7.4 XML types import/export format

7.4 XML types import/export format

The schema of MetaEdit+ XML Types files is similar to that of XML Models files: a gxl tag containing graph tags. The XML namespace for the types files is http://www.metacase.com/gxlGOPRRType. Here is an overview of an XML types file:

 1  <gxl xmlns="http://www.metacase.com/gxlGOPRRType">
 2    <graph typeName="My Graph">
 3      <slot name="My Graph Name">
 4        <property typeName="Graph Name">
 5          <dataType>
 6            <simpleType>String</simpleType>
 7          </dataType>
 8        </property>
 9      </slot>
10      <object>...</object>*
11      <relationship>...</relationship>*
12      <role>...</role>*
13      <binding>
14        <relationship href="#..."/>
15        <connection>
16          <cardinality start="0" stop="N"/>
17          <role href="#..."/>
18          <object href="#..."/>
19        </connection>
20      </binding>*
21      <decomposition>...</decomposition>*
22      <explosion>...</explosion>*
23      <report>...</report>*
24      <constraints>...</constraints>
25    </graph>
26  </gxl>

In line 2, the typeName is the user-visible name of this Graph type.

Lines 3–9 define the same information as is found in one row of the properties table in the Graph Tool; this block is repeated once for each property in the graph type. Line 3 defines a property slot with local name “My Graph Name”: if the name is omitted, it is taken from the property type. Line 4 starts the definition of the property type for this slot: the name of the property type is “Graph Name”. Lines 5–7 define the data type for values of this property type, in this case String.

Lines 10–12 define the object, relationship and role types that can be in this graph type, i.e. the information found in the Graph Tool Types tab. Each of these lines can be repeated multiple times (as shown by the asterisk), and will consist of similar slot definitions to lines 3–9. The types can also contain tags specifying a symbol, as we will see below.

Lines 13–20 are an example of a binding, as would be found in the Graph Tool Bindings tab; again, this block will be repeated once for each binding. Normally, the relationship, role and object types mentioned here will be href references to types already defined earlier in the file. For the way references work, please see Section 7.2.3.

Lines 21 and 22 specify the subgraphs for this graph type, and will be described later. If a subgraph type has not been defined earlier, its definition will be included inline within these elements.

Line 23 will be repeated once for each generator – note that for backwards compatibility the old term for a generator, “report”, is used here. The generators are specified as text between <report> and </report>, with the necessary XML escape sequences. We expect most external programs will not supply generators as part of these files, adding them instead later with the Generator Editor. To avoid a new version of the metamodel deleting these generators, supplying no report elements will leave any existing generators in place. To delete all existing generators in a matching type, supply a single empty <report/> tag.

Non-Property type elements: graph, object, role, relationship

Non-Property types all have a similar structure for their own element and its slot sub-elements. Let us look first at the main element and its attributes:

<graph
  description="A WatchApplication diagram defines the state automaton that implements a logical watch or a watch application."
  id="Graph_ClockApplication_sysadmin_3150525787"
  type="Graph_ClockApplication_sysadmin_3150525787"
  typeName="WatchApplication">

The description attribute contains the text from the Description field of the Graph Tool etc. The id attribute is used when referring to this type elsewhere in the XML file: it need only be unique. The type and typeName attributes are used to name the type, and to recognize it as matching an existing type, so the XML import will update that type.

A type in an XML file is recognized as matching an existing type of the same meta-type if either of the following is true: the type attribute exactly matches the internal name of the existing type, or the typeName attribute matches the user-visible name of the existing type. The GOPPRR meta-type names, e.g. Object, may not be used as values for either attribute.

In general, we expect the type attribute to be used only for files exported from MetaEdit+. As internal type names are unique, they are also used as the value of the id attribute when exporting from MetaEdit+. For files created in other programs, simply supply the typeName attribute, and any unique string for the id attribute.

Each property in a type is represented with a slot element providing information about that slot, and containing a property sub-element with the definition of the property type (or an href reference to it).

