Re: [equinox-dev] dependency on org.osgi.annotation?

[BJ Hargrave <hargrave@xxxxxxxxxx>]

> From: Stephan Herrmann <stephan.herrmann@xxxxxxxxx>

> I was asking about the following scenario:
> 
> User has an arbitrary plugin project which obviously depends on o.e.osgi.

Well I would say that no one should depend upon org.eclipse.osgi.
It is an implementation of the OSGi core spec. If you are writing bundles,
then you are dependent on the OSGi API and should put osgi.core and possibly
osgi.annotation on your compile path. These jars are available from OSGi
Alliance website, Maven Central, JCenter, ... and include their source.

> I'm not speaking of building o.e.osgi, but about consuming.
> 
> In the workspace s/he has references to o.e.osgi as jar with source
> attachment.
> 
> When the user browses / inspects types from o.e.osgi, JDT uses the
jar plus
> its source attachment in order to present javadoc hovers and such.
> Behind the scenes javadoc computation uses the sources and compiles
them
> on the fly in order to provide semantic, rather than syntactic information.
> 
> The problem is: this in-memory compilation of attached sources fails
due
> to unresolved references to an annotation type "ProviderType".
> Normally, JDT's javadoc hovers would know the fully qualified name
of
> any annotations and even support navigation to the type. For ProviderType
> this is not possible, because that name cannot be resolved.
> Still worse, for the javadoc of any API method that mentions another
type
> which in turn is annotated as @ProviderType this transitive lookup
fails,
> causing JDT to abort this compilation because obviously our classpath
> is incorrect. Hence semantic information for javadoc hovers may just
be
> unavailable for affected elements.

Perhaps JDT is a bit too sensitive for what it not
a real compilation but instead just providing hover information.

> 
> BTW, when I classified ProviderType as API, I certainly wasn't implying
> "runtime" API. These things are compile time API, just like
@NonNull
> (which, too, has retention CLASS).

It is necessary to compile the source. But what you
are describing is not really compiling the source but using the source
to provide some hover information. So missing things should not blow the
whole thing up since it is not a real compilation.

>  If an API exposes annotations, the
> declaration for that annotation must be visible for compilation of
client
> source. If the annotation would be relevant only while compiling o.e.osgi
> itself, then I would deem a retention SOURCE much more suitable. By
saying
> "CLASS" you are making this annotation *visible* to *compilation*
of client
> sources, but you are not telling, what the annotation is. In terms
of API
> Tools this should be considered as an API leak.
> But these are semantic issues, not relevant to the tooling problem
at hand.
> 
> IMHO, either the source attachment is incomplete or the bundle must
declare
> a dependency on the artifact containing the annotation declaration.

It is wrong to declare a dependency from org.eclipse.osgi
to the osgi.annotations since such a dependency is a runtime dependency
and there is in fact no runtime dependency on these annotations. Just a
compile-time dependency. And in the situation you describe, the source
code does not really need to be compiled.

> 
> The question is: how do you advise JDT to perform its on-the-fly compilation
> while working on a client project depending on o.e.osgi, which is
available
> as jar + source attachment? 

How about don't fail when you can't find something
just to make hover information? :-)

> Currently, JDT concludes that the sourceattachment
> of o.e.osgi is broken.
> 

--

BJ Hargrave Senior Technical Staff Member, IBM OSGi Fellow and CTO of the OSGi Alliance hargrave@xxxxxxxxxx

office: +1 386 848 1781 mobile: +1 386 848 3788