FuGE | Guide to Extending FuGE (M3 Version)
A guide to extending FuGE
This page lays out a set of guidelines for how to extend FuGE. It is expected that developers are familiar with the Introduction to FuGE document and the UML model.
Developers should also view the rules governing the generation of XML Schema
These guidelines refer to the FuGE milestone 3 release.
The guide is divided into the following sections:
Method of Extension
We recommend that developers of extensions work in UML, and use the AndroMDA cartridge supplied to produce a working XML Schema.
Benefits of developing in UML:
- We believe that UML diagrams facilitate understanding of the model compared with developing an XML Schema directly.
- There are important differences between the semantics of classes and associations, which are clearly represented in UML but the difference is less obvious in XML Schema.
- The UML model can be used in conjunction with other templates for generating platform specific models, such as the framework for the Java STK and relational database definition.
- Documentation provided for classes and associations in UML is automatically updated in the generated XML Schema (and any other platform specific models developed from the UML).
Back to top
Extending Classes and Associations
FuGE provides certain classes that should be extended, using the inheritance mechanism provided in UML. It is also necessary that if two classes are extended and there is an (abstract) association in FuGE between the two superclasses, the corresponding association between the two new subclasses should also be extended by inheritance.
The following diagram shows a part of FuGE (Protocol and Equipment) and an extension model for a Column and ColumnProtocol.
The diagram above shows that Column extends from Equipment and ColumnProtocol extends from Protocol. The association between ColumnProtocol and Column fulfills the same role as the association from +protocolEquipment association. Therefore, the +column association extends from the +protocolEquipment association.
The importance of extending from associations is demonstrated by the following hypothetical example. The ProtocolApplication class has two associations to Data, for input data and output data. ProtocolApplication is extended to capture Normalization performed on microarrays. The Normalization protocol takes as input raw data, and produces processed data as output.
In the example above, the new associations do not extend from any FuGE associations. This could cause problems for any FuGE processing software for the new format because it is not clear what are the inputs and outputs to this ProtocolApplication. The following diagram demonstrates the correct method:
Once the inheritance associations have been drawn, they can be deleted from the diagram (but not the model) to make the diagram clearer.
Back to top
Associations between classes
FuGE supports two types of relationships between classes, inheritance (as described above) and associations. Associations can be set with a cardinality, a direction and a Containment value. The use of each of these settings correctly is particularly important for generating the desired XML Schema.
Directionality
Directionality defines whether one Association End is accessible from the other. Associations are either bi-directional, meaning each Association End is accessible from the other (hence both classes can traverse the relation), or unidirectional, meaning only one Association End is accessible and the relation can only be traversed in one direction.
In the example below, the associations are navigable from Gel2DApplication to Gel2DProtocol, and from Gel2DApplication to Gel2D.
Cardinality
Each Association End contains a specification for its cardinality, or how many instances of a Class can (or must) be reachable at the Association End. Allowable cardinalities include 0..1, 1, 0..* and 1..*.
The cardinality set at the navigable end affects the generation of XML Schema, in the number of allowable child elements. In the example above exactly one instance of Gel2DApplication must be associated with exactly one instance of Gel2D. Also, each Gel2DApplication must be associated with a Gel2DProtocol. Many instances of Gel2DApplication can be associated with a Gel2DProtocol but it is not mandatory that one is.
Containment
The containment of an association is typically set at the non-navigable end of a uni-directional association. The containment can be set as composition (filled diamond), aggregation (open diamond) and no containment. If composition is specified (as from Gel2DApplication to Gel2D above), this means that the instance of Gel2D cannot exist independently of Gel2DApplication. In the example, the association from Gel2DApplication to Gel2DProtocol has no containment specified, meaning that Gel2DProtocol can exist independently of Gel2DApplication.
The direction, containment, cardinality of an association affect the way in which the XML Schema is generated, as detailed in the XML Schema generation rules.
Back to top
Use of stereotypes
All classes that are added to the model should be assigned stereotypes, which signal to AndroMDA how to process the class in the production of the platform-specific models. Almost all classes should be assigned with the following stereotypes:
- XmlSchemaType - this signals to the XML Schema generation cartridge to convert the class to an element in the XML Schema.
- Entity - this signals to the cartridges for generating platform-specific models to treat this class as an entity. For example, this would map this class to a relation (table) in a relational database schema, and various Java classes in the Java STK.
In rare cases, a different stereotype should be used, Enumeration, which signals to AndroMDA that the class represents a list of allowable values. In the example, the types of action allowed for an audit are set as attributes on the AuditAction class that is assigned the Enumeration stereotype. The data type of the attribute action (on Audit) is set to AuditAction.
Stereotypes on associations
Stereotypes are also used on associations to signal how AndroMDA should map the association. The following diagram shows how the MapAssocToElement stereotype should be assigned to a particular association end:
In this case, there are parallel associations between the same element. In the XML Schema, an element is required to distinguish between the child elements. By assigning the MapAssocToElement stereotype to +inputFirstDimension and +inputSecondDimension, the following XML instance would be produced:
<Gel2D identifier="exp001:gel2D:1">
<inputFirstDimension>
<Gel separationDimension="1" identifier="exp001:gel1">
...
</Gel>
</inputFirstDimension>
<inputSecondDimension>
<Gel separationDimension="2" identifier="exp001:gel2" >
...
</Gel>
</inputSecondDimension>
</Gel2DApplication>
Note: in the following cases the MapAssocToElement stereotype should be used:
- Parallel associations between the same classes (as above).
- All associations to OntologyTerm or Description where the context or purpose of the association is given by the association name.
- Any cases where it would be useful to specify an additional qualification about the role of the association (such as specifying inputs or outputs to a ProtocolApplication).
Back to top
Classes to extend
Certain classes should be extended in models developed from FuGE. These classes include: Protocol, ProtocolApplication, Action, Software, Equipment,Parameter, Material, Data, Dimension, DimensionElement and ConceptualMolecule. Follow the links to see a guide for extending each FuGE class.
Note that all these classes are abstract. As a general rule, only abstract classes should be extended, although not all FuGE abstract classes can be extended.
Back to top
