Extension guide

Extension guide

Introduction and guideline

General extension rules

DATEX II models can be extended using extensions. The following conditions must be kept in mind:

  • DATEX can be extended with application specific extensions.
  • Extensions are recommended to be done in the UML model. Users are strongly discouraged to manually edit the generated schemas.
  • A level A model can be extended and will then become a Level B if the Level B extensions rules are respected. If not, the model will become a Level C model.

Level B Extension rules

The following rules apply to level B extensions:

  • a Level B extension is an extension that preserves interoperability between Level A and Level B.
  • a Level B extended client- or sever interface will have the same target namespace and version as the Level A version.
  • a Level B extended client will function with a non-extended server as long as server interface and client interface have the same version number.
  • a Level B extended server interface will function with a non-extended client interface as long as the interfaces have the same version number.

UML extension rules

The following rules are applicable to UML usage:

  • extensions shall be placed in the Extension package.
../_images/projectBrowser_small.jpg
  • each extension shall have its own package in the Extension package either stereotyped as D2Package or D2Namespace.
  • It’s recommended to put new extensions in a D2Namespace, however a D2Namespace can include more then one extension.
  • For a D2Namespace package, Select the newley created D2Namespace and enter values for the following tagged values
    • Definition – a description of namespace
    • Prefix – the prefix that should be used in the generated XSD for this namespace.
    • Version – Version number (optional)

Below is an example of an extension called MyLevelBextension.

../_images/mylevelbextension_extensionguide.jpg
  • When extending existing classes and enumerations, existing UML constructs from the DATEX II UML profile should be used. This is done by dragging a new class or enumeration from the resources tab, to the extension package. To indicate that a class or Enumeration is extending an existing element the D2LevelBExtension UML construct shall be used.
../_images/resources_small.jpg
  • All rules and constrains specified in CEN/EN 16157-1 / the Modelling methodology document shall be followed.
  • It is not allowed to change anything in the Level A packages/namespaces.

Extending Classes

  • To extend a Class, create a new Class by dragging a D2Class from the resources tab, to the extension package or a diagram in the extension package. To indicate that a class is extending an existing element, the D2LevelBExtension UML construct shall be used.
  • The new Class extends an existing(Level A) class. In the following example the ExtendedPublicEvent extends the PublicEvent Class from Level A.
../_images/extendedpubliceventextendprubliceventfromlevela_extensionguide.jpg

To new classes it’s allowed to

  1. Add new attributes, using existing or new data types and enumerations.
  2. Add new relations to new or existing classes.
  • For D2Relation or D2LevelBExtension: click on the D2Relation or D2LevelBExtension stereotype in the DATEX UML profile tree in the “Resources” tab. Then with that still highlighted, drag between two classes in a class diagram to create a new D2Relation or D2LevelBExtension.
../_images/d2relationford2levelbextension_extensionguide.jpg
  • For all other kinds of model element: drag the relevant stereotype from the profile onto the class diagram.
  • It’s not allowed to make specializations of an extended class. (This is just to make it simple)
  • It’s not allowed to extend an extension class (a class that is a specialization of a level A class using the D2LevelBExtension UML construct)
  • It is not allowed to change anything in the Level A packages/namespaces.
  • It is allowed to let a class in the extension package derive from classes in the non-extended part. Example of this is to create new datatypes or new datavalues.

Below is an example of a valid extension of a class extended by a new attribute(numberOfParticipants) and a relation to a new class(Address).

../_images/validextension_small.jpg

Extending Enumerations

  • To extend an enumeration, create a new enumeration by dragging a D2Enumeration from the resources tab, to the extension package or a diagram in the extension package. To indicate that an enumeration is extending an existing element, the D2LevelBExtension UML construct shall be used.
  • The new enumeration extends an existing(Level A) enumeration. In the following example the ExtendedPublicEventTypeEnum extends the existing PublicEventTypeEnum from Level A.
../_images/publiceventtypeenum.jpg
  • To new enumerations it’s allowed to add new enumeration literals.

XSD extension rules

The following rules are implemented by the tool and defined by the methodology document. They are described here for those that are interested.

  • the tool shall name the schema DATEXIISchema_[X]_[Namespace].xsd. Where X is the version of the UML model(modelBaseVersion tagged value) and Namespace is the name of the package stereotyped as namespace from the UML model.
  • the namespace for the Level A schema should be set to http://datex.eu.org/datexII/schema/[X]/[Namespace]. Where X is the version of the UML model(modelBaseVersion tagged value) and Namespace is the name of the package stereotyped as namespace from the UML model.
  • extensions are generated in their own namespace and schema file separate from the other DATEX II namespaces and schema files. The tool shall resolve relations and imports of required schemas.
  • when generating the Schema all complexTypes get an extra element [classname]Extension of the type ExtensionsType which is defined as follows
<xs:complexType name="_ExtensionsType">
  <xs:sequence>
    <xs:any namespace="##any" processContents="lax" minOccurs="0" maxOccurs="unbounded"/>
  </xs:sequence>
</xs:complexType>

This means that every class can be extended with anything and, if extended, it’s known where the extension can be found.

  • when the tool finds an extension class, by looking for the D2LevelBExtension construct, it shall generate a type that looks like:
