![]() | ![]() |
Apache > Jakarta > Cactus > Participating | Docs for: v1.7.2 | v1.7 Last update: August 30 2007 |
Cactus API design rules
Most of these rules are extracted from the excellent
How to Use the Eclipse API article
by Jim des Rivieres.
Public APIs/SPIsTo try to draw the line more starkly, the code base for the platform is separated into API/SPI and non-API/non-SPI packages, with all API/SPI elements being declared in designated API/SPI packages.
org.apache.cactus.foo.* - API org.apache.cactus.spi.foo.* - SPI org.apache.cactus.internal.foo.* - not API; internal implementation packages org.apache.cactus.sample.* - not API; these are examples Everything else is considered internal implementation detail and off limits to all clients. Legitimate client code must never reference the names of non-API/non-SPI 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:
No public methods in internal packagesIn order to preserve binary compatibility, no user public API/SPI must be located in internal packages. No public class exposed as much as possible
Only interfaces should be exposed in the public API/SPI (as much as
possible). This will satisfy binary compatibility and allow future
extensibility. Of course, in some cases, it is not possible. For
example, |