Re: [Proposal/Vote] Breaking API in Cactus 1.6

[Nicholas Lesiecki <nd...@yahoo.com>]

I'm +1 for this refactoring, though I probably won't have time to help.

Cheers,
Nick

On 10/31/03 1:00 PM, "Vincent Massol" <vm...@pivolis.com> wrote:

> 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: cactus-dev-unsubscribe@jakarta.apache.org
> For additional commands, e-mail: cactus-dev-help@jakarta.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: cactus-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: cactus-dev-help@jakarta.apache.org