IBM Rational Software Modeler
Release 6.0

com.ibm.xtools.transform.uml2
Class UMLKindTransform

java.lang.Object
  extended bycom.ibm.xtools.transform.core.AbstractTransformElement
      extended bycom.ibm.xtools.transform.core.AbstractTransform
          extended bycom.ibm.xtools.transform.core.Transform
              extended bycom.ibm.xtools.transform.uml2.UMLTransform
                  extended bycom.ibm.xtools.transform.uml2.UMLKindTransform
All Implemented Interfaces:
ITransformationItem

public class UMLKindTransform
extends UMLTransform

This transform provides a generic mechanism to walk the entire UML2 containment (owner) hierarchy so that specific transformation elements can be executed based upon the UML2 element kind (eClass).

After an instance of this transform is created, the user registers its transformation elements (rules, extractors and transforms) along with the corresponding element kind (eClass) that the transformation element is designed to process. When the first transformation element is registered for a particular element kind, a new subtransform is created and the transformation element is added to that transform. Subsequent transformation elements registered for the same element kind are simply appended to that subtransform. Therefore, multiple transformation elements registered for the same element kind are executed in the order in which they were registered. After all transform elements of a given element kind are executed, the contents of the source is extracted and depending on the element kinds of the extracted element, the associated subtransform will execute on them next. For example, after all the "class" rules are executed for a given "class", the methods of that "class" will be extracted and the "method" rules will be executed on these methods.

The transformation elements are executed based upon an exact match of the element kind for the source UML2 object. For example, a rule that is registered to process "classifiers" will not be called for if the source UML2 element is a "class", even though "class" is derieved from "classifiers". In essence, this UMLKindTransform will only process leaf element kinds defined in the UML2 metamodel.

The UMLKindTransform is designed to process a UML model in a flat manner. The order in which elements of the model are processed is non-deterministic but is based upon the containment hierarchy (owned elements) of the UML model. As such, it is safe to assume that by the time a given element is to be processed, all of its parent elements have been previously processed. The order in which sibling elements are processed may vary from one execution run to the next.

Since the traversal order of the UML containment hierarchy is effectively flat, the execution context passed to all of the registered UML-kind rules will be the same. However, if a transform is registered for a UML element kind, it will be executed with its own context where the parent context is the shared context that registered rules receive.

With UMLKindTransform, rules (or subtransforms) should be only added using the addByKind() method and not the generic Transform add() method. Using the add() method is not recommended and doing so may have undesired results and performance issues because rules added in this manner will be executed for every element in the model.

Note: This type of transform cannot be defined in the transformation extension mechanism because there is currently no way to add a rule to this transform with the associated UML2 kind (eClass).


Constructor Summary
UMLKindTransform()
          The default constructor should only be used internally by the transformation service.
UMLKindTransform(ITransformationDescriptor descriptor)
          Constructor for creating root transforms.
UMLKindTransform(String id)
          Constructor for creating transforms within the transformation hierarchy.
 
Method Summary
 Transform addByKind(EClass elementKind, AbstractTransformElement transformElement)
          Add a transformation element for the given element kind.
 ITransformContext createContext(ITransformContext parentContext)
          Create an execution context associated with this transform.
 void execute(ITransformContext context)
          Ensure that the transformation will execute in a write operation and in a single undo interval.
 Transform findTransformByKind(EClass elementKind)
          Retrieve the subtransform created for a specific element kind.
protected  Collection getElements(ITransformContext context)
          Dynamically build a list of transform elements based on source object.
protected  void handle(Exception exception, ITransformContext context)
          Handle exceptions in the transformation engine.
 
Methods inherited from class com.ibm.xtools.transform.core.Transform
add, add, canAccept, findTransform, getElements, initializeProgress, registerTransform, remove, toString
 
Methods inherited from class com.ibm.xtools.transform.core.AbstractTransform
getTransformationDescriptor
 
Methods inherited from class com.ibm.xtools.transform.core.AbstractTransformElement
getAcceptCondition, getDescription, getId, getName, getProgressMonitor, setAcceptCondition, setDescription, setId, setName
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

UMLKindTransform

public UMLKindTransform()
The default constructor should only be used internally by the transformation service.


UMLKindTransform

public UMLKindTransform(ITransformationDescriptor descriptor)
Constructor for creating root transforms.

Parameters:
descriptor - the corresponding transformation descriptor

UMLKindTransform

public UMLKindTransform(String id)
Constructor for creating transforms within the transformation hierarchy.

Parameters:
id - the unique identifier of this transform
Method Detail

createContext

public ITransformContext createContext(ITransformContext parentContext)
Description copied from class: AbstractTransform
Create an execution context associated with this transform. A transform context can be child of another transform context. For a root transform, the transform context should not have a parent context.

Overrides:
createContext in class AbstractTransform
Parameters:
parentContext - the current context of the transformation execution
Returns:
ITransformContext - A nested context of the transformation execution

execute

public void execute(ITransformContext context)
             throws Exception
Description copied from class: UMLTransform
Ensure that the transformation will execute in a write operation and in a single undo interval.

Overrides:
execute in class UMLTransform
Parameters:
context - the current context of the transformation execution
Throws:
Exception

handle

protected void handle(Exception exception,
                      ITransformContext context)
Description copied from class: Transform
Handle exceptions in the transformation engine.

Because of the recursive nature of the engine, an exception can be caught while quite deeping the execution hierarchy of the transformation. The goal is to catch the real exception and wrap it up in a special transform exception. This special exception is then rethrown and caught by all of the transforms executing in the trasform context stack. The root transform will simply throw the exception, which must be caught by the client executing the transformation.

When the execution is first caught, it is logged and traced. It is up to the client executing the transformation to display an error dialog if necessary.

Overrides:
handle in class Transform
Parameters:
exception - the exception that was thrown
context - the execute context in which the exception occurred

addByKind

public Transform addByKind(EClass elementKind,
                           AbstractTransformElement transformElement)
Add a transformation element for the given element kind.

Parameters:
elementKind - - An eClass meta object from UML2Package.
transformElement - - A transform element that will receive an element
Returns:
Transform - the transform that corresponds to elementKind

findTransformByKind

public Transform findTransformByKind(EClass elementKind)
Retrieve the subtransform created for a specific element kind.

Parameters:
elementKind - - An eClass meta object from UML2Package.
Returns:
Transform - A transform if one is found; otherwise null.

getElements

protected Collection getElements(ITransformContext context)
Dynamically build a list of transform elements based on source object.

Overrides:
getElements in class Transform
Parameters:
context - - a transformation context
Returns:
A list of transform elements.
See Also:
Transform.getElements(com.ibm.xtools.transform.core.ITransformContext)

IBM Rational Software Modeler
Release 6.0


Guidelines for using Eclipse APIs.

Copyright (c) IBM Corp. and others 2004. All rights reserved.