IBM Rational Software Modeler
Release 6.0

com.ibm.xtools.transform.core
Class Transform

java.lang.Object
  extended bycom.ibm.xtools.transform.core.AbstractTransformElement
      extended bycom.ibm.xtools.transform.core.AbstractTransform
          extended bycom.ibm.xtools.transform.core.Transform
All Implemented Interfaces:
ITransformationItem
Direct Known Subclasses:
RootTransform, UMLTransform

public class Transform
extends AbstractTransform

This Transform class contains the implementation for the default transformation engine.

In the default transformation engine, transforms are containers that traverse the transformation element hierarchy, executing extractors, rules and nested transforms. Extractors effectively walk the source model and rules create or update the target model.

All of these transformation elements (rules, extractors, transforms) contained by a transform are kept in a single list. Execution of the transform is achieved by executing its transformation elements, in sequence, with the same transform context.

In the default transformation engine architecture, every transform MUST have a unique identifier (within the transformation).


Constructor Summary
Transform()
          The default constructor should only be used internally by the transformation service.
Transform(ITransformationDescriptor descriptor)
          Constructor for creating root transforms.
Transform(String id)
          Constructor for creating transforms within the transformation hierarchy.
 
Method Summary
 void add(AbstractTransformElement transformElement)
          Add a transformation element to this transform by appending the new element to the end of the element list.
 void add(int index, AbstractTransformElement transformElement)
          Add a transformation element to this transform.
 boolean canAccept(ITransformContext context)
          Determine if the context contains enough information so that the transform can execute it.
 void execute(ITransformContext context)
          Execute the transform with the given context.
 AbstractTransform findTransform(String id)
          Find a transform with the specified identifier that is contained within this transformation hierarchy.
 Collection getElements()
          Return the collection of transformation elements associated with this transform.
protected  Collection getElements(ITransformContext context)
          Retrieve a list of transformation elements for a given transform context.
protected  void handle(Exception exception, ITransformContext context)
          Handle exceptions in the transformation engine.
protected  void initializeProgress(org.eclipse.core.runtime.IProgressMonitor monitor, ITransformContext context)
          Initializes the progress monitor for the execution of the transformation.
protected  void registerTransform(Transform transform)
          Add a transform to the registry of all transforms in this transformation heirarchy.
 boolean remove(AbstractTransformElement transformElement)
          Remove a transformation element from this transform
 String toString()
           
 
Methods inherited from class com.ibm.xtools.transform.core.AbstractTransform
createContext, 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

Transform

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

When this constructor is used, the caller must immediately call setId() to assign a unique identifier to this transform.


Transform

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

Parameters:
id - A unique id for the transform.

Transform

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

Parameters:
descriptor - A transform descriptor.
Method Detail

add

public final void add(int index,
                      AbstractTransformElement transformElement)
Add a transformation element to this transform. Insert the new element into the list of elements at the specified index. If the index is larger than the list size, append the element. If the index is less than zero, insert the element at the beginning of the list.

Parameters:
index - the zero-based index where to insert the element
transformElement - the element to be inserted

add

public void add(AbstractTransformElement transformElement)
Add a transformation element to this transform by appending the new element to the end of the element list.

Parameters:
transformElement - the element to be appended

remove

public final boolean remove(AbstractTransformElement transformElement)
Remove a transformation element from this transform

Parameters:
transformElement - the element to remove
Returns:
boolean - true if the element was removed

canAccept

public boolean canAccept(ITransformContext context)
Determine if the context contains enough information so that the transform can execute it. If no accpetance condition is defined, a transform will accept a context for execution if at least one of its transform elements will accept the context. Subclasses may override this method to provide more specialized acceptance criteria.

Overrides:
canAccept in class AbstractTransformElement
Parameters:
context - the current context of the transformation execution
Returns:
boolean - true if the context is acceptable

execute

public void execute(ITransformContext context)
             throws Exception
Description copied from class: AbstractTransform
Execute the transform with the given context. The context contains various properties that define the source object and the target container where that source object is to be transformed.

Specified by:
execute in class AbstractTransform
Parameters:
context - the current context of the transformation execution
Throws:
Exception
See Also:
AbstractTransform.execute(com.ibm.xtools.transform.core.ITransformContext)

findTransform

public final AbstractTransform findTransform(String id)
Find a transform with the specified identifier that is contained within this transformation hierarchy.

Parameters:
id - the unique identifier of the transform to look for
Returns:
AbstractTransform - the corresponding transform, if found

getElements

public final Collection getElements()
Return the collection of transformation elements associated with this transform.

Returns:
Collection - the transformation elements

getElements

protected Collection getElements(ITransformContext context)
Retrieve a list of transformation elements for a given transform context. By default, ignore the context. Retrieve the elements from the list.

Parameters:
context - - a transformation context
Returns:
A list of transform elements.

registerTransform

protected final void registerTransform(Transform transform)
Add a transform to the registry of all transforms in this transformation heirarchy.

Parameters:
transform - A transform to be registered.

toString

public String toString()

handle

protected void handle(Exception exception,
                      ITransformContext context)
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.

Parameters:
exception - the exception that was thrown
context - the execute context in which the exception occurred

initializeProgress

protected void initializeProgress(org.eclipse.core.runtime.IProgressMonitor monitor,
                                  ITransformContext context)
Initializes the progress monitor for the execution of the transformation. By default, a transformation does not know the amount of work to be performed so the total work flag is "unknown" Transformations that are capable of computing the exact amount of work involved should override this method. The transformation engine does not call IProgressMonitor.worked() so if a transformation does set a total amount of work value, its rules should call the worked() method to update the progress bar.

Parameters:
monitor - - the progress monitor for the transformation
context - the current context of the transformation execution

IBM Rational Software Modeler
Release 6.0


Guidelines for using Eclipse APIs.

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