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.
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.
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.