Adding Signatures to Models

Signatures are pieces of information stored in a model. These pieces of information describe the components that must be installed in order to properly load the model. If a user opens a model with a signature that cannot be found in their runtime then the user is provided with the information stored in the signature.

The DevOps Modeling Platform uses signatures in its files to differentiate between different types of artifacts and to allow certain of its optional components to mark the fact that they were installed into the user's runtime when the file was last modified. Signatures can be used by clients extending the DevOps Modeling Platform to likewise, mark the fact that they were used to modify a model file. The modeling platform will inform the user if they attempt to open the model file without this component installed.

Domain Modeling clients may introduce the signature framework into their resources and editing domains. More detailed information on this topic is outlined in the Using Signatures in Domain Modeling section below.

Registering a Signature

A signature is registered through the com.ibm.xtools.emf.core.signatures extension point. The signature must be associated with at least one feature (component) in the eclipse runtime. This feature information should be enough to inform a user about how they should go about installing the missing feature in order to load the model properly. The feature information provided generally includes a name that the user will understand, a URL that can be used to read about this feature, a specific version number and a short description of the functionality of the feature.


   <extension
         point="com.ibm.xtools.emf.core.signatures">
      <signature
            id="com.ibm.foo.someSignature"
            version="1.0">
         <feature-association
               name="Foo Component"
               url="http://www.example.com/rmp"
               version="1.0.0">
            The Foo component allows the user to do Bar.
         </feature-association>
      </signature>
   </extension>

Once a signature is registered then it can be associated to one or more Eclipse content types or editing domain identifiers. The association can be registered separately from the signature itself. There must be at least one in order for the signature to be used. Common UML modeler content types can be found here that can be used to register new signatures for those types of files.


   <extension
         point="com.ibm.xtools.emf.core.signatures">
      <signature-association
            contentTypeIds="com.ibm.xtools.uml.msl.umlModelContentType"
            signatureId="com.ibm.foo.someSignature"/>
   </extension>

Signatures can also play a role in migrating older models. Signatures are registered with a version to allow model migration participants to be registered against a particular version of a signature.

Using Signatures in Domain Modeling

The IRMPResource is the only EMF resource implementation that is capable of serializing signatures. After loading a model with missing signatures, an IRMPResource will have special UnknownSignatureDiagnostic in its warnings list with the missing feature information. Normally, an application will present a dialog to the user if one of these diagnostics is found in the warnings list after a model has been opened.

The RMPResourceFactory is available for clients to create an IRMPResource. Alternatively, this factory can be registered against the "org.eclipse.emf.ecore.extension_parser" extension point to ensure that EMF uses this resource implementation along with its signature capabilities.


   <extension
         point="org.eclipse.emf.ecore.extension_parser">
      <parser
            class="com.ibm.xtools.emf.core.resource.RMPResourceFactory"
            type="someFileExtension"/>
   </extension>

Note: Whenever an IRMPResource is saved, there must be at least one signature present. Otherwise, the resource will assume that it must be migrated the next time it is loaded.


Legal notices