Xtools Transformation Extensions

Identifier:

com.ibm.xtools.transform.core.transformationExtensions

Description:

This extension point facilitates the configuration of extensions to transformations that are defined by transformation providers registered with the transformation service. Using a transformation extension, a client can extend the behavior of an existing transformation.

A transformation extension allows a client to add rules, content extractors or transforms to an existing transformation, as long as that transformation has published the unique IDs of its transforms. In an extension, the following items can be defined:

Property - new properties for the transformation
RuleDefinition - new rules to extend the current behavior
ExtractorDefinition - new content extractors for walking the model
TransformDefinition - new transforms (containers for extractors and rules)
ExtendTransform - add new rules, extractors or transforms to an existing transform

Configuration Markup:

<!ELEMENT extension (TransformationExtension)>

<!ATTLIST extension

point CDATA #REQUIRED

id CDATA #IMPLIED

name CDATA #IMPLIED>

point - The identifier of the extension point, e.g. com.ibm.xtools.transform.core.transformationExtensions.
id - The identifier of the extension, e.g. my.plugin.transformationExtensions
name - The name of the extension, e.g. %ext.transformationExtensiosName.

<!ELEMENT TransformationExtension (Property* , RuleDefinition* , ExtractorDefinition* , TransformDefinition* , ExtendTransform+)>

<!ATTLIST TransformationExtension

id CDATA #REQUIRED

name CDATA #IMPLIED

targetTransformation CDATA #REQUIRED

author CDATA #IMPLIED

description CDATA #IMPLIED

document CDATA #IMPLIED

enabled (true | false) "true"

version CDATA #REQUIRED

extensionGUI CDATA #IMPLIED

helperClass CDATA #IMPLIED

readonly (true | false) "false">

id - The unique identifier of this transformation extension.
name - The localized name of this transformation extension.
targetTransformation - The unique identifier of the transformation to be extended.
author - The author of this transformation extension.
description - A localized brief description of the transformation extension.
document - An HTML document reference containing detailed information on what the extension does and how it can be used. The referenced HTML document can either be an URL or a file path relative to the root directory of the plug-in.
enabled - The transformation extension enablement flag. An extension that is disabled will not be applied to a new instance of the target transformation when it is created. If this attribute is not defined, the default is enabled (true).
version - The version of this transformation extension. The version format should be compatible with the Eclipse version format: x.y.z.
extensionGUI - An optional class that enables extension authors to integrate custom GUI into the transformation user interface. The specified class must be derived from com.ibm.xtools.transform.ui.AbstractExtensionGUI.
helperClass - An optional class that enables extension authors to hook into various aspects of the transformation framework, such as validation. The specified class must be derived from com.ibm.xtools.transform.core.extension.AbstractTransformExtensionHelper.
readonly - Specifies if the user will be allowed to enable or disable this transformation extension from a transformation configuration. True if the user should not be able to change the state of the transformation extension. False otherwise. The default value is false.

<!ELEMENT Property EMPTY>

<!ATTLIST Property

name CDATA #REQUIRED

id CDATA #REQUIRED

description CDATA #IMPLIED

value CDATA #IMPLIED

metatype CDATA #IMPLIED

metatypeData CDATA #IMPLIED

maxValues CDATA #IMPLIED

delimiters CDATA #IMPLIED

readonly (true | false) "false">

name - The localized name of the transformation property to be added.
id - The identifier of the transformation property which should be unique within the target transformation. However, if the property already exists in the target transformation and is read-write, the value specified in this property definition will override the default value in the transformation descriptor. If the existing property is read-only, this property definition will have no effect.
description - A localized description of this transformation property.
value - The default value of the transformation property. Clients can override this default value in the transform context (ITransformContext). If the "maxValues" attribute is not "1", this default value will be parsed (using the "delimiters" attribute) to create a list of values instead of a single value. If this attribute is not specified, the property value is null.
metatype - Defines the underlying type of the property value(s). The default metatype value is "string".
The following metatypes are provided in the transformation framework: Boolean, Choice, EMF, File, Folder, Integer, Project, Resource, String.
If the UML support of the transformation framework is installed the following metatypes will also be available: Notation, UML, UMLNotation.
metatypeData - Defines the data associated with the underlying type of the property value(s). It is additional information that can be used to define constraints on the value. The default metatype data value is an empty string.
Only two metatypes in the transformation framework currently use this.
1. Choice - The format is a comma separated list. For example, one,two,three.
2. String - The format is a comma separated list of key value pairs. Currently the only supported key is maxLength which defines the maximum number of characters the string may contain. For example, maxLength=10.
maxValues - Defines the maximum number of values that can be defined for the property. A number less than or equal to zero indicates an unlimited number of values. The default maximum number of values is "1".
delimiters - If a property can contain multiple values (maxValues != 1) and a string is defined for the "value" attribute, this delimiters attribute can be defined so that the single value string can be parsed into multiple values (e.g., the keywords property expects a space separated list of words as its "value" attribute). The default delimiters are " \t\r\n\f".
readonly - Identifies a property as being read-only and cannot be changed at runtime. The default is "false".

