See: Description
Interface | Description |
---|---|
IMetaTypeExt |
Interface which can be implemented by meta-type to provide additional information
|
IRunTransformationListener |
This interface should be implemented by those interested in knowing when a
transformation is about to run and when the transformation has completed.
|
IStringSerializableMetaType |
Optional interface which can be implemented by AbstractMetaType
|
ITransformationDescriptor |
The Transformation Descriptor interface provides access to the static
information that is used to identify a transformation.
|
ITransformationItem |
The Transformation Item interface provides access to common attributes
defined by many transformation entities.
|
ITransformationLicense |
A Transformation License stores information about a license associated with a
transformation.
|
ITransformationLicenseProvider | |
ITransformationProperty |
A Transformation Property stores information about one aspect of the
transformation.
|
ITransformContext |
The Transform Context is the interface for setting and getting property
values during the execution of a transformation.
|
Class | Description |
---|---|
AbstractContentExtractor |
The Abstract Content Extractor is the base class for all content
extractors used within the default transformation engine.
|
AbstractMetatype |
This class defines the main class for a metatype converter.
|
AbstractMetatypeDataManager |
This class is responsible for ensuring an object is valid based on the
metatype data of a
ITransformationProperty . |
AbstractRule |
The Abstract Rule class is the base class for all target model processing
that occurs within the default transformation engine.
|
AbstractTransform |
The Abstract Transform class defines the contract between the transformation
service and the implementation of a specific transformation.
|
AbstractTransformationProvider |
The Abstract Transformation Provider is the base class used by authors
to provide transformaitons.
|
AbstractTransformElement |
The Abstract Transform Element class is the base class for all transformation
objects (elements).
|
BaseDescriptor |
This class maintains the static information corresponding to a
transformation.
|
DCMP |
This class is responsible for providing access to the Design Contract
Management Protocols, DCMPs.
|
ListContentExtractor |
The List Content Extractor extracts the contained source objects when
the "SOURCE" proerty in the execution context is a List object.
|
ModelRule |
This abstract rule wraps up the execution of the rule inside a write action, allowing
transform authors to modify models with the rule.
|
ModelTransform |
This transform performs all of its processing within a "read" action.
|
ModelTransformUtility |
This TransformUtility wraps up its execution within a write action, permitting the
TransformUtility to modify a model.
|
Reporter |
This class is used to record issues that occur while a transformation is
running.
|
RootTransform |
The Root Transform class is a utility class that transformation authors
can used as the root of their transformation.
|
RunTransformationEventManager |
This class is responsible for managing the listeners who are interested in
knowing when a transformation starts and ends.
|
SaveDirtyFilesRule |
This Save Dirty Files Rule prompts user to save dirty resources affected by the transformation.
|
Transform |
This Transform class contains the implementation for the default transformation
engine.
|
TransformationServiceUtil |
The class provides access to the Transformation Service.
|
TransformationUsageIdentifier |
This class provides identifiers used to specify how a transformation is
being used.
|
TransformCondition |
A base class for conditions that require the entire transform
context to make their isSatisfied() decision.
|
TransformController |
This class handles executing a TransformConfig.
|
TransformUtility |
The TransformUtility is a class that provides utility functions to transformations.
|
UpdateProgressMonitorRule |
This class is responsible for updating the state of the progress monitor.
|
ValidateEditRule |
This Validate Edit Rule provides a mechanism for transformations to ensure
that the files they want to modify will have the correct permissions.
|
Exception | Description |
---|---|
TransformException |
Capture an exception thrown during the execution of a transformation.
|
This package provides the API of the Transformation Service and the default Transformation Engine.
Transformations are used to convert models from one level of abstraction to another. Typically the conversion is from a higher level of abstraction, such as a UML model, to a lower level, such as Java code. The execution of a transformation requires one or more properties to be defined, such as the source model elements that are to be transformed and the container where the target transformation elements are to be created or updated. Other properties can be defined to enable customization of the transformation.
An extension to a transformation can be defined by someone other than the transformation author, where the extension augments the behaviour of that transformation. An extension can also define properties to enable customization of that extension.
The transformation framework provides the following features:
Transformation authors define transformation descriptors in XML using the transformation provider extension point (com.ibm.xtools.transform.core.transformationProviders). The actual logic for the transformation is typically defined in code and is based upon the Transformation Engine. The Transformation Service examines its extension points at startup and populates registries of the available transformations, transformation extensions and transformation property metatypes.
The helper class TransformationServiceUtil
is provided to access the available transformations. Transformations are registered in XML
and can be specified as either public or private. A public transformation is visible
in the UI but a private transformation can only be accessed by client code.
A transformation descriptor in XML may also specify one or more properties that a transformation can access when it is executing. These properties can be used to customize the execution of the transformation. If a read-write property is defined for a public transformation, the user will be able to change that property's value before the transformation is executed.
Every property
defined by a transformation or by a transformation extension has an associated
"metatype". This metatype indicates the type of value the property contains.
Default metatypes supported by the Transformation
Service include string, boolean, integer, resource, etc. For example, a property defined
with the metatype
boolean will contain a value of type Boolean
.
As part of the transformation descriptor in XML, the author must define one or more metatypes for the source and target model types that are applicable for the transformation. The transformation UI will attempt to adapt the selected UI objects into appropriate objects based upon the specified metatypes. If UML transformation support is available, the Transformation Service also defines metatypes for UML2 semantic and UML2Notation elements.
For example, suppose a transformation requires a UML semantic element as its source and a UI object that represents a UML semantic element is selected in some model content explorer or on a diagram. The UI object selected in the explorer usually represents the UML semantic element whereas the UI object selected in a diagram represents the notational element that corresponds to the UML semantic element. Specifying a source model type of "UML2" in the XML transformation descriptor enables the transformation UI to automatically adapt the selected UI objects to the appropriate UML semantic elements before executing the transformation.
Using the metatype converter extension
point (com.ibm.xtools.transform.core.metatypeConverters), a transformation author
may define custom metatypes. These metatypes can be used either as the type for
transformation properties or they can be used as transformation source and target model types.
The metatype descriptor in XML defined two flags to indicate how the metatype
can be used and also defines a class to perform the actual conversions. This class must
be derived from AbstractMetatype
.
One flag indicates the metatype converter can adapt the selection (a UI object) into a corresponding data object. only if this flag is set can the metatype be used as a transformation source or target model type.
The second flag indicates the value for this metatype can be represented by a user editable string. If this flag is set, the metatype can be used as the type for a transformation property. However, in addition to this metatype flag, the corresponding property must also be read-write before the metatype value is displayed as a string in a property sheet that the user can modify. This flag also require the metatype converter be able to resolve the user modified string back into a corresponding data object.
A transformation extension enables a client to augment an existing transformation by inserting logic into the transformation. The extension is defined in XML using the transformation extensions extension point (com.ibm.xtools.transform.core.transformationExtensions). An extension can only augment a transformation that is based upon the Transformation Engine by inserting Rules and Extractors into the transformation hierarchy. See Transformation Engine below for more details. When an instance of a transformation is requested, the Transformation Service will automatically incorporate all appropriate extensions into that transformation instance. Thus when the transformation is executed, the original logic and the extended logic will be executed at the same time as if it were one entity.
The following Eclipse extension points are defined by the Transformation Service:
The transformation engine does not assume any structure within the source model other than the model is probably hierarchical in nature. The engine has been tailored for traversing models that are based upon a hierarchical containment meta-model, such as UML. For example, in UML a package can contain classes and other packages. A class can contain attributes, operations and other classes.
The transformation engine architecture consists of transforms, rules and
content extractors, also referred to as just extractors. A transform, derived from
AbstractTransform
, is a container
that has an ordered list of transform elements, which can be rules, extractors and other
transforms (subtransforms). A transform executes a source object by executing that same
object sequentially with its transform elements. A rule, derived from
AbstractRule
,
executes the source object by
converting it to one or more objects in the target model.
A content extractor, derived from AbstractContentExtractor
, executes
a source object by extracting the appropriate contents from that source object and then executing
each resulting object with the corresponding transform. A subtransform is simply a transform contained
directly by a parent transform and effectively executes the same source object as if the transform
elements of the subtransform were part of the parent transform. Each transform element can
have an associated condition that must be accepted before the transform element is executed.
The connections between transforms, rules and extractors (the transformation hierarchy) determine how the source model is to be traversed. In most cases, a transform will contain rules and extractors and indirect references to other transforms via its extractors. These indirect references to other transforms enable the source model to be walked.
One or more rules within a transform perform the necessary processing of the source object to the target model, and one or more extractors within a transform perform the walking of the source model. The contained rules, extractors and subtransforms are kept in a single ordered list. Thus the transformation author decides how the source model is to be traversed and processed. To traverse the source model containment hierarchy, a rule would execute first on a given source model object so that one or more target model objects can be created. Then, one or more extractors would be executed (on the same source object) to process the elements contained by that source object.
Therefore, the transformation hierarchy of transforms, rules and extractors will be similar to the containment hierarchy of the source meta-model but during transformation execution, the transforms, rules and extractors are typically called recursively.
The hierarchical nature of source models and the recursive nature of the transformation
hierarchy require that the context in which the transforms, extractors and rules are
executed must be kept in a stack-like fashion. ITransformContext
is responsible for maintaining this execution contextual information, which includes
the current source, target and target container objects. It also includes a local property
table that enables rules to define data that can be accessed by sibling rules or by
rules in nested transforms.
A new execution context object is created each time a transform is executed, with one exception. When an extractor is executed and it returns multiple source objects to be executed by its associated transform, only one new context is created that is used multiple times. All rules and extractors associated with the transform use the same context object so if one rule defines a new (temporary) property, a sibling rule can access or modify that property. When a nested transform is executed, the new execution context created is linked to its parent context. Therefore, rules within the nested transforms have access to the properties defined in all of its parent contexts in addition to the properties defined in their own context. However, the properties in parent contexts are read-only.
If the transformation author wishes to use the default transformation engine, all
of the transforms in the transformation will either be Transform
or will be a subclass. If the author wishes to use his own transformation engine, there
must still be a transformation provider and a transformation descriptor in XML. The
root transform of the transformation (returned by the provider) must be derived from
AbstractTransform
and its execute() method starts the custom engine.
In this case, the author
would not be using default engine rules or extractors but would be using concepts applicable to his
custom transformation engine. As a result, the transformation
extension mechanism will not work.