UML-to-Java transformations description

The UML-to-Java transformation transforms UML model elements into Java™ code, and generates code that is compatible with the Java 2 Platform, Standard Edition 1.4 (J2SE 1.4) and the Java 2 Platform, Standard Edition 5.0 (J2SE 5.0).

Important: The UML-to-Java 1.4 transformation is deprecated, and is now called the UML-to-Java (deprecated) transformation. The UML-to-Java (deprecated) transformation contains no new functionality, and the transformation behavior is different from the UML-to-Java 5.0 transformation, which is now called the UML-to-Java transformation. You should use the UML-to-Java transformation, whether an application contains code that is compatible with J2SE 5.0 or with J2SE 1.4 or later.

If the transformation configuration implements the Reconciled Modeling design contract management protocol (DCMP), you must specify source and target elements that are valid for the UML-to-Java and Java-to-UML transformations.

Valid transformation sources

The UML-to-Java transformation generates Java classes from the following UML sources:

UML models
Packages and their contents
Non-nested classes and their contents
Non-nested interfaces and their contents
Non-nested enumerations

The transformation transforms the contents of UML models, packages, classes, and interfaces. For example, when the transformation transforms a class, the transformation also transforms the operations and properties of the class.

If you select a model or model elements in the Project Explorer view instead of using the Transformation Configuration editor, the model or elements that you select override the source model or elements that you specify in the transformation configuration. The transformation configuration is not affected and the source that you specify on the Source and Target page of the transformation configuration editor or in the New Transformation Configuration wizard does not change.

Valid transformation targets

You can specify a Java project, or a source folder in a Java project, as the destination for the output of the UML-to-Java transformation.

Alternate names for generated output

You can create a mapping model to specify alternate names for the elements that the transformation generates, without modifying the source model. You might specify alternate names if you want to include Java-specific details, such as naming restrictions in platform-independent models, or if the logical organization of the source model is not appropriate as target packaging.

You can specify a qualified name such as com.ibm.NewName or an unqualified name such as NewName. Specifying alternate names for packages affects all classifiers in that package, unless the classifier specifies a fully qualified name. You can also specify alternate locations in the same project for elements that the transformation generates.

Support for custom enumerations

You can enable the generation of Java enumerations that preserve the name and values of the enumeration literals as retrievable strings. To enable this feature, select the UML to Java Custom Enumeration Extension when you configure a UML-to-Java transformation.

Transformation of passive class state machines

You can enable the generation of Java code for passive class state machines. To enable this feature, select the corresponding extension when you configure a UML-to-Java transformation. After the transformation runs, you can run the generated state machine code as a Java application.

Transformation of XSD data types

If you apply the XSD Types model library to a UML model, when you run the UML-to-Java transformation, the XSD data types are transformed into corresponding Java qualified names. For detailed mapping information, see the reference topic below.

Parameterized types that the UML-to-Java transformation supports

You can specify the following Java collection types as the generic interface for parameterized types, or generics, when you create or configure a UML-to-Java transformation:

AbstractCollection
AbstractList
AbstractMap
AbstractSequentialList
AbstractSet
ArrayList
BitSet
Collection
HashMap
HashSet
Hashtable
LinkedList
List
Map
Set
SortedMap
SortedSet
Stack
TreeMap
TreeSet
WeekHashMap
Vector

The transformation does not generate parameterized type information for other Java collections.

UML collection types and Java varargs

The UML collection type is determined by the following properties of the model elements:

In the Properties view, on the General page, the Ordered and Unique properties specify the UML collection type.
In the Properties view, on the Advanced page, the Is Ordered and Is Unique properties specify the UML collection type.

Note: To specify the Java collection type that the transformation generates, you can also apply the «JavaCollection» or the «JavaArray» stereotype to the UML attribute, association, or operation. Applying the stereotype overrides the default collections that you select in the transformation configuration. These stereotypes are available in the UML-to-Java transformation profile.

By default, if the last parameter in a list of operation parameters has multiplicity * or x..*, the transformation generates a Java vararg. To override this default behavior and generate a Java collection:

Select the corresponding transformation extension in the transformation configuration. See the related task topic below for information about configuring a UML-to-Java transformation.
Apply the «JavaCollection» stereotype to the corresponding UML parameter or property, and set the collectionType property of the stereotype.