<!ELEMENT RuleDefinition EMPTY>

<!ATTLIST RuleDefinition

id CDATA #REQUIRED

name CDATA #IMPLIED

description CDATA #IMPLIED

class CDATA #REQUIRED

acceptCondition CDATA #IMPLIED>

id - The unique identifier of this rule. This ID must be unqiue within the transformation extension and will be referenced in AddRule elements within this extension. Every reference to this rule definition will result in a new instance of the rule class being created.
name - The localized name of the rule. If the name is not specified, the ID will be used.
description - A localized description of this rule.
class - The rule implementation class. This class must be derived from com.ibm.xtools.transform.core.AbstractRule.
acceptCondition - This attribute defines a class that is used by the rule in the canAccept() method. This class should be derived from org.eclipse.emf.query.conditions.Condition. If this attribute is not defined, the default implementation of canAccept() will accept anything (returns true).

<!ELEMENT ExtractorDefinition EMPTY>

<!ATTLIST ExtractorDefinition

id CDATA #REQUIRED

name CDATA #IMPLIED

description CDATA #IMPLIED

class CDATA #REQUIRED

acceptCondition CDATA #IMPLIED

filterCondition CDATA #IMPLIED>

id - The unique identifier of this content extractor. This ID must be unqiue within the transformation extension and will be referenced in AddExtractor elements within this extension. Every reference to this extractor definition will result in a new instance of the extractor class being created.
name - The localized name of the content extractor. If the name is not specified, the ID will be used.
description - A localized description of this content extractor.
class - The content extractor implementation class. This class must be derived from com.ibm.xtools.transform.core.AbstractContentExtractor.
acceptCondition - This attribute defines a class that is used by the extractor in the canAccept() method. This class should be derived from org.eclipse.emf.query.conditions.Condition. If this attribute is not defined, the default implementation of canAccept() will accept anything (returns true).
filterCondition - The attribute defines a class that is used to perform additional filtering when extracting the contents from the source object in the execute() method. This class should be derived from org.eclipse.emf.query.conditions.Condition. If this attribute is not defined, no additional filtering is performed when extracting related objects from the source object.

<!ELEMENT TransformDefinition EMPTY>

<!ATTLIST TransformDefinition

id CDATA #REQUIRED

name CDATA #IMPLIED

description CDATA #IMPLIED

class CDATA #IMPLIED

acceptCondition CDATA #IMPLIED>

id - The unique identifier of this transform. This ID must be unqiue within the transformation extension and within the transformation instance. Although this transform ID can be referenced in both AddTransform and AddExtractor, only one instance of the transform will be created and all references will be resolved to that one instance.
name - The localized name of the transform. If the name is not specified, the ID will be used.
description - A localized description of this transform.
class - The transform implementation class. This class must implement the ITransform interface. If a class is not specified, the default transform class com.ibm.xtools.transform.core.Transform will be used.
acceptCondition - This attribute defines a class that is used by the transform in the canAccept() method. This class should be derived from org.eclipse.emf.query.conditions.Condition. If this attribute is not defined, the default implementation of canAccept() for a transform is to accept the data if at least one of its transform elements (rules, extractors or subtransforms) accepts the data.

<!ELEMENT ExtendTransform (AddRule* , AddExtractor* , AddTransform*)>

<!ATTLIST ExtendTransform

id CDATA #IMPLIED

name CDATA #IMPLIED

targetTransform CDATA #REQUIRED>

id - An identifier of this transform extension. This identifier would be used for debugging purposes only.
name - The name of this transform extension. This name would be used for debugging purposes only.
targetTransform - The unique identifier of the transform to be extended. This transform must exist in the target transformation.

<!ELEMENT AddRule EMPTY>

<!ATTLIST AddRule

id CDATA #REQUIRED

index CDATA #IMPLIED

insertAtID CDATA #IMPLIED>

id - The unique identifier of the rule definition to be added. The rule definition must exist in the corresponding transformation extension. A new instance of the rule is created and added.
index - The index in the transform's list of elements where the rule is to be inserted. For example, a transform already contains elements A and B. Rule C is contributed through an extension using an index of 1. The new list of transformation elements will be elements A, C then B. If the index is less than or equal to zero, the element is inserted at the beginning of the list (e.g. C, A, B). If the index is greater than the size of the list, or this "index" attribute is not defined, the element is appended (e.g. A, B, C).
insertAtID - The rule will be inserted in the transform's list of elements before the element with this id. Use this instead of index to specify where the rule will be inserted when it's likely the transform's list of elements will change in new versions of the transformation or by another extension. If a value is specified for both index and insertAtID, the index value will be used.

