Package naming convention in a mixed Java and OSGi world

The "standard" before OSGi was to move all internal stuff into *internal* packages.

IBM uses the *internal* approach in the ready for rational program:

Requirement: General 2.5

a)      Provide a list of non-public Eclipse interfaces and the methods used by your offering...

This means that IBM exports *internal* packages and asks for a rationale if you use one of its internal classes. This approach enables you to:

1. point the programmers to the correct way to use the software
        OR 
2. move the class out of internal and into the official API.

In OSGi, if you do not export a package, the programmer cannot access it. However, this breaks the important aspect that programmers sometimes use your classes in ways you did not envision. So you also export packages that could be interesting and only hide the absolutely non API packages.

However, if you want to use the jar outside of OSGi then there is no way of hiding the absolute non-API packages and also no way of recognizing that the package is off limits. 

Conclusion: there should be a new naming convention providing for three levels of package visibility. 

1. API,  dom.organization.soandso
   
2. Not intended to be API dom.organization.internal.soandso
3. Absolutely not API dom.organization.private.soandso