Best practice for controlling access to a ".internal" package

Question

I write Eclipse plugins and export some classes as an API while wanting to restrict access to other classes.

I follow the common Eclipse practice of separating these classes into a ".internal" subpackage.

However, then I can't use "package" or default level access on these classes since many of them need to be used by the classes I'm exporting.

What is the best practice for preventing or discouraging users of my API from using these classes for their own purposes? Is there an automatic checker?

I admit that I've dabbled in using some of Eclipse's internal classes when I had no choice :)

Clarification: I have a similar need with non-plugin code.

Answer 1

Isn't it just a case of updating the META-INF/MANIFEST.MF to being a plug-in osgi project (if it's not already?). It should look something like:

Manifest-Version: 1.0
Bundle-ManifestVersion: 2
Bundle-Name: My-plugin
Bundle-SymbolicName: com.mycompany.mypluginname
Bundle-Version: 1.0.0
Bundle-Vendor: MyCompany
Bundle-RequiredExecutionEnvironment: JavaSE-1.6
Service-Component: 
Import-Package: org.apache.log4j;version="1.2.14" (, separated etc)
Export-Package: com.mycompany.mypluginname.myapipackage;version="1.0.0"

And then nicely omit the .internal package. The platform should do the rest.

By the way, you then use the Import-Package: in any dependent bundles, plugins etc, rather than depending on the jar/project (which is the old, sucky way which doesn't work - as you're finding).

This gives you massive de-coupling of your code dependencies. If you decide that your plugin code should belong in a different jar/bundle, you just move individual packages, and make the new bundle/plug-in export it. Since the client bundles just import the package from "the cloud" (cloud being the OSGi platform), you can move code a lot more freely.

Note: As mentioned in the comments, you don't need to be running your apps in OSGi to get this "benefit". Eclipse can compile it's code under OSGi package restrictions, and your build/server can run in "the unprotected world". e.g. the OSGi manifests don't enforce anything to 3rd parties (who wish to use .internal), but provide "notifications" and restrictions to those that want them.

Answer 2

Unless you have to handle somebody else's untrusted code using your trusted library, please don't restrict it.

Needing internal/package access sometimes indicates a failure of your API design, and you can't know until long afterwords.

Make it public, name it InternalWhatever, and live with it.

Answer 3

For plugin projects: Use the Manifest setup that Stephen mentions. (You can also edit this through the "Runtime" page of the Manifest editor. Note that if you would like to only expose a package to specific plugins you can do that as well using

Export-Package: com.javadude.foo;x-friends:="com.javadude.fee"

For non-plugin projects: Use separate source folders to define what is exported from your project.

1. Right-click project and choose New Source Folder (perhaps name it "internal-source")
2. Right-click project and choose Properties
3. Go to Java Build Path
4. Click the Order and Export tab
5. Uncheck the source folders you do not want to export

Only the source folders that are checked under "Order and Export" will be added to the classpath of referencing projects.