JavaGen Customization

Besides stereotypes, there are several other ways to customize the code that JavaGen generates.

XDoclet Customization

XDoclet attributes are a primary means of customizing what JavaGen generates. In general when JavaGen encounters a XDoclet attribute it passes it through to the generated code while suppressing the generation of equivalent default values.

In other cases, specific XDoclet tags have a wider influence, completely changing what is generated. For example, placing the @hibernate.one-to-one constrained="true" attribute on one side of a one-to-one association will trigger the generation of several other attributes, transforming the underling relational database mapping from a foreign key relationship to constrained primary key relationship.

See the module documentation for specific attribute effects.

Adding XDoclet Attributes to UML Models

Tagged Values are a standard UML extension mechanism and provide the means to add XDoclet attributes to UML classes, attributes and associations. JavaGen treats any tag/value pair as an XDoclet attribute if the tag name starts with '@'.

For example, to add XDoclet tags in Poseidon as a Tagged Value pair select the class, attribute or method then select the Tagged Value dialog. The results should look something like the following:

setting XDoclet tag in Posiedon

Notice that there are two name-value pairs on the right side separated by a space.

Poseidon users can also add XDoclet tags in the Documentation dialog as follows:

setting XDoclet tag in Posiedon

To save time, we recommend that you first add the XDoclet tags to the source files and verify the correct XDoclet output and behavior before pasting them into the UML file.

Adding Tagged Values to Associations

To add an attribute to an association end in Poseidon:

  1. Click on an existing one-to-one association between two classes, in the 'Properties' tab
  2. Select the desired association end, then select the 'Tagged Values' tab
  3. In the 'Tag' column enter the tag name, for example: @hibernate.one-to-one
  4. Under the 'Value' column enter the value(s), for example: constrained="true"

JavaGen Properties

Various Ant properties can be set to modify JavaGen output. Properties are forwarded to JavaGen in two ways:

  1. Any property that uses the javagen. prefix, for example: 
    <property name="javagen.config" value="petstore"/>
  2. Properties explicitly named in the coma delineated javagen.properties list: 
    <property name="javagen.properties" value="model.name,database.name,datasource.name"/>

Please see specific modules for details.

Round-Tripping

Although JavaGen does not support automatic 'round-tripping', the ability to add source code to the UML file makes it possible to completely customize the generated classes. This works well for tiers that typically only require a little customization like EJB CMPs, but for business logic intensive classes where most of the code is hand written, it makes more sense to use the generated class as a template and maintain the code by hand.

Remember JAM users should move source files from the 'src-gen' directory to the 'src' directory before modifying them by hand. The build system will then automatically manage duplicate files, preserving files found in the 'src' directory.

Adding Source Code to UML

Source code can be added to method bodies and JavaGen passes this text through unchanged. To add source code into Poseidon select the target method, the select the 'Source code' tab and paste in the code:

adding source to poseidon

We do not recommend writing source code in your UML tool for anything but trivial tasks. It is much more efficient and less error prone to write and test your code in your favorite IDE, then paste it back into the UML before regenerating.

It is not intended that this technique be employed extensively, there are more powerfull techniques for coding implementation details such as IoC, AOP, delegation, inheratance and dynamic proxies that won't tie your model to a specific technology. However, if you need UML-to-implementation round-trip capabilities it is available.

Java Version

TODO

Ignoring Packages and Classes

UML does not allow a reference to a type unless it has been defined within the scope of the model. To model Java software, designers must define dummy classes to represent standard Java and open-source libraries.

For example, to make a class serializable, one must first define a java.io.Serializable interface and drop it in the diagram before one can draw this representation.

To prevent the code generator from emitting all these dummy reference classes, JavaGen provides two techniques for suppressing package and class generation:

  • the <<ignore>> stereotype - any class or interface with this stereotype will not be generated.
  • a package excludes list - any package name listed in this Ant property will not be generated.

By default javagen.package.excludes filters the following package names: 

<property name="javagen.package.excludes" 
  value="java javax sun com.sun org.apache org.omg org.xml org.w3c net junit com.javagen.commons"/>

If you need to override this property, note that this is a space-separated list of package prefixes.

Renaming Stereotypes

JavaGen doesn't force you to use JavaGen-specific stereotypes. Stereotypes can by renamed dynamically by specifying from:to pairs in a comma-delineated list: 

<property name="javagen.stereotype.replacements" value="entity:cmp,service:stateless"/>

In this example <<entity>> will be replaced with <<cmp>> and <<service>> with <<stateless>>.

XSLT Descriptor Processing

XSLT stylesheets are ideal for post-processing deployment descriptors and XML mapping files. This is an effective and flexible technique for:

  • Overcoming XDoclet limitations and bugs.
  • Customizing deployment descriptors for different target platforms.
  • Adding security constraints for production deployments.
  • Enforcing standards such as database table and column naming.
  • Converting HTML to JSP.
  • Converting between different product versions.

It is often more productive to use XSLT rather than changing XDoclet tags in the source code. Post-processing also promotes the continuous integration development process.

JAM comes with several built-in stylesheets and the post-process-ejb-dd JAM example demonstrates EJB security and SQL name processing.