Declaring an Operation Extension Point

Here are the steps for a transformation author to allow external contributions:

1. Identify extension points
    
   Identify in the transformation flow (i.e. the operations hierarchy) some areas (referred as extension points) where external authors would like to contribute extensions. An extension point shall be used when:
   • you anticipate a client might want to perform extra operations, dedicated to his context, that enhances the default behavior you implement,
   • you can provide an easy to understand context,
   • you can commit to not change the context nor the semantics of the extension point, which must be stable in time.
      
   Here are typical extension points you may want to provide:
   • after reading the input model, for contributors to perform refactorings before executing the transformation,
   • during the transformation, if there are stable points at which contributors can adapt what is being transformed,
   • before writing the output model, for contributors to perform final additions to the model created by the transformation.
   
   You are recommended to minimize the number of extension points, to have a clear and understandable contract with contributors. Extension point shall not operate at very low level of the transformation.
    
2. Declare an extension point
    
   Here are the steps to declare an extension point:
   1. In the plugin.xml file, where the operation service is declared, add an extension of 'com.sodius.mdw.core.operations' and create an extensionPoint element.
   2. Declare an 'id' attribute to this extension point. This identifier must never change and will be used by contributors to reference this extension point.
   3. Declare a 'factory' attribute, referencing an OperationFactory subclass that each contribution needs to extend.
       
3. Implement the base operation factory
    
   Contributed operations will need to have access to some variables related to the execution context. Such variable might be an instance of Model, a collection of model elements, etc. The variables involved are dependent on the actual extension point. Therefore it is the responsibility of the operation factory associated to the extension point to provide such variables, through dedicated getter methods.
    
   Below is an example of operation factory that demonstrates the recommended pattern for extension points:

   public abstract class MyAbstractOperationFactory implements OperationFactory {
   
       public static Operation createExtension(String extensionPoint, final String myVariable, OperationContext context) {
           return new ExtensionOperation<MyAbstractOperationFactory>(extensionPoint, context) {
   
               @Override
               protected void configure(MyAbstractOperationFactory factory) {
                   factory.myVariable = myVariable;
               }
           };
       }
   
       private String myVariable;
       
       protected final String getMyVariable() {
           return myVariable;
       }
   }
   

   The highlighted code is the one dependent to a particular extension point. The rest of the code is a general pattern that you are encouraged to adopt:
   • The factory provides a static createExtension() method to request the execution of contributed extensions.
   • The createExtension() method uses an ExtensionOperation instance to perform the actual execution the contributed extensions.
   • The configure() method is used to set all necessary variables on a factory (instantiated by extensions).
     • An alternative pattern is to define the createExtension() method in an external class and use some setter methods defined on the factory to set variables. The pattern presented here has the advantage to isolate completely the handling on factory's variables.
   • The getMyVariable() method provides access to the variable for subclasses.
      
   Note: this operation factory must be visible by contributors: the package owning the factory must be part of the 'Exported Packages' in the 'Runtime' tab of the MANIFEST.MF file.
    
4. Execute contributed extensions
    
   You have to request the execution of contributed extensions from an operation using a code like the following:

   public class MyMainOperation extends Operation {
   
       private OperationContext context;
       
       public MyMainOperation(OperationContext context) {
           this.context = context;
       }
   
       protected void run(IProgressMonitor monitor) {
       
           // execute the 'standard' transformation
           run(new TransformationOperation(context), monitor);
           
           // allow extensions to augment the scope of the transformation
           String myVariable = "whatever value is needed for the extensions";
           run(MyAbstractOperationFactory.createExtension("com.sodius.my-extension-point", myVariable, context), monitor);
       }
   }
   

5. Document the extension points
    
   You finally have to document the extension points defined in the transformation. The documentation shall provide details on the context of each extension point and the type of customization to perform by contributions. You are recommended to provide a Javadoc of the operation factories used by extension points, so the contributors can understand what variables are accessible through getter methods and what they are meant for.

Developing Operations