Copyright © 2007 International Business Machines Corp.



UML2 2.1 Migration Guide



This guide looks at the most recent changes to the UML metamodel and attempts to guide the user through the migration implications.  Relatively few changes have been made between UML 2.0 and UML 2.1 so there is not much for clients to do in preparation of the migration, however, clients still have to understand the implications.


By James Bruck, Kenneth Hussey IBM
July 19, 2007



A few terms and abbreviations will be used throughout this document.



UML2 2.1

Latest version of the API.

UML2 2.0.4

Maintenance version. Based on older UML2 2.0 version but supports opening of 2.1 models.

OMG issue 10536

OMG issue 10537


UML2 2.1. This refers to the latest version of the UML API which is based on the UML 2.1.1 specification defined by OMG available at



The underlying motivation behind metamodel changes in the UML2 2.1 release has to do with fixing problems that were discovered while trying to implement redefinition, however, there are more fundamental problems regarding the impact that bidirectional associations in the metamodel have on modeling in practice.  The bidirectional associations in question are the ones between Transition and Vertex specifying incoming/outgoing and source/target, and also, the one between ConnectorEnd and Connector specifying ends and roles ( refer to: Superstructure (ptc/07-02-05), p.164 figure 9.4 and p.521 figure 15.2 )

These associations make practical use of the API/metamodel difficult since for example changing the source or target of a transition in a specializing context would cause the incoming/outgoing of a vertex in some other context (and possibly different model/resource) to be updated.  The purpose of these changes was to break the requirement for bi-directional associations to not directly modify the incoming and outgoing properties of Vertex which could be in another model. 

These changes were incorporated into the metamodel in anticipation that changes would be adopted in the 2.2 specification that as of this writing has not yet been finalized.  The metamodel changes require changes to the serialized representation on disk thereby requiring a change to the namespace URI.

 The namespace URI for the UML metamodel in UML2 2.1 has changed to (

 It is also important to note that making these metamodel changes does not constitute an API change (the Java API will remain unchanged).


Understanding the issues…

Prior to UML2 2.1, in order to create a connector between connectable elements (which could be in different resources), the connectable elements (and hence the resources that contain them) need to be modified. Likewise, to create a transition between vertices, the vertices need to be modified.  The properties at the end of these bidirectional associations need to be made derived in order to enable practical use of connectors and transitions in an application that supports redefinition and/or team scenarios. Specifically, properties ConnectableElement::end, Vertex::incoming, and Vertex::outgoing should be made derived.

Until similar changes are made to the UML specification (e.g. as part of UML 2.2), export to XMI interchange format will serialize the (otherwise transient) values of these derived features so as to maintain compliance with UML 2.1.1.


Regarding the bidirectional association between Vertex and Transition:

UML RTF issue 10537 ( addresses the problem which can be summarized with the following example


In context C1, assume we have 3 states S1, S2, S3 and a transition T1 from S1 to S2.  Context C2 specializes context C1.     C2 redefines T1 call it T1*.


Assume we want to change the target of T1* to S3.   S3 itself is not redefined, but rather, visible through inheritance.  By changing the target of T1* to S3 we are actually referring to the S3 in the context of C1 and thereby crossing model boundaries.   This is a result of a bi-directional association between Vertex and Transition in the meta-model.


The resolution involves breaking the bidirectional associations into two unidirectional associations.  In this way, when we wish to change the source/target of a transition, we do not directly modify the incoming and outgoing properties of Vertex.

The following modified metamodel diagram captures the changes:




The derivation for the incomings can be described as follows:

context Vertex::incoming

  derive : Transition.allInstances()->select(target=self)

(By creating derivations in this way, we also take into account redefined transitions that may not be directly owned by the region owning the vertex to which the transition connects.)

The derivation for the outgoings can be described as follows:

context Vertex::outgoing

  derive : Transition.allInstances()->select(source=self)


Regarding the bidirectional association between ConnectableElement and ConnectorEnd:

UML RTF issue 10536 ( addresses the problem.   The problem and subsequent solution are similar to that of the previously described bidirectional association between Vertex and Transistion.

The derivation of end can be described as follows:

context ConnectableElement::end

       derive : ConnectorEnd.allInstances()->select(role=self)


How will this affect clients?

Clients face several issues:

1. Opening up older models with the new UML2 2.1 API.      

2. Supporting existing users of UML2 2.0.x API and allowing them to interoperate with clients of the UML2 2.1 API.

3. Updating existing Profiles or Models created with older version of the API.

4. Code sweep for hardcoded uses of namespace URI.

Opening up older models with the new API

Models created using the older 2.0.x version of the namespace URI will seamlessly open up in the latest version of the UML2 2.1 API.   If these models are subsequently saved, the only observable differences would be that the properties mentioned previously (incoming/outgoing on Vertex and Connector) would no longer be serialized since they are derived.   In addition to this information not being serialized, the namespace UIR would also be updated.

Older 2.0.x version.

Newer 2.1 version

Interoperability between UML2 2.0.x API and UML2 2.1 API

Some clients based on UML2 2.0.x version of the API might need to interoperate with clients using UML2 2.1 version.  In such a case, an existing model would need to be passed between the two clients without loss of data.   

A new maintenance version (2.0.4) was created to support this scenario.   The new maintenance build will allow users of the older 2.0.x version to open up models created with UML2 2.1 API.   In such cases, the 2.1.0 model would not have the incomings/outgoings serialized.  Therefore, the result of getOutgoings(), getIncomings() is a “semi-derived” list capable of repopulating the lists if they were not previously serialized.   Since in the 2.0 version of the API, the association between Vertex and Transition is bidirectional and not cached by the cache adapter, a new cache adaptor was created called org.eclipse.uml2.uml.util.UMLCacheAdapter.    The ability of the getIncomings()/getOutgoings() hinges on the new UMLCacheAdapter being used.    Clients of the 2.0.4 version must explicitly request this adapter by setting a system property org.eclipse.uml2.common.util.CacheAdapter.INSTANCE to org.eclipse.uml2.uml.util.UMLCacheAdapter or an appropriate subtype.

 specify org.eclipse.uml2.common.util.CacheAdapter.INSTANCE = org.eclipse.uml2.uml:org.eclipse.uml2.uml.util.UMLCacheAdapter

Updating existing profiles and models created with older version.

To ensure existing models are up to date, simply open them up using the latest 2.1 API, and save them out.  Profiles and models should be opened and closed/saved so that the UML namespace URI will be updated. 

Client code sweep

Annotations saved within user models still use the older source.  Any client code hardcoding this source for annotations (not recommended) or using UMLPackage.nsURI should be aware that annotations still user the older namespace URI.

  Annotations such as those used to store keywords and Ecore representation of defined profiles still use the original annotation source (



For the most part, the migration from 2.0.x to 2.1.0 should be transparent.   The key changes involve changes to Transitions and Vertex and also Connectors.  If your tooling does not involve State machines or Composite Structures the only change you will notice is the namespace URI change.  Also keep in mind that no changes have been made to the API - all the changes described here involve serialized version of client models.

 For more information on UML2, visit the home page or join the newsgroup.


 [1] Bugzilla: 185602



Java and all Java-based trademarks and logos are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States, other countries, or both.