Open Java UML Project

This project aims to improve the productivity of developers and reduce their workload by providing a simple and effective means of producing and maintaining design diagrams. The intention is to address the short comings of using typical drag and drop diagram editors that I experienced whilst working on large (and small) Java development projects. The overall idea is to give developers a Java API that they can use to produce diagrams, whilst benefiting from the same development practises and conventions that have evolved to improve the quality of software development.

Using typical diagram editors, the diagrams are completely seperate from the code they represent. This means developers need to know how to locate the diagram(s) that represent the code they are working on. It also means that there is a disconnect between the diagrams and the code meaning the diagrams can (and often do) get out of sync with the code after a few defects and change requests have been actioned on the code. Generally work practises including peer reviews aim to avoid this however this imparts additional workload on developers and due to time pressures this system often breaks down and becomes less effective.

By using a Java API to render design diagrams, the diagram artifacts are more closely located to the code they represent. In fact they will likely be stored in the same source repository (albeit in a seperate project) as the code. This is probably not as important during the initial development project, however becomes very important during ongoing support and maintenance of the software after the project has completed.

Using a Java API, it also means it is possible (and even convenient) to implement automated validation to ensure that the diagrams remain a true representation of the code even after defects and change requests have been implemented. For example, you could use Java Reflection to ensure that each message in your diagrams correspond to an actual method, or that each method in your service bean(s) is represented in a diagram. This removes the dependance on thorough peer reviews reducing the workload of developers.

Another advantage of using a Java API, is it gives the developers full control over how their diagrams appear as they can customise the code that renders the diagrams. In other words you no longer have to tolerate the fact that your choice of diagram editor does not quite get the UML2 syntax fully correct. This also means that conventions regarding diagrams can be enforced and conveniently implemented using a customised Java API. For example, a conditional (if) statement can be represented in many different notations in UML sequence diagrams. The problem with typical diagram editors is that they give the developers the freedom to use any or all of these notations leading to inconsistencies in diagrams that again can only be addressed by peer review. By using a Java API, a team leader could establish a method to add an if statement to a diagram, which would mean all diagrams within the team will use a consistent notation.

Further, drag and drop editors are tedious to use. And the bigger the diagram, the more tedium. For example, consider a sequence diagram with some 20 messages from top to bottom. If during a defect or change request, an additional message needs to be inserted just after the second message, then the other 18 messages first need to be dragged downwards to make room for the new message. The tedium is compounded if your team leader then decides during a peer review that you actually needed two new messages! Using a Java API, it would be a simple matter of inserting a new line of code at the relevant place.

A more subjective advantage is that developers will likely produce better diagrams using a Java API. This is because Java developers like to develop in Java, not drag arrows around a screen! I've never met a developer that looks forward to editing a diagram in a typical drag and drop editor, and the quality of diagrams produced tends to reflect this. I suspect that if developers could generate diagrams from within their IDE using Java code, the quality of the diagrams would be much improved.

Currently, only sequence diagrams are supported. It seemed like sequence diagrams were the best place to start as they tend to be the most numerous, time consuming and complicated diagrams on most projects. The intention is to add support for class diagrams later.

An example of a sequence diagram is shown below. It demonstrates all of the sequence diagram elements supported by the Open Java UML Project. The source code that produced this diagram can be seen here.

How to Draw Sequence Diagrams

The project files can be downloaded here

The first thing to do is download the JAR distribution file. Once you have that, setup a Java development project in your favorite IDE with the JAR on the classpath, and then you are ready to go. The only dependancy is a JDK 1.6 or above. Because the viewer uses a Swing client, you also need to be in an environment with a head (i.e. graphical user interface).

To run in Eclipse, create a new Run Configuration of type Java Application with the following properties:

When you want to view a diagram, select your implementation of SequenceDiagramViewable (see below) in the Project Explorer, then select the SequenceDiagramViewer Run Configuration from the toolbar.

The distribution comes with a viewer client application for viewing diagrams. This viewer allows you to view your diagrams, as well as save them in various image file formats, or alternatively copy the image to the clipboard so you can paste it into your document editor. The viewer class is:

com.ojump.sequence.graphics.viewer.SequenceDiagramViewer

The main method accepts one command line argument which is the full name of a class that implements the SequenceDiagramViewable interface. You need to implement this interface for each diagram that you author and want to view in the viewer. The full name of the interface is:

com.ojump.sequence.graphics.viewer.SequenceDiagramViewable

An example implementation is provided with the distribution which showcases various elements of sequence diagrams supported. The class is:

com.ojump.sequence.graphics.viewer.SequenceDiagramViewableReferenceImpl

This interface forces you to implement one method called getSequenceDiagram(), which returns, you guessed it, an instance of SequenceDiagram. You need to assemble an object model to represent the diagram that you want to view. For convenience, a builder class is provided with methods to add various elements to a diagram. The builder class is:

com.ojump.sequence.SequenceDiagramBuilder

(You can extend the class above to implement a builder that implements your own conventions and/or convenience methods if you like.)

The getSequenceDiagram() method of the builder will return an instance of the SequenceDiagram class, which you in turn return to the viewer.

How to Customise the Diagrams

The viewer uses a renderer object to render the sequence diagrams. The viewer uses a default renderer, however you can implement your own and tell the viewer to use yours by way of a system property:

-Dcom.ojump.sequence.graphics.SequenceDiagramRenderer=[full name of renderer class]

Your renderer class must implement the interface:

com.ojump.sequence.graphics.SequenceDiagramRenderer

To minimise your workload, it is suggested that you extend the default renderer:

com.ojump.sequence.graphics.SequenceDiagramRendererImpl

This default renderer delegates tasks to individual strategy components. You can extend any of these components to adjust their behaviour and then override the factory methods within the renderer to instantiate your implementations.

The distribution comes with a second renderer that extends the default renderer to render the diagrams in colour. The full class name is:

com.ojump.sequence.graphics.SequenceDiagramRendererColorImpl

As described above, to use this colour viewer include the following system property when you invoke the viewer:

-Dcom.ojump.sequence.graphics.SequenceDiagramRenderer=com.ojump.sequence.graphics.SequenceDiagramRendererColorImpl

The sample diagram rendered in colour can be seen below: