7

jre comes with many libraries in rt.jar one of which is com.sun.istack.internal*. I needed the documentation of com.sun.istack.internal.Nullable(which I found being used by google in its CacheBuilder) and first I thought was to go to docs.oracle.com to find its documentation and there I found nothing about it. Next went to source folder sourced with jdk and I didn't find com name entity in the said folder. Next I take a look at the jre7 release and take a look at all the packages and class and found no mention of Nullable there. Though SO had one mention of it, but nothing concrete. I am still puzzled where to get its documentaion and src if needed. I even looked legacy sun api documentation at oracle but nothing mentioned about it. where does oracle document there policy about ported packages and their being standard or not-standard.They must have documented it somewhere it is just that I'm taking too much of time to get there.

Please point me there.

EDIT: Actually the javax.annotation.Nullable is being used in google CacheBuilder and not com.sun.istack.internal.Nullable. Also for someone who may face this issue: javax.annotation.Nullable is not part of Java SE as of now, and it is being ported in jsr305 jar. So if you are planning to use CacheBuilder or just going through its code, do add jsr305 jar in your class path, else eclipse get confuse and will point you to com.sun.istack.intenal.Nullable when ever you hover your cursor over Nullable.

Community
  • 1
  • 1
mawia
  • 9,169
  • 14
  • 48
  • 57

3 Answers3

12

Guava doesn't use com.sun.istack.internal.Nullable. Everything that is not documented in the official Java SE javadoc is internal code, and should not be used in applications.

You're probably looking for javax.annotation.Nullable, which is part of JSR305.

Arjan Tijms
  • 37,782
  • 12
  • 108
  • 140
JB Nizet
  • 678,734
  • 91
  • 1,224
  • 1,255
  • @Override public boolean equals(@Nullable Object obj) { if (this == obj) { return true; } One snippet from com.google.common.base.Equivalence and Equivalence is full of use of this annotation. – mawia May 20 '12 at 13:54
  • See http://docs.guava-libraries.googlecode.com/git-history/v12.0/javadoc/src-html/com/google/common/base/Equivalence.html#line.26: javax.annotation.Nullable, just as I told you. – JB Nizet May 20 '12 at 13:58
  • Well, javax.annotation.Nullable doesn't seem to be provided by JSE, but is there in JSR305, eclipse got terrifically confused(hovering cursor over Nullable, it will point you to com.sun.istack.internal.Nullable), since I didn't had jsr305. As it could not resolve javax.annotaion.Nullable, it confused Nullable to be that of com.sun.istack.internal.Nullable. – mawia May 20 '12 at 15:12
4

Here is a link to the source code:

(This link may break in the future, but you should be able to find an equivalent using a Google search.)

The reason that you can't find the source code or javadocs in the standard JDK / JRE distributions is that this is a INTERNAL class. There is a long-standing Oracle / Sun policy of discouraging developers from writing code that is dependent on Java internal classes.

FWIW - this is just an annotation, and the meaning is pretty much what the class name implies.


UPDATE - Apparently, the real cause of this confusion is that you didn't include the JSR305 jar in your buildpath. It is a dependency for CacheBuilder. Eclipse classname completion is then doing its best ... but failing.

Stephen C
  • 698,415
  • 94
  • 811
  • 1,216
  • It was written by Kohsuke Kawaguchi! Since when was he writing code for the JDK? – Tom Anderson May 20 '12 at 13:54
  • He worked at Sun before it was bought by Oracle. Why wouldn't he write code for the JDK? Hudson Jenkins was written on his spare time, AFAIK. – JB Nizet May 20 '12 at 13:56
  • Thanks, I know it is annotation. And even then we will like to have its documentation. Refer comment to JB Nizet Post. – mawia May 20 '12 at 13:56
  • Since 2001 apparently - http://weblogs.java.net/blog/kohsuke/archive/2010/04/05/good-bye-sunoracle – Stephen C May 20 '12 at 13:57
  • @mawia - *"And even then we will like to have its documentation."* - Well now you can have it. Just follow the link in my answer. If the lack of published javadoc is a annoying you, complain to Google. They are the ones who decided to use an internal annotation rather than defining or reusing a non-internal annotation with that semantic. – Stephen C May 20 '12 at 13:59
  • @StephenC javax.annotation.Nullable is not part of JSE but is being provided JSR305 and since it was not their in classpath, eclipse got confused it with com.sun.istack.internal.Nullable...refer to comment on JBNizet post.So you were right google is not using com.sun...Nullable. – mawia May 20 '12 at 15:16
  • You can hide packages from showing up in auto-completion in eclipse. *Windows->Preferences->Java Appearance->Type Filter*. I ad usually add `com.sun.*`. – Adam Gent May 16 '13 at 15:28
  • @VictorStafusa - *"(This link may break in the future, but you should be able to find an equivalent using a Google search.)"* - Did Googling work for you? If you can be bothered to find the new source link and tell me what it is, I'll update my answer. – Stephen C Jun 26 '15 at 02:52
  • Yes, it is easily found in [Grepcode](http://grepcode.com/file/repository.grepcode.com/java/root/jdk/openjdk/8u40-b25/com/sun/istack/internal/Nullable.java/). I just thought that you would like to know that the link is definitively broken. – Victor Stafusa - BozoNaCadeia Jun 26 '15 at 13:27
0

It is said that It's Oracle's intent that these classes be inaccessible at compile-time.

Below is my workaround in case adding a modern jar for those annotation is not allowed.

If using Gradle, add:

compileJava.options.compilerArgs << "-XDignore.symbol.file"

If using Ant, change the javac tag like:

    <javac srcdir="src" destdir="${classes.dir}" classpathref="classpath" memoryinitialsize="512m" memorymaximumsize="1024m" fork="true">
        <compilerarg line="-encoding utf-8 -XDignore.symbol.file"/>
        <exclude name="test/**"/>
    </javac>
RAY
  • 2,201
  • 2
  • 19
  • 18