Versions Compared

Old Version 4

changes.mady.by.user Kirstin Seidel-Gebert

Saved on

compared with

New Version 5

changes.mady.by.user Kirstin Seidel-Gebert

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Published by Scroll Versions from space WBRIDGE and version 20.1c
Div
Classe2e-refDiv

Otp
Floatingfalse

Rp

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 informationa built-in mapping of XML to UML classes and vice versa:

  • Components: Services

    • Service exchanging document style/literal encoded messages.
      The mapping procedures are used, when mapping SOAP messages to UML classes and back.

      Note
      iconfalse

      The mapping procedures described below

    will

    • do not work with SOAP/RPC encoding.

    • REST Adapter and REST Service
      The mapping procedures are used, when mapping REST calls to UML classes and back.
  • Operations:Blob operation:

    Mapping of UML classes to XML documents is controlled by stereotypes assigned to class attributes and association ends.

    Multiexcerpt include
    MultiExcerptNameconversions
    nopaneltrue
    PageWithExcerptINTERNAL:_examples_BRIDGE

    Multiexcerpt include
    MultiExcerptNameurlUrl
    nopaneltrue
    PageWithExcerptINTERNAL:_examples_BRIDGE

    Controlling the Mapping by Using Stereotypes

    Stereotypes control how UML class properties (attributes and association ends) are serialized to an XML Documentdocument. 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 (also see Frontend Components).

    Stereotypes

    To control the mapping, the The following stereotypes are available:

    StereotypeDescriptionTagged Values
    (Description see below)
    Class
    <<XML>>

    Set this basic stereotype on class level to be able to apply the stereotypes listed below to the attributes. You can only apply one of these stereotypes at a time.

    		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
    Attribute
    All stereotypes listed below inherit from <<E2EAttribute>> which gives additional tagged values. In this context of XML-UML mapping, only externalName and order are relevant.

    externalName
    order

    <<XMLNamespace>>When this stereotype is applied to an UML property, it will be mapped to a XML namespace. The property must be of base type String<<XMLNamespace>>UML properties having a simple type are mapped to XML namespaces.
    • The prefix of the namespace is given by the property name.
    • The URI of the namespace is given in the property value.
    • 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.

    <<XMLElement>>When this stereotype is applied to an UML property, it will be mapped to an XML element.xmlNamespace
    xmlForm
    xmlFormat
    xmlArrayElement
    isNillable
    <<XMLAttribute>>

    When this stereotype is applied to an UML property, it will be mapped to an XML attribute. The property must be of simple type. If the property type is complex, the compiler will report an error.

    		xmlNamespace
    xmlForm
    xmlFormat
    <<XMLCharacters>>

    When this stereotype is applied to an UML property, its content will be mapped to a character stream. The property must be of simple type.

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

    		xmlFormat

    Tagged Values

    Tagged ValueLevelStereotypeDescriptionAllowed Values
    Classes
    classToXMLDefaultRootNameComposite<<E2EComposite>>

    Multiexcerpt include
    MultiExcerptNameclassToXMLDefaultRootName
    PageWithExcerptFrontend Components

    Noteinfo
    iconfalse

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


    		Default

    Multiexcerpt include
    MultiExcerptNamerootName_Default
    PageWithExcerptFrontend Components

    Type Name

    Multiexcerpt include
    MultiExcerptNamerootName_Type
    PageWithExcerptFrontend Components

    Variable Name

    Multiexcerpt include
    MultiExcerptNamerootName_Variable
    PageWithExcerptFrontend Components

    xmlNamespaceClass

    <<XML>>

    		Specify the XML namespace.a valid namespace
    xmlElementNameClass<<XML>>Specify the name of the XML root element.a valid element name
    isMixedClass<<XML>>

    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).
    isOrderedClass<<XML>>Specify 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 (default).
    Attributes
    xmlNamespaceAttribute<<XMLElement>>
     <<XMLAttribute>>

    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.

    ExampleExamples:

    • 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
    • Also, 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<<XMLElement>>
     <<XMLAttribute>>

    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<<XMLElement>>
     <<XMLAttribute>>
    <<XMLCharacters>>

    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
    • Parsing CDATA elements works out of the box, you do not need to
    set xmlFormat
    • set xmlFormat.
    		a valid format string (see Number Formatting or Date and Time Formatting)
    CDATAcompose string as CDATA
    isNillableAttribute<<XMLElement>>

    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>.

    Info
    iconfalse

    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
    orderAttribute

    <<XMLNamespace>>
    <<XMLElement>>
    <<XMLAttribute>>
    <<XMLCharacters>>

    		Use order Use 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:

    Image Removed

    Code Block
    {
	"aClass" : { "anArray" : ["A1", "A2", "A3"] };
}

    ...

    Code Block
    languagexml
    <aClass>
    <anArray>A1</anArray>
    <anArray>A2</anArray>
    <anArray>A3</anArray>
