jaxb
Class MetaArchitectureDocument

java.lang.Object
  extended by jaxb.MetaArchitectureDocument

public class MetaArchitectureDocument
extends java.lang.Object

Meta Architecture Document

.

This document explains how this architecture document is written.

All of the JAXB RI architecture document is built as javadoc. So contributing to this document means writing/modifying the javadoc and commiting it.

Using javadoc makes it easier to keep the documents in sync, thanks to modern IDEs, and it also allows us to link to various code pieces more easily.

The javadoc module

The JAXB RI workspace contains a special 'javadoc' module, which is used exclusively for hosting architecture document javadoc. Normally, the architecture document is written on a package/class that provides the functionality, but this module can be used to write a part of the document that doesn't relate to any particular code (such as this document itself.)

Javadoc Hacks

The out-of-box javadoc tool lacks several features for writing documentations, so we wrote a few custom javadoc tags to enhance the expressiveness.

ArchitectureDocument tag

The ArchitectureDocument tag is a block tag that can be written on a class or a package. When present, it changes the way the javadoc is generated for that class/package. Specifically, it brings the description page to the very top of the HTML page (whereas normally the description is after the list of members.)

This improves the readability by eliminating the needs to scroll down.

SequenceDiagram tag

The SequenceDiagram tag is an inline tag that can be written anywhere. This tag allows you to write an UML sequence diagram in a declarative fashion.

For example, the following javadoc will produce the following picture:

{@SequenceDiagram
# Define the objects
object(O,"o:Toolkit");
placeholder_object(P);
step();

# Message sequences
active(O);
step();
active(O);
message(O,O,"callbackLoop()");
inactive(O);
create_message(O,P,"p:Peer");
message(O,P,"handleExpose()");
active(P);
return_message(P,O,"");
inactive(P);
destroy_message(O,P);
inactive(O);

# Complete the lifelines
step();
complete(O);
 }

For details about the syntax, see this document.

When you are writing a diagram, it's convenient to use a scratch pad (Sun-internal) to quickly check the output of your description.

DotDiagram tag

The DotDiagram tag is similar to the SequenceDiagram tag in its concept. It is an inline tag that can be written anywhere. This tag allows you to write a box and arrow diagram by using the dot program in the GraphViz package.

For example, the following javadoc will produce the following picture:

{@DotDiagram
digraph G {
        size ="4,4";
        main [shape=box]; // this is a comment
        main -> parse [weight=8];
        parse -> execute;
        main -> init [style=dotted];
        main -> cleanup;
        execute -> { make_string; printf}
        init -> make_string;
        edge [color=red]; // so is this
        main -> printf [style=bold,label="100 times"];
        make_string [label="make a\nstring"];
        node [shape=box,style=filled,color=".7 .3 1.0"];
        execute -> compare;
}
 }

For details about the syntax, see this document.

When you are writing a diagram, it's convenient to use a scratch pad (Sun-internal) to quickly check the output of your description.

Generating the document

To generate the document locally, run ant architecture-document from the command line. Because of the way the custom javadoc tags work, this only works for computers running inside Sun.

Alternatively, Hudson automatically posts a new architecture document to the java.net every time a commit is made. This process typically takes 10 minutes (so in the worst case, it takes 20 minutes for your change to be reflected.)

Browse the document

The up-to-date version of the document is always available at the java.net.


Constructor Summary
MetaArchitectureDocument()
           
 
Method Summary
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

MetaArchitectureDocument

public MetaArchitectureDocument()