2004-02-19 16:41:04 -05:00
|
|
|
<!--
|
|
|
|
|
Copyright 2002-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.
|
|
|
|
|
-->
|
2002-06-28 23:49:01 -04:00
|
|
|
<html>
|
|
|
|
|
<head>
|
|
|
|
|
<title>Developers guide for Jakarta Commons "Collections" Package</title>
|
2004-12-19 16:43:26 -05:00
|
|
|
</head>
|
2002-06-28 23:49:01 -04:00
|
|
|
<body bgcolor="white">
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<div align="center">
|
|
|
|
|
<h1>The Jakarta Commons <em>Collections</em> Package</h1>
|
|
|
|
|
<h2>Developers Guide</h2>
|
2005-02-26 07:55:26 -05:00
|
|
|
$Id$<br />
|
2002-06-28 23:49:01 -04:00
|
|
|
<a href="#Introduction">[Introduction]</a>
|
|
|
|
|
<a href="#CollectionInterfaces">[Collection Interfaces]</a>
|
|
|
|
|
<a href="#CollectionImplementations">[Collection Implementations]</a>
|
|
|
|
|
<a href="#UtilityClasses">[Utility Classes]</a>
|
2004-12-19 16:43:26 -05:00
|
|
|
<a href="#CodingStandards">[Coding Standards]</a>
|
|
|
|
|
<br />
|
|
|
|
|
<br />
|
2002-06-28 23:49:01 -04:00
|
|
|
</div>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<a name="Introduction"></a>
|
|
|
|
|
<h3>1. INTRODUCTION</h3>
|
|
|
|
|
|
|
|
|
|
<p>The <em>Collections</em> package contains a set of Java classes that extend
|
|
|
|
|
or augment the Java Collections Framework. This developers guide seeks to set
|
|
|
|
|
out rules for the naming of classes and methods within the package. The purpose
|
|
|
|
|
of this, as with all naming standards, is to improve the coherency and
|
|
|
|
|
consistency of the whole API.</p>
|
|
|
|
|
|
|
|
|
|
<p>The philosophy of the naming standards is to follow those of
|
|
|
|
|
java.util.Collections.</p>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<a name="CollectionInterfaces"></a>
|
|
|
|
|
<h3>2. COLLECTION INTERFACES</h3>
|
|
|
|
|
|
|
|
|
|
<p>Collection interfaces are new types of collections not included in Java.
|
|
|
|
|
Examples include <code>Bag</code> and <code>SortedBag</code>. These interfaces
|
|
|
|
|
shall:</p>
|
|
|
|
|
<ul>
|
|
|
|
|
<li>be top level interfaces</li>
|
|
|
|
|
<li>have a name that describes their purpose</li>
|
|
|
|
|
</ul>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<a name="CollectionImplementations"></a>
|
|
|
|
|
<h3>3. COLLECTION IMPLEMENTATIONS</h3>
|
|
|
|
|
|
|
|
|
|
<p>Collection implementation are new implementations of collection interfaces.
|
|
|
|
|
Examples include <code>DoubleOrderedMap</code> and <code>DefaultMapBag</code>.
|
|
|
|
|
These interfaces shall:</p>
|
|
|
|
|
<ul>
|
|
|
|
|
<li>be top level classes</li>
|
|
|
|
|
<li>have a name that ends with the collection type being implemented</li>
|
|
|
|
|
<li>have a name that describes their implementation</li>
|
|
|
|
|
<li>contain no public inner classes</li>
|
|
|
|
|
<li>only contain the collection implementation, and any methods specific to
|
|
|
|
|
that implementation</li>
|
|
|
|
|
</ul>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<a name="UtilityClasses"></a>
|
|
|
|
|
<h3>4. UTILITY CLASSES</h3>
|
|
|
|
|
|
|
|
|
|
<p>Utility classes provide additional functionality around an interface and
|
|
|
|
|
its basic implementations. Examples include CollectionUtils and ListUtils.</p>
|
|
|
|
|
|
|
|
|
|
<p>Each class shall follow the naming pattern XxxUtils where Xxx relates to the
|
|
|
|
|
object being returned by the class, for example <code>ListUtils</code> and
|
|
|
|
|
<code>BagUtils</code>. Variations on a theme (<code>SortedBag</code> as opposed
|
|
|
|
|
to <code>Bag</code>) will be dealt with in one Utils class. Each Utils class
|
|
|
|
|
shall:</p>
|
|
|
|
|
|
|
|
|
|
<ul>
|
|
|
|
|
<li>be a single, static method based, class</li>
|
|
|
|
|
<li>have a name consisting of the interface name plus 'Utils'</li>
|
|
|
|
|
<li>deal with one collection interface and its variations</li>
|
|
|
|
|
<li>provide methods that decorate the interface with additional
|
|
|
|
|
functionality</li>
|
|
|
|
|
<li>provide methods that perform useful utility functions on that
|
|
|
|
|
interface</li>
|
|
|
|
|
</ul>
|
|
|
|
|
|
2002-07-02 22:34:09 -04:00
|
|
|
<p>Where the method in a Utils class is a decorator, the name shall consist of
|
|
|
|
|
an adjective followed by the collection type. Typically such adjective is
|
|
|
|
|
formed by appending an -ed suffix (meaning "having"/"characterized by") to the
|
|
|
|
|
word describing the type of decorator. For example,
|
|
|
|
|
<code>synchronizedMap(Map)</code> or <code>predicatedSet(Set)</code>.
|
|
|
|
|
Occasionally, such construct is awkward and a more suitable adjective can be
|
|
|
|
|
used instead. For example, <code>lazyList</code>,
|
|
|
|
|
<code>unmodifiableList</code>.</p>
|
|
|
|
|
|
2003-05-10 11:26:44 -04:00
|
|
|
<p>These decorators should be implemented either as non-public, static,
|
|
|
|
|
inner classes, or as public classes in a subpackage. If a subpackage is used,
|
|
|
|
|
the constructors should be protected and a public static decorate() method
|
|
|
|
|
provided on each class for construction.</p>
|
2002-06-28 23:49:01 -04:00
|
|
|
|
2004-12-19 16:43:26 -05:00
|
|
|
<a name="CodingStandards"></a>
|
|
|
|
|
<h3>5. CODING STANDARDS</h3>
|
2002-06-28 23:49:01 -04:00
|
|
|
|
2004-12-19 16:43:26 -05:00
|
|
|
<p>Commons Collections follows similar style rules to many other Java open source
|
|
|
|
|
projects, and the Sun conventions. Some specific conventions are:</p>
|
2002-06-28 23:49:01 -04:00
|
|
|
|
2004-12-19 16:43:26 -05:00
|
|
|
<ul>
|
|
|
|
|
<li>No tabs, 4 space indentations</li>
|
|
|
|
|
<li>Curly brackets open at line end</li>
|
|
|
|
|
<li>Else, catch and finally statements after the closing bracket</li>
|
|
|
|
|
<li>Single space after keyword such as if</li>
|
|
|
|
|
<li>Two spaces between parameter name and description in @param</li>
|
|
|
|
|
<li>Generally copy the style of the surounding code</li>
|
|
|
|
|
</ul>
|
|
|
|
|
|
|
|
|
|
<p>And rememeber, the commons-dev mailing list is there for any discussions
|
|
|
|
|
or queries about patches or new additions to collections.</p>
|
|
|
|
|
|
|
|
|
|
</body>
|
|
|
|
|
</html>
|
