SimpleDBM Coding and Design Principles

Modular design

SimpleDBM is broken down into distinct modules. Each module implements a particular sub-system, and is contained in its own package. All module packages are located under the org.simpledbm namespace. Example, org.simpledbm.locking.

Each modules has a public API, which is specified via a set of Java interfaces. Classes must not be used as part of the public API, though there are a few exceptions.

The module implementation is always contained in a package named org.simpledbm.{module}.impl. Example, org.simpledbm.locking.impl.

To make the modules reusable and as independent of each other as possible, the interface of a module is deliberately specified in general terms. Where possible, the direct dependence between modules is avoided. If two modules are dependent, then the only permissible way for one module to interact with another is to go via the public API. Modules are not allowed to depend upon implementation specifics of other modules.

Documentation

Most of the documentation for SimpleDBM is incorporated as Javadoc comments within the source code, and in package and overview documents. The aim is to keep the documentation as close to the source code as possible.

Being an educational project, producing good documentation is high priority.

Java coding standards

Heavy use is made of the new concurrency packages in Java 5.0. Enums are used where appropriate. SimpleDBM does not define any Generic classes itself, but makes liberal use of Java 5.0 Generic classes.

Fine grained thread locking is used to maximise concurrency. Using coarse grained locking would have simplified the code, but would not have provided an opportunity for exploring various techniques for fine-grained locking. Deadlock is avoided by careful ordering of locks.

Memory manangement is left to the Garbage Collector. Rather than using Object pools, SimpleDBM encourages the use of short-lived objects, on the basis that this aids the garbage collector in reclaiming space more quickly. The aim is to keep permanently occupied memory to a low level.

Only checked Exceptions are used. Each module defines its own Exception hierarchy. Exceptions are always handled or passed up the stack - if they are ignored then this is documented in the code. Care is taken to report Exceptions properly. All error messages are given error codes.

Particular attention is paid to cleaning up of resources. To ensure that resources are cleaned up during normal as well as exceptional circumstances, finally blocks are used.

Debug messages are used liberally - and are executed conditionally so that if debug is switched off, there is minimal impact on performance.

Third party libraries

To void license compatibility issues, and to reduce dependency on third-party libraries, SimpleDBM makes little or no use of any external libraries. A custom wrapper is used for logging, which uses the Java logging API underneath.

Test Cases

Each module is accompanied with JUnit test cases.

Release schedule

The system is designed so that each module is usable once it is delivered. This means that although the full system has not yet been constructed, the individual modules can be used as soon as they are available. See the Status page for information about availability of modules.


Copyright © 2005 by Dibyendu Majumdar.