Hi, I'd like to perform a full overhaul of our package organization. The reason is that we are currently not showing our users what API is public and what API is not public. Unfortunately, Java does not provide a built-in solution for this.
I'd like to propose to use the scheme used in Eclipse development (see http://www.eclipse.org/articles/Article-API%20use/eclipse-api-usage-rule s.html). Paraphrasing Jim: ----- proposal start here ----------- To try to draw the line more starkly, the code base for the platform is separated into API and non-API packages, with all API elements being declared in designated API packages. - API package: a JavaT package that contains at least one API class or API interface. The names of API packages are advertised in the documentation for that component; where feasible, all other packages containing only implementation details have "internal" in the package name. The names of API packages may legitimately appear in client code. For the Cactus project, these are: org.apache.cactus.foo.* - API org.apache.cactus.foo.internal.* - not API; internal implementation packages org.apache.cactus.sample.* - not API; these are examples - API class or interface: a public class or interface in an API package, or a public or protected class or interface member declared in, or inherited by, some other API class or interface. The names of API classes and interfaces may legitimately appear in client code. - API method or constructor: a public or protected method or constructor either declared in, or inherited by, an API class or interface. The names of API methods may legitimately appear in client code. - API field: a public or protected field either declared in, or inherited by, an API class or interface. The names of API fields may legitimately appear in client code. Everything else is considered internal implementation detail and off limits to all clients. Legitimate client code must never reference the names of non-API elements (not even using Java reflection). In some cases, the Java language's name accessibility rules are used to disallow illegal references. However, there are many cases where this is simply not possible. Observing this one simple rule avoids the problem completely: - Stick to officially documented APIs. Only reference packages that are documented in the published API Javadoc for the component. Never reference a package belonging to another component that has "internal" in its name---these are never API. Never reference a package for which there is no published API Javadoc---these are not API either. ------- end of proposal ----------- Committers, do you agree to refactor our packages to follow these rules? Here's my +1 Thanks -Vincent --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
