Page tree
Skip to end of metadata
Go to start of metadata

Mapping of UML classes to XML documents is controlled by stereotypes assigned to class attributes and association ends. Tagged value Class To XML Default Root Name on the composite controls the name that will be assigned to the root element (see Frontend Components).

The following operations and components are using this information:

  • SOAP Adapter and SOAP Services exchanging document style/literal encoded messages.

    The mapping procedures described below will not work with SOAP/RPC encoding.

  • Blob operation: xmlToClass()
  • String operation: xmlToClass()
  • Any type operation: classToXML()

Example File (Builder project E2E Action Language/XML):

<your example path>\E2E Action Language\XML\uml\xmlSimpleConversions.xml
<your example path>\E2E Action Language\XML\uml\xmlComplexConversions.xml

Example File (Builder project Add-ons/URL):

<your example path>\Add-ons\URL\uml\urlUrl.xml

Controlling the Mapping by Stereotypes

Stereotypes control how UML class properties (attributes and association ends) are serialized to an XML Document. If no stereotype is assigned, the following default rules apply for mapping XML to UML classes ( xmlToClass() ):

  • XML attributes are mapped to class attributes.
  • XML elements are mapped to class associations ends.
  • The XML root element is named according to the definitions in the service composite, tagged value Class To XML Default Root Name.

The following stereotypes are available:

StereotypeDescriptionTagged Values
(Description see below)
<<XML>>Set this basic stereotype on class level to be able to apply the stereotypes listed below to the attributes.xmlNamespace
xmlElementName
isMixed
isOrdered
<<XMLElement>>UML properties are mapped to XML elements.xmlNamespace
xmlForm
xmlFormat
isNillable
<<XMLAttribute>>

UML properties having a simple type are mapped to XML attributes.
If the property type is complex, the compiler will report an error.

xmlNamespace
xmlForm
xmlFormat
<<E2EAttribute>>This stereotype can be used to specify an order for  the generation of XML elements.order
<<XMLNamespace>>UML properties having a simple type are mapped to XML namespaces.
The prefix of the namespace is given by the property name. If the same namespace is declared more than once, the runtime will suppress namespaces further down the XML hierarchy, if prefix and namespace are identical. If not, the xUML Runtime will throw an exception.

<<XMLCharacters>>UML properties having a simple type are serialized as a character stream.xmlFormat

Tagged Values

Tagged ValueLevelDescriptionAllowed Values
classToXMLDefaultRootNameComposite

Bridge 7 Specify which name to assign to the XML root element upon serializing. This setting can be overridden by using XML composer options as described on classToXML() Operation.

If this tagged value is set to other values than "Default", tagged values xmlElementName and xmlNamespace on the <<XML>> class are disregarded.


Default

Try to use name and namespace defined on the class by the <<XML>> stereotype. Fallback to Variable Name if not provided (default).

Type Name

Use static name and namespace of the class as name of XML root element.

Variable Name

Use the name of the reference (object/variable) as name of XML root element.

xmlNamespaceClassSpecify the XML namespace.a valid namespace
xmlElementNameClassSpecify the name of the XML root element.a valid element name
isMixedClass

Specify whether the XML contains attributes that are serialized as character stream (attributes with stereotype <<XMLCharacters>>, see also Controlling the Mapping by Stereotypes).
For more information on mixed content, refer to Mixed Content.

trueXML contains serialized attributes.
falseXML does not contain serialized attributes (default).
isOrderedClassSpecify whether the class attributes should be serialized to XML using the order tag that has been specified on the attributes.trueSerialize in order of order tags from the attributes.
falseSerialize in order of attributes on class.
xmlNamespaceAttribute

Each XML attribute and element may have its own namespace. If the tagged value contains an URI, the runtime will automatically generate a unique prefix.

Example: A tagged value xmlNamespace = "http://e2e.ch" on the UML property anElement will result in the XML document <ns0:anElement xmlns:ns0="http://e2e.ch">.
However, it is possible to define the prefix by using the following syntax: 'xmlns:' <prefix name>  '=' <namespace uri>. For example,  tagged value xmlNamespace = 'xmlns:typens="http://e2e.ch"' of the UML property anElement will lead to the following XML fragment: <typens:anElement xmlns:typens="http://e2e.ch">.

an URI
a valid xlmns syntax
xmlFormAttribute

Depending on this tagged value, XML elements or attributes may not be qualified by a namespace prefix even if they have one.

qualified

The element or attribute must always be qualified by a namespace prefix. Default for XML elements.

