Developer Information

This document explains key concepts that JChassis developers need to know as well as system and tool requirements for developing JChassis code.

Philosophy

Where do the requirements for JChassis come from? There are no customers so we cannot derive requirements from them. Instead we will take the approach that if we attempt to use JChassis to build reasonably complex applications, then the requirements for JChassis will grow from this.

This process has been bootstrapped by building the a "throw-away" JChassis prototype that includes peer-to-peer extensions including a chat system. Most basic aspect of JChassis that were envisaged for the first release have been included in this prototype.

Some trivial example applications have been developed in parallel with the first JChassis release. Example applications should be designed to exercise the entire range of JChassis functionality and will act both as a source of new ideas for the current and future releases, and also as an addition testing mechanism at the system level.

It is intended that as much as possible of JChassis will run on Java 1.1 VMs, so please keep this in mind when developing new modules. If you really need things like weak references or heavy use of "difficult" collections operations, then you must resort to Java 2. If you just have simple needs stick to 1.1. For example, if you only need simple collections functionality, use a Vector. Always check the 1.1 API to make sure you are not using methods that were added during later VMs.

Quality

Quality is often an afterthought in open source projects (with notable exceptions though). Too many open source innovation have been passed over because they are too obscure, inefficient, or buggy to be easily used.

To be part of the official JChassis release, all modules (and the core) will go through one or more iterations of:

design
design review
implementation of code *and* unit test *and* javadoc
code and test review
system/integration testing

If you don't know what some or all of these mean, then ask.

Developers should announce any change in status of the module they are working on to the jchassis-devel mailing list.

Design will include actual Java interface specifications. These must be though roughly documented.

Design review will be by members of the jchassis-devel mailing list once the design has been allowed. Final decision will be by a vote amongst the project administrators (OK so thats just me at the time of writing :-)). Be warned that if you start writing code before the review is complete, this is OK, but you might need to do a lot of rewriting to meet an revised design.

Code will be documented as it is written, not afterwards. This will not only help you but the other developers who may be trying to integrate their work with your module as it is being built.

Code and test review will be done in the same way as design review.

If you don't agree with the above policies, then you should leave the project immediately. Do not write code and hope that it is somehow so good that an exception will be made. It will be rejected as part of the official release.

It is intended that JChassis will eventually have a "quality rating system" for JChassis modules. This rating will be applied to all modules that are part of the official release, as well as to third party modules at the third parties request. The rating system will indicate:

the stability of the interface (ie. how likely is it to change)
the performance of the implementation (typically, speed and memory)
the bugginess of the implementation in typical applications
the completeness of usage documentation
the clarity of usage documentation
the completeness of design documentation
the clarity of design documentation
the coverage of unit test code
the appropriateness of unit test code (does it really exercise the interfaces)

The table of modules vrs. rating will be published on the JChassis web site in the hope that it will encourage developers to develop quality modules and also so that JChassis users can find the "best-of-the-best" modules for their projects. The latter consideration avoid negative publicity for JChassis which could result from users encountering buggy third party modules and assigning the blame to JChassis.

Methodology

No particular methodology is preferred for JChassis development. If you can present your designs in a coherent form, whether it be text, UML diagrams, or whatever, as long as it conveys what the other developers need to know, it is OK. If you are going to send diagrams or complex documents, make sure it is an open format that can be viewed under multiple OSs (not just Windows). In fact, the same applies to any documents you submit to the project.

General methodology guidelines are:

make simple things simple to do - for example, don't make a nice simple interface that works for most people more complex to satisfy everyone, consider an additional interface and leave the simple one alone (but alway try to reuse *code*)
document copiously - at least for the benefit of others if not yourself
bugs are a *much* *much* easier to fix as design stage rather than late in the release or after the release
that extra 10-20% of effort to make code reusable will save many times that of effort later down the track

More guidelines may be added over time.

System Requirements

Any machine that can run the tools specified below will do.

Tools

You will need:

Sun's JDK 1.4.1 or higher (API doc also recommended)
A Java 1.1 JDK: IBM's JDK 1.1.8 works well.
CVS
a source code editor
Apache Ant 1.5.3-1 or higher with the JUnit 3.8.1 or higher "junit.jar" file installed in the ant "lib" subdirectory
to convert the SDK documentation (user guide, module guide, factsheet, etc.) to HTML and PDF you will need to put the following JAR files from Apache FOP into your Ant lib directory: fop.jar, avalon.jar and batik.jar (not sure if the last one is needed); you will also need to put the file xalan2.jar from Apache Xalan into your Java 2 JDK's jre/lib/endorsed directory: Xalan version 2.5.0 works: note that you can't build the the SDK without these.

Your source code editor should be set up to NOT use TAB characters, but to insert spaces instead. See the "coding conventions" below.

It should be noted that a good CVS client will translate line termination characters to suit the environment it is working in. A common problem is that files on a SMB mount ("shared folder") have different line termination characters to what the CVS client expects because the SMB mounted system is a different OS. CVS then dutifully checks in these alien line termination characters. Checking these in will result in disastrous "cvs diffs" where every line in the file seems to have changed, albeit invisibly. The same can happen if files are moved from one OS to another without translating the line terminations. This might be just the result of moving the files to an SMB mounted filesystem. If you work on multiple OSs, please be careful. Check cvs diffs *before* committing in files. Ask someone if any of the above is unclear.

If you are interested in system testing, you should obtain some other JDKs, not necessarily Java 2 either. Examples are Kaffe's Java 1.1 VM, Sun's JDK 1.1, Sun's J2ME, etc.

Coding and Javadoc Conventions

See here.

$Id: developer_info.html,v 1.4 2003/05/23 23:53:16 stainsby Exp $