To create a Java vararg, you can apply the vararg keyword to the parameter, or you can let the transformation transform the last parameter in a list into a vararg by default.

Annotation of Java source code with UML collection information

If you do not configure the transformation to generate code that is compatible with J2SE 5.0, the UML-to-Java transformation adds comments about UML collection types to the Java collection types that it generates. These comments enable the visual development tools to create accurate visual representations of the Java collection types.

If you specify a multiplicity of * on a UML attribute and you do not change the Java collection information in the transformation configuration, by default, the UML-to-Java transformation generates a Java set.

The following table shows an example of an association relationship between Class1 and Class2; the association relationship specifies a multiplicity of 1..*. The table also shows excerpts of the source code that the transformation generates using the default values in the transformation configuration, and the visual representation of the association relationship. Assume that the transformation is not configured to create trace relationships between source model elements and generated code.

UML elements UML-to-Java transformation output Visual representation of transformation output

UML elements	UML-to-Java transformation output	Visual representation of transformation output
	The transformation generates the following source code if you clear the Use Java 5 check box in the transformation configuration: `public class Class1 { /** * <!-- begin-UML-doc --> * <!-- end-UML-doc --> * @uml.annotations for <code>class2</code> * collection_type="Package1.Class2" * @generated "UML to Java (com.ibm.xtools.transform.uml2.java5.internal.UML2JavaTransform)" */ private Set class2; }`
The transformation generates the following source code if you select the Use Java 5 check box in the transformation configuration: `public class Class1 { /** * <!-- begin-UML-doc --> * <!-- end-UML-doc --> * @generated "UML to Java (com.ibm.xtools.transform.uml2.java5.internal.UML2JavaTransform)" */ private Set<Class2> class2; }`

This image shows UML model elements named Class1 and Class2, with an association relationship that specifies a multiplicity.

The transformation generates the following source code if you clear the Use Java 5 check box in the transformation configuration:

public class Class1 {
	/** 
	 * <!-- begin-UML-doc -->
	 * <!-- end-UML-doc -->
	 * @uml.annotations for <code>class2</code>
	 *     collection_type="Package1.Class2"
	 * @generated "UML to Java (com.ibm.xtools.transform.uml2.java5.internal.UML2JavaTransform)"
	 */
	private Set class2;
}

This image shows the visual representation of Class1 in the Project Explorer view, which contains a collection of Class2 classes.

The transformation generates the following source code if you select the Use Java 5 check box in the transformation configuration:

public class Class1 {
	/** 
	 * <!-- begin-UML-doc -->
	 * <!-- end-UML-doc -->
	 * @generated "UML to Java (com.ibm.xtools.transform.uml2.java5.internal.UML2JavaTransform)"
	 */
private Set<Class2> class2;
}

If you run the Java-to-UML transformation using the generated code in the above example as the transformation source, it generates the following items:

In Class1, the transformation generates a UML attribute called class2 with the «JavaCollection» stereotype applied; the collectionType property is set to java.util.Collection, and the multiplicity is set to *.
In Class2, the transformation generates a UML attribute of type Class called class1, with a multiplicity set to 1, and no stereotype applied.

The following image shows the visual representation of the UML class that the Java-to-UML transformation generates:

This image illustrates the example described in the previous paragraph.

Generation of Javadoc information

When you configure the UML-to-Java transformation to generate J2SE 5.0 code, the transformation generates Javadoc information for the Java elements that it supports. The generated Javadoc information is made up of the following components:

The contents of the documentation property for a UML element, which the transformation places between the following tags:
```
/*
 * 
 * 
 */
```
Annotations that the transformation generates
Information generated by the JDT comments template for the corresponding Java type
Note: To customize the Javadoc information that a JDT template generates, click Window > Preferences > Java > Code Style > Code Templates; then expand Comments, select a Java type, and in the Pattern field for that type, customize the Java comment.

Preservation of Javadoc information from previous releases of Rational Software Architect

To preserve the information between the Javadoc tags that were generated in previous releases of the product, run the Java-to-UML transformation once to migrate the Javadoc information into the documentation property of the corresponding element in the UML model.