unqualifiedNo namespace prefixes are allowed (for details see http://www.w3.org/TR/xmlschema-0/#NS). Default for XML attributes.
xmlFormatAttribute

If numbers and date/time types are parsed or composed, the XML parser respectively composer expects simple date types following the XML schema specification. However, legacy XML documents may contain different number and date/time formats. In this case, the tagged value xmlFormat may hold a format string. If numbers are parsed or composed use the format strings defined in section Number Formatting. If date/time expressions must be parsed or composed, use the format strings defined in Date and Time Formatting.

Use xmlFormat = "CDATA" together with stereotype <<XMLElement>> to compose strings as CDATA with classToXML() . Parse CDATA elements works out of the box, you do not need to set xmlFormat.
a valid format string (see Number Formatting or Date and Time Formatting)
CDATAcompose string as CDATA
isNillableAttribute

By default, UML properties that are NULL are not serialized into XML documents. However, if it is necessary to do so, isNillable must be set to true. In this case, the UML properties being NULL will look like: <aProperty xsi:nil="true"></aProperty>.

Some client code generators will use this attribute in the WSDL file for type generation. If false they will generate simple types, if true they will generate complex types.

trueserialize NULL properties
false (default)do not serialize NULL properties
orderAttributeUse this tagged value of <<E2EAttribute>> to specify the order in which the XML elements will be generated to the XML document.a valid float

XML Serialization

The behavior of XML serialization is not always self-explanatory but a consequence of the definition of arrays in XML schema.

The following table shows the behavior of XML serialization for the following class containing an array:

{
	"aClass" : { "anArray" : ["A1", "A2", "A3"] };
}
DescriptionXML result
All values are present.
<aClass>
    <anArray>A1</anArray>
    <anArray>A2</anArray>
    <anArray>A3</anArray>
</aClass>
The second value (A2) is NULL and isNillable=false.
<aClass>
    <anArray>A1</anArray>
    <anArray>A3</anArray>
</aClass>
The second value (A2) is NULL and isNillable=true
<aClass xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <anArray>A1</anArray>
    <anArray xsi:nil="true"/>
    <anArray>A3</anArray>
</aClass>
The array is NULL.
<aClass>
</aClass>
The array is empty.
<aClass>
</aClass>
All elements are NULL and isNillable=false.
<aClass>
</aClass>
All elements are NULL and isNillable=true.
<aClass xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <anArray xsi:nil="true"/>
    <anArray xsi:nil="true"/>
    <anArray xsi:nil="true"/>
</aClass>
classToXMLDefaultRootName="Default" and xmlElementName="anotherClass".
<anotherClass>
    <anArray>A1</anArray>
	<anArray>A2</anArray>
	<anArray>A3</anArray>
</anotherClass>
classToXMLDefaultRootName="Type Name" and xmlElementName="anotherClass".
<AClassType>
    <anArray>A1</anArray>
	<anArray>A2</anArray>
	<anArray>A3</anArray>
</AClassType>
classToXMLDefaultRootName="Variable Name" and xmlElementName="anotherClass".
<aClass>
    <anArray>A1</anArray>
    <anArray>A2</anArray>
    <anArray>A3</anArray>
</aClass>

Examples

Example File (Builder project Add-ons/URL):

<your example path>\Add-ons\URL\uml\urlUrl.xml

The following example shows how to convert an XML data structure with mixed content to an UML class.

If an XML element has attributes, this is called mixed content in Bridge context.

Suppose the following XML data structure with two elements street and city is given:

<address id="4711">
	<street id="4711-1">13, Coal Street</street>
	<city id="4711-2">New York, NY 10017, USA</city>
</address>

The class diagram below illustrates how to map the content of XML element street ("13, Coal Street") and the value of its attribute id ("4711-1") to a class structure:

To map XML element street and its attribute id, you need a dedicated class as a container. In this example, this is class StreetElement. XML attribute id of element street is mapped to class attribute id of UML class StreetElement via matching names. The content of the XML element street is mapped to the class attribute that has stereotype <<XMLCharacters>>. In this example this is text_value.
Class StreetElement must have stereotype <<XML>> and tagged value isMixed set to true because it contains the serialized attribute text_value (also see explanation of tagged value isMixed).

Containter StreetElement is associated to the main address class. The name of the association end (street) must match the name of the XML element. Associated class StreetElement is only a container for the street element and its name is not relevant for the mapping.

If the XML element contains attributes, which should not be mapped to UML class attributes, an association to a base type can be used. The example shows this for element city. The content of the element ("New York, NY 10017, USA") will be available in city (accessible as attribute of the instantiated class Address2Example1). As the id attribute cannot be mapped, it will be discarded when executing xmlToClass().

If an object of class Address2Example1 was serialized back in a SOAP response, the SOAP message would read:

<address2Example1 xmlns:ns1="urn:Services.URLService.URLPort.DataItems" xsi:type="ns1:Address2Example1">
    <id xsi:type="xsd:string">4711</id>
    <street xsi:type="ns1:StreetElement">
      	<id xsi:type="xsd:string">4711-1</id>
      	<text_value xsi:type="xsd:string">13, Coal Street</text_value>
    </street>
    <city xsi:type="xsd:string">New York, NY 10017, USA</city>
</address2Example1>

The same result could be obtained with the following class diagram:


You have the flexibility to map XML structures in different ways. You can define very compact class diagrams for simple XML structures, but you have also the possibility to map complex XML data structures graphically.

If an XML Schema is provided, you can import it with the Builder. It will generate all classes and relations according the XSD import rules described in XML Schema Import Rules. For how to use the XSD Importer refer to Importing WSDL or XSD.