Date: 2004-02-13T04:25:51
Editor: VincentMassol <[EMAIL PROTECTED]>
Wiki: Jakarta Cactus Wiki
Page: ApiDesignRules
URL: http://wiki.apache.org/jakarta-cactus/ApiDesignRules
no comment
New Page:
#pragma section-numbers off
= Cactus API design rules =
The rules below are a proposal for Cactus 1.6.
== Public APIs ==
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 Java 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.
== No public methods in internal packages ==
In order to preserve binary compatibility, no user public API must be located in
internal packages.
== No public class exposed as much as possible ==
Only interfaces should be exposed in the public API (as much as possible). This will
satisfy binary compatibility and allow future extensibility. Of course, in some cases,
it is not possible. For example, ServletTestCase has to be a class as it contains
logic required to transform a JUnit test case into a Cactus test case. Same for
ServletTestSuite as the way to use it in a JUnit suite() method is to create an
instance of it.
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