Note: To generate the Javadoc tags that were generated in previous releases of the product, you can modify the code templates in the Java Development Toolkit.

Documentation of relationships in transformation output

The UML-to-Java transformation transforms UML relationship documentation into Javadoc information for the following UML relationships:

Associations
Generalizations
Implementations
Realizations

To transform usage relationship documentation into Javadoc information, you must configure the UML-to-Java transformation to generate J2SE 5.0 code.

The transformation adds documentation for generalization, implementation, and realization relationships to the UML documentation for the originating class in each relationship. The transformation also adds the documentation for these relationships to the Javadoc information for the generated target class of each relationship.

For associations, the transformation adds the UML documentation to the documentation of each associated property.

Preservation of Java keywords

UML models cannot represent several Java keywords, such as strictfp, native, transient, and volatile. To preserve these keywords when you run the UML-to-Java transformation, you should model these keywords as UML keywords.

Model element identifiers in transformation output

When you run a transformation that is configured to create trace relationships, for each element that supports the @generated tag, the transformation appends a unique identifier to the @generated tag. This identifier specifies the UML model element from which the Java element was generated, as in this example: * @generated "sourceid:platform:/resource/UMLProject/SimpleModel.emx#_83GpoBtIEdyLaOwyRX_ZMQ". If you rename elements in the source UML model, this unique identifier enables the merge functionality to refactor and merge the appropriate elements.

The Java-to-UML, or reverse, transformation can also use the identifiers to match corresponding elements between the Java project and the UML model. If applicable, changes to the Java source code elements are treated as modifications or as code refactoring instead of additions and deletions to the generated code.

Visual representations of generated Java elements

If you want the output of the UML-to-Java transformation to be the primary engineering artifact, you can specify that the transformation implements the design contract management protocol (DCMP) known as Mixed Modeling. By specifying this DCMP, the transformation creates a direct relationship between the source UML objects and the generated Java code. Creating direct relationships deletes the source UML objects and replaces them with visual representations of the source objects.

Note: You can configure a transformation preference to specify whether to display a warning message before replacing source UML model elements with pointers to the generated elements. For more information about setting transformation preferences, see the link to the related task topic named "Transforming models" at the end of this topic.

If the transformation cannot transform UML elements, such as nested elements, it moves these elements to the nearest package. If the transformation cannot move a model element to the nearest package, it deletes the element.

To avoid possible problems, you should place your source model under version control.

Trace relationships between source model elements and transformation output

You can use the UML-to-Java transformation to create trace relationships from UML source model elements to the generated Java classes. You can then view the trace relationships in a topic diagram by creating and running model queries.

Creating trace relationships is useful in large projects that might contain multiple models and multiple transformation configurations. You can also create and run traceability queries that display how the transformation output relates to software specifications and model elements.

When you run a transformation that is configured to create trace relationships, for each element that supports the @generated tag, the transformation appends a unique identifier to the @generated tag. If you rename elements in the source UML model, this unique identifier enables the merge functionality to refactor and merge the appropriate elements.

Note: If you move a UML element out of the scope of its top-level class, when you rerun the transformation, the merge algorithm does not refactor or merge the renamed element because the scope of the element changed.

When you rerun the transformation, if necessary, the transformation uses the identifier in the source code to match corresponding elements and then changes the code to reflect the changes to the model. For example, if you rename a UML operation in the source model and rerun the transformation, the transformation renames the previously generated Java method and preserves the method body, instead of deleting the previously generated method and adding a new method.

To view the relationships between source model elements and the transformation output, you can visualize the source model element in a diagram and drag the code element that the transformation generates into that diagram. The following table lists the following things: the UML representation for a source model element named Class1, which contains an integer attribute named attribute1, and two operations named Operation1 and Operation2, which do not have any parameters; the code that the transformation generates; and the class diagram that shows the trace relationship between the elements.

UML element Transformation output Trace relationship in a class diagram