<xsd:complexType name="_MyClassExtensionsType">
  <xsd:sequence>
    <xsd:element name = "myClass" type ="Namespace:MyClass" minOccurs="0">
    <xs:any namespace="##other" processContents="lax" minOccurs="0 maxOccurs="unbounded"/>
    </xsd:any>
  </xsd:sequence>
</xsd:complexType>

Note

_[ClassName]ExtensionsType will be used as type on [Classname]Extension element instead of _ExtensionsType.

  • if a class has two extensions, both of them will be added in list in the _[ClassName]ExtensionsType complexType. This means that a non extended client knows that there are some extensions points but does not care what they are. We still have a strict validation of the core part of the schema.
  • when the tool finds an extended enumeration, by looking for the D2LevelBExtension construct, it should generate a new type that looks like:
<xs:simpleType name="_"EnumerationNameFromUMLModel"ExtensionType">
  <xs:restriction base="xs:string">
    <xs:enumeration value=NameOfLiteralFromExtension />
    ...
  </xs:restriction>
</xs:simpleType>
  • if in a level B model one or more level B extensions exist for a DATEX II enumeration, the literals specified in all these extensions are collected in one type described above.
  • this new type will be used as the type for the attribute _extendedValue in the definition of the enumeration (replace type=”xs:string”)
<xs:complexType name="_"EnumerationNameFromUMLModel>
  <xs:simpleContent>
    <xs:extension base=Namespace:EnumerationNameFromUMLModel>
      <xs:attribute name="_extendedValue" type="xs:string" />
    </xs:extension>
  </xs:simpleContent>
</xs:complexType>
  • an enumeration value “_extended” is automatically generated for all “D2Enumeration” classes in support of compatible extensions.

Note

The solution allows a Level A instance to validate against any Level b extended model/schema as long as the modelBaseVersion is the same. An extended Level B instance can be validated against any Level A schema as long as the modelBaseVersion is the same.

Known limitations

There are two known limitations.

  1. An extended level B instance cannot validate against another extended level B Schema.
  2. It’s not possible to sensibly extend abstract classes from Level A, due to the fact that the D2LevelBExtension mechanism does not provide real polymorphism. Hence, the extension could not be instantiated. To solve this limitation for SituationRecord and Publication classes in Level A, two concrete hook classes have been created; GenericPublicaiton and GenericSituationRecord. Use this to derive new types of Publications and SituationRecords.

Validation

The next image gives an overview of situation where successful validation is possible.

../_images/overviewvalidation.jpg

V[X] means Version of the interface where 1 and 2 is the version number. A means a Level A model / schema / interface B1, B2 means a Level B model / schema / interface. But they are different extensions. The arrows show between which interfaces successful validation can be performed. If there is no arrow between two interfaces then successful validation cannot be done

Level C Extension rules

The following rules apply to level C extensions:

  • a Level C extension is an extension that has no interoperability between Level A and Level C.
  • a Level C extended client- or sever interface will not have the same namespace as Level A.
  • a Level C extended client shall function with a server that has implemented the same level C extension.
  • a Level C server interface shall function with a client that has implemented the same level C extension.

UML extension rules

The following rules are applicable to UML usage:

  • a Level C extension can in principle change and modify anything of the D2Logical model Level A part. But it’s recommended that the rules below which are similar to Level B extensions are followed.
  • extensions should be placed in the Extension package.
../_images/projectBrowser_small.jpg
  • each extension should have its own package in the Extension package.
  • it’s only recommended to extend existing classes with new attributes and compositions. This is done by adding a new class, to the extension package. The new class is a specialization of an existing(Level A) class. This is done by using the ordinary UML Generalization construct.
  • as compatibility is not preserved with Level A anything can in theory be changed in Level A part. A change will be detected by the tool and the model will be a Level C model.
  • all rules and constrains specified in CEN/EN 16157-1 / the Modelling methodology document shall be followed.
  • it’s not recommended to change anything in the Level A packages / namespaces.
  • the tool shall check compliance with level A and B when loading a model(XMI). If it detects that something has been changed in level A part in a non Level B valid way the tool shall classify the model as a level C model.

XSD extension rules

To make sure the namespace name and the schema name is not the same for Level C and Level A and B the beginning of the names are read from the configuration file. The schema name will begin with LevelC and the namespace will begin with http://levelC/schema. These two values can be changed in the configuration file.

Importing and exporting extensions

Importing and exporting extensions are preferable done with XMI. In EA you highlight the package in the project Tree and choose import / export and the either “import package from XMI file” or “export package from XMI file”.

Import dialog looks like this

../_images/importPackagefromXMI_small.jpg

Select the file and press Import. | The export dialog looks like this.

../_images/exportDialog_small.jpg

Choose file name and make sure the selections and versions of XMI is as above.Press Export.

Sharing extensions

Extensions in XMI format can easily be shared, because it’s just a file. If you have an extension that is used by more then one, please share this extension on the website www.datex2.eu. There is a extensions directory where you can upload your extension (XMI, UML model, XSD and documentation). Known extensions can be candidates for inclusion in future versions of DATEX.