You are viewing a plain text version of this content. The canonical link for it is here.
Posted to cactus-dev@jakarta.apache.org by vm...@apache.org on 2004/04/11 16:50:14 UTC
cvs commit: jakarta-cactus/documentation/docs/xdocs/participating apis.xml navigation.xml
vmassol 2004/04/11 07:50:14
Modified: documentation/docs/xdocs sitemap.xml
documentation/docs/xdocs/participating navigation.xml
Added: documentation/docs/xdocs/participating apis.xml
Log:
Added page on Cactus API/SPI design rules
Revision Changes Path
1.78 +7 -0 jakarta-cactus/documentation/docs/xdocs/sitemap.xml
Index: sitemap.xml
===================================================================
RCS file: /home/cvs/jakarta-cactus/documentation/docs/xdocs/sitemap.xml,v
retrieving revision 1.77
retrieving revision 1.78
diff -u -r1.77 -r1.78
--- sitemap.xml 24 Mar 2004 18:31:24 -0000 1.77
+++ sitemap.xml 11 Apr 2004 14:50:14 -0000 1.78
@@ -30,6 +30,12 @@
<!-- Internal links (sorted alphabetically by id) -->
<!-- ================================================================== -->
+ <resource id="apis" target="participating/apis.html"
+ name="Public API/SPIs">
+ Explains how the Cactus project differentiates between public API/SPI
+ and internal implementation classes.
+ </resource>
+
<resource id="build_result" target="participating/build_result.html"
name="Nightly Build Results">
Aggregated links to the results of the nightly builds.
@@ -460,6 +466,7 @@
<external id="cvs" url="http://jakarta.apache.org/site/cvsindex.html"/>
<external id="easymock" url="http://easymock.org"/>
<external id="eclipse" url="http://www.eclipse.org"/>
+ <external id="eclipse_api_usage" url="http://www.eclipse.org/articles/Article-API%20use/eclipse-api-usage-rules.html"/>
<external id="eblox" url="http://www.eblox.com"/>
<external id="french" url="http://www.ressources-java.net/cactus"/>
<external id="gump" url="http://jakarta.apache.org/gump/"/>
1.10 +1 -0 jakarta-cactus/documentation/docs/xdocs/participating/navigation.xml
Index: navigation.xml
===================================================================
RCS file: /home/cvs/jakarta-cactus/documentation/docs/xdocs/participating/navigation.xml,v
retrieving revision 1.9
retrieving revision 1.10
diff -u -r1.9 -r1.10
--- navigation.xml 24 Mar 2004 18:31:24 -0000 1.9
+++ navigation.xml 11 Apr 2004 14:50:14 -0000 1.10
@@ -38,6 +38,7 @@
<item id="todo"/>
<item id="build_result"/>
<item id="coding_conventions"/>
+ <item id="apis"/>
<item id="cvs" label="CVS"/>
<item id="howto_build"/>
<item id="coverage"/>
1.1 jakarta-cactus/documentation/docs/xdocs/participating/apis.xml
Index: apis.xml
===================================================================
<?xml version="1.0"?>
<!--
* ========================================================================
*
* Copyright 2004 The Apache Software Foundation.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*
* ========================================================================
-->
<document id="apis">
<properties>
<title>Public API/SPI vs internal classes</title>
</properties>
<body>
<section title="Cactus API design rules">
<note>
Most of these rules are extracted from the excellent
<a href="ext:eclipse_api_usage">How to Use the Eclipse API</a> article
by Jim des Rivieres.
</note>
<section title="Public APIs/SPIs">
<p>
To 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.
</p>
<ul>
<li>
<strong>API/SPI package</strong>: a Java package that contains at
least one API/SPI class or API/SPI interface. The names of API/SPI
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/SPI
packages may legitimately appear in client code. For the Cactus
project, these are:
</li>
<source><![CDATA[
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
]]></source>
<li>
<strong>API/SPI class or interface</strong>: 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.
</li>
<li>
<strong>API/SPI method or constructor</strong>: a public or
protected method or constructor either declared in, or inherited
by, an API/SPI class or interface. The names of API/SPI methods
may legitimately appear in client code.
</li>
<li>
<strong>API/SPI field</strong>: a public or protected field either
declared in, or inherited by, an API/SPI class or interface. The
names of API/SPI fields may legitimately appear in client code.
</li>
</ul>
<p>
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:
</p>
<ul>
<li>
Stick to officially documented APIs/SPIs. Only reference packages
that are documented in the published API/SPI Javadoc for the
component. Never reference a package belonging to another component
that has "internal" in its name --- these are never API/SPI. Never
reference a package for which there is no published API/SPI Javadoc
--- these are not API/SPI either.
</li>
</ul>
</section>
<section title="No public methods in internal packages">
<p>
In order to preserve binary compatibility, no user public API/SPI
must be located in internal packages.
</p>
</section>
<section title="No public class exposed as much as possible">
<p>
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, <code>ServletTestCase</code> has to be a class as it
contains logic required to transform a JUnit test case into a Cactus
test case. Same for <code>ServletTestSuite</code> as the way to use
it in a JUnit <code>suite()</code> method is to create an instance
of it.
</p>
</section>
</section>
</body>
</document>
---------------------------------------------------------------------
To unsubscribe, e-mail: cactus-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: cactus-dev-help@jakarta.apache.org