Bug 129401 - [doc] make it explicit whether an API requires an OSGi container
Summary: [doc] make it explicit whether an API requires an OSGi container
Status: RESOLVED FIXED
Alias: None
Product: Platform
Classification: Eclipse Project
Component: Runtime (show other bugs)
Version: 3.2   Edit
Hardware: PC Windows XP
: P3 normal (vote)
Target Milestone: 3.2   Edit
Assignee: Oleg Besedin CLA
QA Contact:
URL:
Whiteboard:
Keywords: api
Depends on:
Blocks:
 
Reported: 2006-02-24 16:03 EST by Rafael Chaves CLA
Modified: 2006-05-10 14:21 EDT (History)
2 users (show)

See Also:

Attachments
Patch adds Javadoc explicitly stating if OSGi presence is required (46.62 KB, patch)
2006-04-28 10:57 EDT, Oleg Besedin CLA 		no flags Details | Diff
Patch adds Javadoc explicitly stating if OSGi presence is required (47.41 KB, patch)
2006-05-08 15:59 EDT, Oleg Besedin CLA 		no flags Details | Diff
Patch to be applied against the HEAD (38.85 KB, patch)
2006-05-09 17:05 EDT, Oleg Besedin CLA 		no flags Details | Diff
Show Obsolete (1) View All Add an attachment (proposed patch, testcase, etc.)

Note You need to log in before you can comment on or make changes to this bug.
Description Rafael Chaves CLA 2006-02-24 16:03:02 EST 
I really appreciate the Runtime refactoring effort and the ability of using cool pieces of Eclipse from regular Java apps. But from the API it is impossible to tell whether it would work for an ordinary Java app, outside the OSGi container. The only way of being sure is to try and test it.

So I ask that for those API the intended use includes calling it from plain Java apps, the spec explicitly spell that out. Otherwise clients might end up relying on an implementation detail, and be broken later on.
Comment 1 Pascal Rapicault CLA 2006-02-24 16:44:21 EST 
I agree with that. Marking for 3.2 so we don't forget about this issue and discuss it.
Comment 2 Jeff McAffer CLA 2006-04-24 15:03:04 EDT 
yes, we need to think about how to doc this.
Comment 3 Oleg Besedin CLA 2006-04-27 16:44:23 EDT 
I plan to add the following comments to the Javadoc of APIs in equinox.common and equinox.registry plugins (those are the only two plugins expected to provide funcitonality without OSGi):

This class/interface utilizes functionality provided by OSGi and can't be used without OSGi present.

or 

This class can be used without OSGi.

Due to the large volume of changes, please comment soon if you'd like to modify the text to be added to Javadocs.
Comment 4 Oleg Besedin CLA 2006-04-28 10:57:41 EDT 
Created attachment 39776 [details]
Patch adds Javadoc explicitly stating if OSGi presence is required
Comment 5 Oleg Besedin CLA 2006-05-08 15:59:26 EDT 
Created attachment 40641 [details]
Patch adds Javadoc explicitly stating if OSGi presence is required

Updated wording of the Javadoc
Comment 6 John Arthorne CLA 2006-05-08 16:12:22 EDT 
Updating milestone for unfinished doc work
Comment 7 Oleg Besedin CLA 2006-05-09 10:15:35 EDT 
Patch for the Javadoc is applied.
Comment 8 Jeff McAffer CLA 2006-05-09 14:40:26 EDT 
did someone review this?

This is API stuff (not changes but clarifications) but still should be reviewed for long term impacts etc.
Comment 9 Oleg Besedin CLA 2006-05-09 17:05:55 EDT 
Created attachment 40879 [details]
Patch to be applied against the HEAD

The patch takes a different approach and groups APIs into two categories:
a) APIs that don't require OSGi running
b) APIs that expect OSGi to be running

The APIs in (a) get this line in the Javadoc:

      This class[interface] can be used without OSGi running.

and APIs from (b) don't get anything written in the Javadoc about OSGi requirements.

Note that APIs from group (a) might still need to consume classes fdrom OSGi. At present, the collection of OSGi classes used by the equinox.registry and equinox.common APIs from group (a) can be found in the plugin org.eclipse.equinox.supplement.
Comment 10 DJ Houghton CLA 2006-05-10 13:31:10 EDT 
This looks good to me.
Comment 11 Oleg Besedin CLA 2006-05-10 14:21:41 EDT 
Thanks, DJ! Patch applied.