UML-to-JPA transformations description

The UML-to-JPA transformation generates Java™ Persistence API (JPA) entities and Java code from Unified Modeling Language (UML) model elements. You must apply the stereotypes of the UML-to-JPA transformation profile to UML model elements to generate enterprise beans.
Before you use this transformation to generate JPA entities and Java classes, you must install specific components and enable specific capabilities.
  • You must install the following components:
    • Java, Java Persistence API (JPA), and EJB 3.0 graphical editing and transformations
    • Tools for WebSphere® Application Server, version 7.0
  • You must enable the following capabilities:
    • Java Persistence API Transformation
    • EJB 3.0 Transformation Profile tool
  • If you configure the UML-to-JPA transformation to create trace relationships between UML elements and the generated JPA entities, you must enable the following capabilities:
    • EJB 3.0 Modeling
    • JPA Modeling
    Note: The Modeling capability category contains the EJB 3.0 Modeling and JPA Modeling capabilities.
After you run the transformation, to customize the transformation output, you must enable the following capabilities:
  • Enterprise Java Developer
  • J2EE Developer

Limitations of the UML-to-JPA transformation

The UML-to-JPA transformation generates JPA version 2.0 entities. If you configure the transformation to generate a deployment descriptor and you require JPA version 1.0 support, you must manually edit the deployment descriptor. In the orm.xml file that the transformation generates, change the following entity-mappings properties:
  • Change the version attribute from "2.0" to "1.0"
  • Change the xsi:schemaLocation attribute from "http://java.sun.com/xml/ns/persistence/orm_2_0.xsd" to "http://java.sun.com/xml/ns/persistence/orm_1_0.xsd"

Generation of Java artifacts by other transformations

When you apply a UML-to-JPA transformation configuration, the transformation service invokes the following transformations, in the order listed below:
  1. UML-to-Java transformation
  2. UML-to-JPA transformation
  3. UML-to-EJB 3.0 transformation
For each of these transformations, the rules of these transformations transform as many source elements as possible. If you do not apply the stereotypes of the UML-to-JPA transformation profile to UML model elements, the UML-to-Java and UML-to-EJB 3.0 transformations transform the UML model elements into Java code and Enterprise JavaBeans (EJB) 3.0 artifacts, and JPA entities are not generated.

Check the Problems view for information about missing stereotypes.

Valid transformation sources

You can specify the following elements as sources for the UML-to-JPA transformation:

  • 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

The transformation can generate output to a JPA project or Java project, or a source folder in a JPA project or Java project. You can create the JPA project with or without a client project. The transformation generates code in the first detected source folder of the JPA project and in the first detected source folder of the client project, if one exists.

Deployment descriptors and persistence files

You can configure the transformation to generate a deployment descriptor, which consists of the following persistence files:
  • orm.xml, which contains the JPA annotations that correspond to the UML elements in the transformation source
  • persistence.xml, which contains a <mapping-file> element that refers to orm.xml

When you configure the transformation to generate a deployment descriptor, it generates all JPA annotations in the persistence files, and does not generate JPA annotations in the Java code.

Trace relationships between source model elements and transformation output

You can use the UML-to-JPA transformation to create trace relationships from the generated Java classes to the UML source elements. 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.

The JPA-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.

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 items: the UML representation for a source model element named Class1, which contains an integer attribute named id, and an operation named Operation1 that does not have any parameters; the code that the transformation generates; and the class diagram that shows the trace relationship between the elements.
Table 1.
UML element Transformation output Trace relationship in a class diagram
The UML representation of the class named EntityClass, which is described in the preceding paragraph.
 
/**
 * 
 */

import javax.persistence.Id;
import javax.persistence.NamedQuery;
import javax.persistence.Entity;
import java.io.Serializable;

/** 
 * <!-- begin-UML-doc -->
 * <!-- end-UML-doc -->
  * @uml.annotations
 *     derived_abstraction="platform:/resource/Miscellaneous%20Models/Blank%20Package1.emx#_sQ4U4J-QEd2RedZBNurApQ"
 * @generated "sourceid:platform:/resource/Miscellaneous%20Models/Blank%20Package1.emx#_sQ4U4J-QEd2RedZBNurApQ"
 */
@Entity
@NamedQuery(name = "EntityClass.findByid", query = "select obj from EntityClass where obj.id = :id")
public class EntityClass implements Serializable {
	/** 
	 * <!-- begin-UML-doc -->
	 * <!-- end-UML-doc -->
	 * @generated "sourceid:platform:/resource/Miscellaneous%20Models/Blank%20Package1.emx#_sRjDQZ-QEd2RedZBNurApQ"
	 */
	@Id
	private Integer id;

	/** 
	 * @return the id
	 * @generated "sourceid:platform:/resource/Miscellaneous%20Models/Blank%20Package1.emx#_sRjDQZ-QEd2RedZBNurApQ?GETTER"
	 */
	public Integer getId() {
		// begin-user-code
		return id;
		// end-user-code
	}

	/** 
	 * @param id the id to set
	 * @generated "sourceid:platform:/resource/Miscellaneous%20Models/Blank%20Package1.emx#_sRjDQZ-QEd2RedZBNurApQ?SETTER"
	 */
	public void setId(Integer id) {
		// begin-user-code
		this.id = id;
		// end-user-code
	}

	/** 
	/** 
	 * <!-- begin-UML-doc -->
	 * <!-- end-UML-doc -->
	 * @generated "sourceid:platform:/resource/Miscellaneous%20Models/Blank%20Package1.emx#_s0NrcJ-QEd2RedZBNurApQ"
	 */
	public void Operation1() {
		// begin-user-code
		// TODO Auto-generated method stub

		// end-user-code
	}

	/** 
	 * <!-- begin-UML-doc -->
	 * <!-- end-UML-doc -->
	 * @generated
	 */
	private static final long serialVersionUID = 0;

	/** 
	 * <!-- begin-UML-doc -->
	 * <!-- end-UML-doc -->
	 * @generated
	 */
	public EntityClass() {
	}
A trace relationship, with the derive stereotype applied, between the UML representation of EntityClass 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 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.

Related tasks:
Transforming UML models into Java Persistence API entities
Configuring UML-to-JPA transformations
Feedback