Modeling the XML Structure

Introduction

This is the third document in the introduction to TransacXML.

This document describes the basic rules of how to model an XML document in TransacXML.

You need to model the XML document to be able to process or create the XML documents.

Modeling rules

The following section describes the rules you need to know to be able to model an XML document in TransacXML.

The first two parts: "Object types and inheritance" and Complex element content" are the most important.

The "Namespaces" section is relevant for all documents that use namespaces. As this is a very common occurrence, this part is also recommended reading.

The rest of the modeling rules descriptions describe how to model special cases. You should have a look at them so that you know that there are solutions for these cases if you encounter them - but you do not need to go into details with them.

Object types and inheritance

This describes how XML objects are mapped to objects in the Plex model. All the referenced objects are found in the WSYXML model.

1. All complex elements are represented in Plex as entity-objects that inherit from XMLElement.
2. All complex elements that can occur more than once under one parent element are represented in Plex as entity-objects that inherit from XMLRepeatingElement (which inherits from XMLElement).
3. All simple elements are represented in Plex as fields that inherit from ElementFieldUT (often through ElementField).
4. All attributes are represented in Plex as fields that inherit from AttributeFieldUT (often through AttributeField).

Complex element content

The distinguishing property of complex elements is that they can contain structures. The complex element can contain other complex elements, simple elements, and attributes.

The content of the complex elements are modeled as follows:

1. The relation between a parent complex element and its complex child elements is modeled by ENT includes ENT triples.
2. The relation between a complex element and its simple child elements is modeled by ENT has FLD triples. When creating the complex element, the order of the "has" triples will determine the order of the simple elements.
3. The relation between a complex element and its attributes is modeled by ENT has FLD triples.

Namespaces

Namespaces are found in many real-life XML documents. TransacXML offers a way to assign namespaces to each of the object types.

1. For complex elements, let the entity inherit from the entity WSYXML/NamespaceAware.
2. For simple elements and attributes, let the field inherit from the field WSYXML/NamespaceAware.

In both cases, the object that inherits from NamespaceAware will get two new scoped source codes called Namespace and Prefix. By specifying values for the literals of these objects you can specify the namespace of the object and the prefix to use when creating the object in an XML document.

Text content in complex elements

In some cases, you can find complex elements that have text content in addition to the simple elements and attributes.

This construct is not very common in real-life documents.

For example:

In this document, the complex element MyElement contains two simple elements SubElement1 and SubElement2.

In addition to this, it contains text content (abcd).

Repeating simple elements

In some cases, a complex element has more than one simple child element with a specific name.

This construct is not very common in real-life documents.

For example:

In this case, the complex element "Comments" contains a number of simple child elements named "Comment".

This is modeled by letting the field Comment inherit from WSYXML/RepeatingElementField.

Inserting complex elements before simple elements

The default behavior of TransacXML is to insert the simple elements first, followed by the complex elements - as for example:

In many cases this is no problem, but if other parties have described the format, the following cases is possible:

Here, the complex element "complex" is places between the two simple elements. This means that you will have to be able to specify the position of the complex element in relation to the simple elements.

This is done by using a "ComplexElement" field. A field that inherits from ComplexElement is a placeholder that is only used to specify the position of the corresponding complex element (XMLElement) in relation to the simple elements.

The definitions for the above example would be (only the definitions relevant for the top element is shown):

Note that it is the sequence of the "has" triples that specifies the order of the elements. The relation between the ComplexElement field and the XMLElement is that the name is the same.

This is only relevant when creating documents. TransacXML does not use the specified order when reading documents.

Example

This will show how you manually can model an XML document in Plex using the rules described above.

Not all of the rules will be shown in the example; only the most common constructs will be shown.

The following example will show how to model the document introduced in the document explaining the structure of XML documents. If you have not already done so, it is recommended that you read this document.

When modeling XML documents in TransacXML, we follow the convention that all fields that belong to an XMLElement entity are scoped by the Fields function scoped by the entity. This convention ensures that you easily can find the fields used by a specific XMLElement - and that you can change the fields without influencing other documents.

However, you do not have to follow this convention, the patterns works as well when the fields are placed elsewhere. What is important for the patterns are that the fields have the correct inheritance and that the ENT has FLD triples are correct.

Model the complex element Race

The complex element "Race" is modeled as an XMLElement entity with two AttributeFields using the following triples:

The fact that "race" has a child element "Course" and a child element "Horses" is modeled using ENT includes ENT triples:

At this point, you have defined the entire content of the complex element Race:

Model the complex element Course

The complex element "Course" is modeled as an XMLElement entity with two ElementFields using the following triples:

After creating these triples, you have defined the entire content of the complex element Course.

Model the complex element Horses

The complex element "Horses" is modeled as an XMLElement without any fields.

"Horses" contains a number of "Horse" child elements. This is modeled as follows:

After creating these triples, you have defined the entire content of the complex element Horses:

Model the complex element Horse

The complex element "Horse" is modeled as an XMLRepeatingElement with an AttributeField and three ElementFields using the following triples:

After creating these triples, you have defined the entire content of the repeating complex element Horse - and the entire document:

Tip

If the fields you handle in the XML document maps directly with your existing database fields, consider inheriting from ElementFieldUT and AttribtuteFieldUT instead. By doing so you can also inherit from the corresponding database field - thus making the mapping of values between XML and database easier.

Example - namespaces

To show the modeling of namespaces, three namespace declarations have been added to the example document and all elements have been assigned to a namespace.

The basic definitions are exactly the same as for document with no namespaces. In the following description, only the additional definitions will be described.

Inheritance

This defines the elements as belonging to a namespace.

Assigning namespace and prefix

This inheritance provides two source-codes "Namespace" and Prefix" for each element.

To assign the specific namespace and prefix to each element specify the following literal values for these source codes:

Race.Namespace

    http://www.websydian.com/examples

Race.Prefix

    ex

Race.Course.Namespace

Race.Course.Fields.CourseName.Namespace

Race.Course.Fields.Address.Namespace

    http://www.websydian.com/examples/course  

Race.Course.Prefix

Race.Course.Fields.CourseName.Prefix

Race.Course.Fields.Address.Prefix

    co

Race.Horse.Namespace

Race.Horses.Horse.Namespace

Race.Horses.Horse.Fields.Value.Namespace

Race.Horses.Horse.Fields.DateOfBirth.Namespace

Race.Horses.Horse.Fields.Gender.Namespace

    http://www.websydian.com/examples/horse

Race.Horse.Prefix

Race.Horse.Horses.Prefix

Race.Horses.Horse.Fields.Value.Prefix

Race.Horses.Horse.Fields.DateOfBirth.Prefix

Race.Horse.Fields.Gender.Prefix

    ho

Tip

If you have a lot of elements in the same namespace, consider creating an abstract XMLElement and ElementField (and AttributeField if necessary) for the namespace. Let the abstract objects inherit from NamespaceAware and specify the values for namespace and prefix on these abstract Plex objects.

Inherit from these entities/fields instead of directly from the NamespaceAware objects. By doing so, you can be certain that the namespace and prefix are the same for all elements and attributes that should use this namespace. It also ensures that you only have to change one thing if the namespace changes.

Next document

More information

More information about modeling, creating and processing XML

Parts documentation for TransacXML

Other Uses documentation for TransacXML

Namespace declarations explained

Namespaces in TransacXML

ComplexElement Field