The Jakarta Commons Collections Package

1. INTRODUCTION

The Collections 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.

The philosophy of the naming standards is to follow those of java.util.Collections.

2. COLLECTION INTERFACES

Collection interfaces are new types of collections not included in Java. Examples include Bag and SortedBag. These interfaces shall:

• be top level interfaces
• have a name that describes their purpose

3. COLLECTION IMPLEMENTATIONS

Collection implementation are new implementations of collection interfaces. Examples include DoubleOrderedMap and DefaultMapBag. These interfaces shall:

• be top level classes
• have a name that ends with the collection type being implemented
• have a name that describes their implementation
• contain no public inner classes
• only contain the collection implementation, and any methods specific to that implementation

4. UTILITY CLASSES

Utility classes provide additional functionality around an interface and its basic implementations. Examples include CollectionUtils and ListUtils.

Each class shall follow the naming pattern XxxUtils where Xxx relates to the object being returned by the class, for example ListUtils and BagUtils. Variations on a theme (SortedBag as opposed to Bag) will be dealt with in one Utils class. Each Utils class shall:

• be a single, static method based, class
• have a name consisting of the interface name plus 'Utils'
• deal with one collection interface and its variations
• provide methods that decorate the interface with additional functionality
• provide methods that perform useful utility functions on that interface

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, synchronizedMap(Map) or predicatedSet(Set). Occasionally, such construct is awkward and a more suitable adjective can be used instead. For example, lazyList, unmodifiableList.

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.

5. CODING STANDARDS

Commons Collections follows similar style rules to many other Java open source projects, and the Sun conventions. Some specific conventions are:

• No tabs, 4 space indentations
• Curly brackets open at line end
• Else, catch and finally statements after the closing bracket
• Single space after keyword such as if
• Two spaces between parameter name and description in @param
• Generally copy the style of the surounding code

And rememeber, the commons-dev mailing list is there for any discussions or queries about patches or new additions to collections.