<slot
  id="a0hedn"
  name="Application name"
  unique="false">
    <property ...> ...
    </property>
</slot>

The slot id is the internal name of the slot: it can be composed of letters and numbers, but must begin with a letter. If omitted, MetaEdit+ will create naïve names p1, p2 etc., but if imported types are edited and re-imported, there is a possibility that the naïve name will clash with an earlier name. The name attribute is the local name of that property in this type, and unique specifies whether values of the property must be unique over all instances of this type (checked only when manually creating new instances).

Property types

A property type has the same attributes as non-property types, but a different set of sub-elements specifying the data type and dialog widget for values of this property:

<property 
  description=""
  id="Property_Name_sysadmin_3150525691"
  type="Property_Name_sysadmin_3150525691"
  typeName="Name [Watch]">
    <dataType>
        <simpleType>String</simpleType>
    </dataType>
    <widget>Input Field</widget>
</property>

DataType values can be either simple or complex. The simple values are those that can be seen directly in the Datatype choice dialog in the Property Tool: String, Text, Number, Boolean, Creation Timestamp, or Collection. These are enclosed as XML text within a simpleType tag.

If the data type is a simple String, you can optionally supply a <widget> used to edit values of that type. The default value is Input Field, but you can supply any of the values shown in the Widget choice dialog of the Property Tool (except SOAP Fixed List). If you supply one of the List widgets or a Radio Button Set widget, you must also supply a defaultValue and a set of listValues:

<property typeName="TestRadioButtons">
    <dataType>
        <simpleType>String</simpleType>
    </dataType>
    <defaultValue>
        <string>a</string>
    </defaultValue>
    <widget>Radio Button Set</widget>
    <listValues>
        <string>a</string>
        <string>b</string>
        <string>c</string>
    </listValues>
</property>

If the dataType is Collection, an extra contentsDataType element must be supplied. Its content is either a simpleType element containing String, or a graph, object, relationship, role or port element defining the contents type (or referring to it with href).

<property typeName="TestStringCollection">
    <dataType>
        <simpleType>Collection</simpleType>
    </dataType>
    <contentsDataType>
        <simpleType>String</simpleType>
    </contentsDataType>
</property>

<property typeName="TestGraphCollection">
    <dataType>
        <simpleType>Collection</simpleType>
    </dataType>
    <contentsDataType>
        <graph href="#MyGraph1"></graph>
    </contentsDataType>
</property>

Properties whose values are objects are represented directly with an object element inside the dataType element; similarly for other non-properties:

<property typeName="TestGraphProperty">
    <dataType>
        <graph href="#MyGraph1"></graph>
    </dataType>
</property>

Symbols

The vector graphics information for symbols is represented in the W3C SVG format using the 1.2 Tiny profile, which is more than adequate for our graphics needs. The extra information needed for MetaEdit+ symbols, e.g. connectables and conditional symbol elements, is represented in the namespace http://www.metacase.com/symbol.

Subgraphs

The graph element can also include decomposition and explosion elements that specify the legal subgraph types. Decomposition has an object and a graph, and explosion has an object, relationship or role, plus a graph. The graph elements may contain the definition of the graph type, or an href reference to the graph type defined elsewhere in the file.

<decomposition>
  <object href="#..."/>
  <graph href="#..."/>
</decomposition>
<explosion>
  <object href="#..."/>
  <graph href="#..."/>
</explosion>

Constraints

The constraints specified in the Graph Tool are exported in a constraints element of the graph element. Each constraint has its own tag, named after the type of constraint: connectivity, occurrence, uniqueness, portSame or portDifferent. The sub-elements of the constraints correspond to the fields in the definition dialog for that type of constraint.

<constraints>
  <connectivity>
    <object href="#..."/>
    <role href="#..."/>
    <max>1</max>
  </connectivity>
</constraints>

As the types mentioned in constraints will generally have been defined earlier in the graph element, their tags here will normally refer to them with href. Note though that the property in the port constraints is represented as a simple string, the local name of the property.