The Patternity Distribution

Patternity is composed of 2 parts: the code generation doclet and the pattern documentation taglet. These two parts are in the same jar archive patternity.jar.

System requirements

Patternity requires a properly configured JDK or JRE version 1.4 or later on your system with the javadoc parser. It may work with other versions, except for the pattern documentation taglet which requires the 1.4 javadoc parser due to the taglet API. Your classpath must include tools.jar.

Installation

Patternity comes as a single .zip file. Unzip this file into a directory of your choice, referred to as <patternity_root>.

Usage - documentation

To run the Patternity documentation in addition to the normal javadoc documentation on your sources, run javadoc with the -taglet option:

javadoc -private -d your/destination/path/to/javadoc -taglet com.docletpatterns.core.PatternTaglet -tagletpath <patternity_root>patternity.jar your/path/to/package1 your/path/to/package2 ...

Usage - code generation

To run the Patternity code generation on your sources, run javadoc with the -doclet option:

javadoc -private -doclet com.docletpatterns.core.Doclet -docletpath <patternity_root>patternity.jar your/path/to/package1 your/path/to/package2 ...

The -private option tells javadoc to include all classes and members. You could also set -protected (default setting) or -public to only include public classes and members.

The batch files patternity-documentation.bat and patternity-generation.bat included in the distribution give an example of use in Windows environment. For more information about javadoc, doclets and taglet, see:

http://doclet.com/

Getting Started

A simple example

Open or create a plain java class MyClass.java, and add a field with some javadoc comment and two Patternity tags (these are non-pattern tags, just coding idioms):

/**
* this is my name
* @get
* @set
*/
protected String name;

Now run the Patternity doclet as described in the previous chapter. You can now see that a getter and a setter methods have been added to your code. Now run it again, and check there is no difference since Patternity will not generate methods that already exist.

see source code...

Now let us dive into real patterns. Pattern-driven code generation in Patternity is very field oriented, since fields describe many information by their own, that prevents you from specifying them.

Let us create a singleton for our class. Add a static field to the class with the comment @pattern Singleton:

/**
* @pattern Singleton
*/
protected static MyClass mySingleton = null;

Run Patternity, and you can see the singleton method added to the code.

Now let us make this class a Proxy to another class or interface.

/**
* @pattern Proxy
*/
protected AnotherClass myProxy = null;

Run Patternity, and you can see that every public method from the proxy-ed class have been added to the code, with complete and working implementation.

see source code for the if proxy...

 

Using parameters

This works the same for other patterns. However there are a few patterns that require some additional information to be given. The Composite pattern for example, when implemented through a Collection, needs to know the Component interface, that must be specified as a parameter:

/**
* @pattern Composite component=MyNodeInterface
*/
protected List children = new ArrayList();

see source code for the composite...

 

The syntax for additional parameters is key=value (no space).

To implement a visitor for every class of an object model, create your visitor class, and add the @pattern tag, with two optional parameters:

/**
* @pattern Visitor package=myproject.mydom node=AbstractNode
*/
public class MyVisitor …{

From this tag, Patternity will generate visit(…) methods for every non-abstract, non-interface class of the package “mydom” that implements or extends the node “AbstractNode”. This may save time.

see source code for the visitor...

 

Re-generate the code

As Patternity never generates a method that already exists, therefore to have a method generated again you need to remove it or to embed it into comments before running Patternity.

Modify the generated code

Once the code has been generated you can edit it as you like, your modifications will be kept. The tool just helps you in writing the painful code for you, but you are always the master of the code.

Add pattern documentation to the javadoc

Simply run the javadoc with the Patternity taglet and every class that contains pattern information (at class, field or method level) will present this information in its class description, with links to the pattern description in an html file.

Currently, this file is called designpatterns.html and should be copied into a subdirectory called "reference" in your javadoc destination directory. This file should have anchors #patternname to be linked from the pattern documentation in the classes.

!         Due to taglet API limitations, only classes with @pattern at the class level are processed for documentation, even if they have fields or methods tagged with @pattern. To overcome this limitation Patternity should be written as a doclet, not as a taglet, and this would prevent you from using any custom doclet for your javadoc documentation.

Therefore, for classes to be documented you must add an empty @pattern at the class level if there is not already one.

Supported design and coding patterns

For up-to-date design and coding patterns list and reference, see:

http://patternity.com/patterns.php

Features and feedback

Because pattern-driven and tag-driven issues are pretty new, Patternity needs feedback from real users to know in what direction to further improve it. Special feedback is expected in usability and documentation formatting (more natural language, or more bullets, more keywords… ?)

Bug report, features requests and support queries can be handled at:

https://sourceforge.net/tracker/?group_id=68092

 

The Patternity team.