UML element	Transformation output	Trace relationship in a class diagram
	/** * / package Package1; import java.util.Collection; /* * <!-- begin-UML-doc --> * <!-- end-UML-doc --> * @uml.annotations * derived_abstraction="platform:/resource/UMLProject/Model.emx#_9YlH8CpPEdyn7_VFIWTp4A" * @generated "sourceid:platform:/resource/UMLProject/Model.emx#_9YlH8CpPEdyn7_VFIWTp4A" / public class Class1 { /* * <!-- begin-UML-doc --> * <!-- end-UML-doc --> * @generated "sourceid:platform:/resource/UMLProject/Model.emx#__8ptgOSnEdyXH8PWExuX2g" / private Integer attribute1; /* * @return the attribute1 * @generated "sourceid:platform:/resource/UMLProject/Model.emx#__8ptgOSnEdyXH8PWExuX2g?GETTER" / public Integer getAttribute1() { // begin-user-code return attribute1; // end-user-code } /* * @param theAttribute1 the attribute1 to set * @generated "sourceid:platform:/resource/UMLProject/Model.emx#__8ptgOSnEdyXH8PWExuX2g?SETTER" / public void setAttribute1(Integer theAttribute1) { // begin-user-code attribute1 = theAttribute1; // end-user-code } /* * <!-- begin-UML-doc --> * <!-- end-UML-doc --> * @generated "sourceid:platform:/resource/UMLProject/Model.emx#_RDsjcOSnEdyXH8PWExuX2g" / public void Operation1() { // begin-user-code // TODO Auto-generated method stub // end-user-code } /* * <!-- begin-UML-doc --> * <!-- end-UML-doc --> * @generated "sourceid:platform:/resource/UMLProject/Model.emx#_R04v0OSnEdyXH8PWExuX2g" */ public void Operation2() { // begin-user-code // TODO Auto-generated method stub // end-user-code } }

This image shows the UML representation of Class1, which is described in the preceding paragraph.

/**
 * 
 */
package Package1;

import java.util.Collection;

/** 
 * <!-- begin-UML-doc -->
 * <!-- end-UML-doc -->
 * @uml.annotations
 *     derived_abstraction="platform:/resource/UMLProject/Model.emx#_9YlH8CpPEdyn7_VFIWTp4A"
 * @generated "sourceid:platform:/resource/UMLProject/Model.emx#_9YlH8CpPEdyn7_VFIWTp4A"
 */
public class Class1 {
	/** 
	 * <!-- begin-UML-doc -->
	 * <!-- end-UML-doc -->
	 * @generated "sourceid:platform:/resource/UMLProject/Model.emx#__8ptgOSnEdyXH8PWExuX2g"
	 */
	private Integer attribute1;

	/** 
	 * @return the attribute1
	 * @generated "sourceid:platform:/resource/UMLProject/Model.emx#__8ptgOSnEdyXH8PWExuX2g?GETTER"
	 */
	public Integer getAttribute1() {
		// begin-user-code
		return attribute1;
		// end-user-code
	}

	/** 
	 * @param theAttribute1 the attribute1 to set
	 * @generated "sourceid:platform:/resource/UMLProject/Model.emx#__8ptgOSnEdyXH8PWExuX2g?SETTER"
	 */
	public void setAttribute1(Integer theAttribute1) {
		// begin-user-code
		attribute1 = theAttribute1;
		// end-user-code
	}

	/** 
	 * <!-- begin-UML-doc -->
	 * <!-- end-UML-doc -->
	 * @generated "sourceid:platform:/resource/UMLProject/Model.emx#_RDsjcOSnEdyXH8PWExuX2g"
	 */
	public void Operation1() {
		// begin-user-code
		// TODO Auto-generated method stub

		// end-user-code
	}

	/** 
	 * <!-- begin-UML-doc -->
	 * <!-- end-UML-doc -->
	 * @generated "sourceid:platform:/resource/UMLProject/Model.emx#_R04v0OSnEdyXH8PWExuX2g"
	 */
	public void Operation2() {
		// begin-user-code
		// TODO Auto-generated method stub

		// end-user-code
	}
}

This image shows a trace relationship, with the derive stereotype applied, between the UML representation of Class1 and the transformation output.

The transformation does not alter the source model when you specify that the transformation generate trace relationships.

Integration with team support

The UML-to-Java transformation provides integration functionality with IBM® Rational® Team Concert, CVS, Rational ClearCase®, and Rational ClearCase LT version control systems, which enables you to automatically check out files or add new files. You must enable team capabilities to work with configuration management systems.