Specifying custom extractors in submap mapping rules

The transformation source code for a submap mapping rule invokes another transformation. If the input attribute in a submap mapping rule represents a collection of objects, the transformation that is specified in the submap rule is run once for each object in the collection. You can modify this default behavior by specifying an input filter or a custom extractor.

Before you begin

You must have a mapping model open. A mapping model has .mapping as a file name extension. The mapping model must contain at least one mapping declaration, and a submap mapping rule must be defined in the mapping declaration.

About this task

If you create a custom extractor but do not specify an input filter, all the objects that the submap extractor returns are processed by the submap rule when you run the transformation. Custom extractors override the behavior of default extractors, which return the entire collection of objects in an input attribute that is specified by the submap.

Procedure

In the editor area, right-click the mapping rule; then click Show in Properties.
In the Properties view, click the Custom Extractor tab.
Select the Custom Extractor check box.
Note: If this check box is clear, the submap rule extracts the contents of the input feature when you run the transformation.
To specify the code for the custom extractor, complete one of the following steps:
- Click Inline to enter Java™ code in the text area below the Code option; then click Apply. The code that you specify must return a result of type java.util.Collection.
  Tip: To see a list of valid variable names, in the text area below the Inline button, press Ctrl+Space.
  
  Note: The variable called <name>_src specifies the current input object.
- Click External to specify a Java class that contains the custom extractor code. The Java class that you specify must implement the com.ibm.xtools.transform.authoring.ExtractorExtension interface. You must also implement the Collection execute(EObject source) method, where source is set to the current input object. The method extracts objects from the collection in the input attribute, and returns these objects in a collection of type java.util.Collection. When you click Browse, a dialog box enforces the selection of a valid class.
  Tip: To create a Java class that implements a custom extractor, click New; then complete the fields in the New Java Class window.
Click File > Save.

Results

When you run the generated transformation code, the collection of objects that the custom extractor returns is used instead of the collection of the input attribute.

Example

Consider an input object that contains a UML package called Package1, which contains two UML classes, called Class1 and Class2. Package1 also contains a UML package called Package2, and Package2 contains a UML class called Class3.

When the default extractor receives Package1 as input to its execute method, it returns a collection that contains Class1 and Class2.
The custom extractor listed below returns a collection that contains Class1, Class2, and Class3.

package uml_to_ecore_example.transforms;
import java.util.Collection
public class AddClassesFromNestedPackages implements ExtractorExtension {
    public Collection execute(EObject source) {
        Package pkg = (Package)source;
        Collection c = new BasicEList();
        // recursively add all classes in this package and its nested packages
        for (Iterator i=pkg.getPackagedElements().iterator(); i.hasNext();) {
            Object obj = i.next();
            if (obj instanceof Class) c.add(obj);
            else if (obj instanceof Package) c.addAll(execute((Package)obj));
        }
        return c;}}

Feedback