</aClass>

    ...

    Code Block
    languagexml
    <aClass>
    <anArray>A1</anArray>
    <anArray>A3</anArray>
</aClass>

    ...

    Code Block
    languagexml
    <aClass xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <anArray>A1</anArray>
    <anArray xsi:nil="true"/>
    <anArray>A3</anArray>
</aClass>

    ...

    Code Block
    languagexml
    <aClass>
</aClass>

    ...

    Code Block
    languagexml
    <aClass>
</aClass>

    ...

    Code Block
    languagexml
    <aClass>
</aClass>

    ...

    Code Block
    languagexml
    <aClass xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <anArray xsi:nil="true"/>
    <anArray xsi:nil="true"/>
    <anArray xsi:nil="true"/>
</aClass>

    ...

    Code Block
    languagexml
    <anotherClass>
    <anArray>A1</anArray>
	<anArray>A2</anArray>
	<anArray>A3</anArray>
</anotherClass>

    ...

    Code Block
    languagexml
    <AClassType>
    <anArray>A1</anArray>
	<anArray>A2</anArray>
	<anArray>A3</anArray>
</AClassType>

    ...

    Code Block
    languagexml
    <aClass>
    <anArray>A1</anArray>
    <anArray>A2</anArray>
    <anArray>A3</anArray>
</aClass>

    Examples

    externalName<<XMLNamespace>>
    <<XMLElement>>
    <<XMLAttribute>>
    <<XMLCharacters>>

    Sometimes names of XML attributes or elements do not comply with the rules specified on Syntax Scheme of the xUML Action Language. Use externalName to specify the name of the XML attribute or element, and specify a better name via the name of the UML property for internal usage.


    Examples

    Mapping Mixed Content XML to a UML Class

    Multiexcerpt include
    MultiExcerptNameurlUrl
    nopaneltrue
    PageWithExcerptINTERNAL:_examples_BRIDGE

    ...

    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:

    Image Modified

    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 ).

    ...

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

    ...

    Info
    iconfalse

    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.

    Arrays and XML Serialization

    The behavior of XML serialization in this case 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:

    Image Added

    Code Block
    {
	"aClass" : { "anArray" : ["A1", "A2", "A3"] };
}
    DescriptionXML result
    All values are present.
    Code Block
    languagexml
    <aClass>
    <anArray>A1</anArray>
    <anArray>A2</anArray>
    <anArray>A3</anArray>
</aClass>
    The second value (A2) is NULL and isNillable=false.
    Code Block
    languagexml
    <aClass>
    <anArray>A1</anArray>
    <anArray>A3</anArray>
</aClass>
    The second value (A2) is NULL and isNillable=true
    Code Block
    languagexml
    <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.
    Code Block
    languagexml
    <aClass>
</aClass>
    The array is empty.
    Code Block
    languagexml
    <aClass>
</aClass>
    All elements are NULL and isNillable=false.
    Code Block
    languagexml
    <aClass>
</aClass>
    All elements are NULL and isNillable=true.
    Code Block
    languagexml
    <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".
    Code Block
    languagexml
    <anotherClass>
    <anArray>A1</anArray>
	<anArray>A2</anArray>
	<anArray>A3</anArray>
</anotherClass>
    classToXMLDefaultRootName="Type Name" and xmlElementName="anotherClass".
    Code Block
    languagexml
    <AClassType>
    <anArray>A1</anArray>
	<anArray>A2</anArray>
	<anArray>A3</anArray>
</AClassType>
    classToXMLDefaultRootName="Variable Name" and xmlElementName="anotherClass".
    Code Block
    languagexml
    <aClass>
    <anArray>A1</anArray>
    <anArray>A2</anArray>
    <anArray>A3</anArray>
</aClass>