<!ELEMENT AddExtractor EMPTY>

<!ATTLIST AddExtractor

id CDATA #REQUIRED

index CDATA #IMPLIED

transform CDATA #REQUIRED

insertAtID CDATA #IMPLIED>

id - The unique identifier of the extractor definition to be added. The extractor definition must exist in the corresponding transformation extension. A new instance of the extractor is created and added.
index - The index in the transform's list of elements where the extractor is to be inserted. For example, a transform already contains elements A and B. Extractor C is contributed through an extension using an index of 1. The new list of transformation elements will be elements A, C then B. If the index is less than or equal to zero, the element is inserted at the beginning of the list (e.g. C, A, B). If the index is greater than the size of the list, or this "index" attribute is not defined, the element is appended (e.g. A, B, C).
transform - The unique identifier of the transform which will process the objects returned by the content extractor. This transform must either already exist in the transformation, have a corresponding definition in this transformation extension, or correspond to a registered transformation. Once ths transform is created and linked into the corresponding transformation instance, that transform instance will be used for subsequent references.
insertAtID - The extractor will be inserted in the transform's list of elements before the element with this id. Use this instead of index to specify where the extractor will be inserted when it's likely the transform's list of elements will change in new versions of the transformation or by another extension. If a value is specified for both index and insertAtID, the index value will be used.

<!ELEMENT AddTransform EMPTY>

<!ATTLIST AddTransform

id CDATA #REQUIRED

index CDATA #IMPLIED

insertAtID CDATA #IMPLIED>

id - The unique identifier of the transform to be referenced. This transform must either already exist in the transformation, have a corresponding definition in this transformation extension, or correspond to a registered transformation. Once ths transform is created and linked into the corresponding transformation instance, that transform instance will be used for subsequent references.
index - The index in the transform's list of elements where the transform is to be inserted. For example, a transform already contains elements A and B. Transform C is contributed through an extension using an index of 1. The new list of transformation elements will be elements A, C then B. If the index is less than or equal to zero, the element is inserted at the beginning of the list (e.g. C, A, B). If the index is greater than the size of the list, or this "index" attribute is not defined, the element is appended (e.g. A, B, C).
insertAtID - The transform will be inserted in the transform's list of elements before the element with this id. Use this instead of index to specify where the transform will be inserted when it's likely the transform's list of elements will change in new versions of the transformation or by another extension. If a value is specified for both index and insertAtID, the index value will be used.

Examples:

Following is an example of a transformation extension:

<extension point="com.ibm.xtools.transform.core.transformationExtensions">
   <TransformationExtension
      id="clientB.transformation.extension.1"
      targetTransformation="providerA.TransformA">
      <Property id="extension.property.1" name="newPropertyName" value="default value" readonly="true" />

      <RuleDefinition
         id="clientB.ClassRuleB1"
         name="Client B Class Rule 1"
         class="com.ibm.clientB.extension.ClassRuleB1" />

      <RuleDefinition
         id="clientB.ClassRuleB2"
         name="Client B Class Rule 2"
         class="com.ibm.clientB.extension.ClassRuleB2" />

      <ExtractorDefinition
         id="clientB.ClassExtractorB"
         name="Client B Class Extractor "
         class="com.ibm.clientB.extension.ClassExtractorB" />

      <TransformDefinition
         id="clientB.ClassTransformB"
         name="Client B Class Transform "
         class="com.ibm.clientB.extension.ClassTransformB" />

      <ExtendTransform
         targetTransform="TransformA.ClassTransform" >
         <AddRule
            id="clientB.ClassRuleB1"
            index="0" />
         <AddExtractor
            id="clientB.ClassExtractorB"
            transform="clientB.ClassTransformB" />
      </ExtendTransform>

      <ExtendTransform
         targetTransform="clientB.ClassTransformB"
         <AddRule
            id="clientB.ClassRuleB2" />
      </ExtendTransform>

   </TransformationExtension>
</extension>

API Information:

The value of the class attribute in the <RuleDefinition> element must be derieved from com.ibm.xtools.transform.core.AbstractRule.

The value of the class attribute in the <ExtractorDefinition> element must be derived from com.ibm.xtools.transform.core.AbstractContentExtractor.

The value of the class attribute in the <TransformDefinition> element, if specified, must be derived from com.ibm.xtools.transform.core.AbstractTransform. If not specified, the class com.ibm.xtools.transform.core.Transform is used.

The value of the acceptCondition and filterCondition attributes in the rule, extractor and transform definitions must be derived from org.eclipse.emf.query.conditions.Condition. By default, the condition can only interrogate the current source object to make its decision. If more information is needed, the condition can be derived from com.ibm.xtools.transform.core.TransformCondition, in which case the entire transform context is available.