Correspondence between an XML string and an EGL variable

This topic describes the EGL record or handler that corresponds to an Extensible Markup Language (XML) string. Other topics describe the serviceLib.convertFromXML and serviceLib.convertToXMLfunctions that are used by a Rich UI developer to convert XML data to or from a variable, as might be necessary to access a third-party REST service.

XML and EGL records or handlers

You can define an EGL Record or Handler type that is the basis of a record (or array of records) used to process an XML string. The type includes details that are found in an XML Schema, which is a language for validating an XML string.

When you use the function XMLLib.convertToXML, you write the content of the EGL record to an XML string. When you use the function XMLLib.convertFromXML, you write the XML string into the EGL record; and if the string does not fulfill a validation rule specified in the record, the EGL Runtime issues a RuntimeException.

In a Rich UI application, XML may be the format of a message sent to or received from a REST service, but is never the format used in relation to a web (SOAP) service. The EGL Rich UI Proxy expects the data submitted from the application to a web (SOAP) service to be in JavaScript™ Object Notation (JSON) format, and the Proxy returns web (SOAP) service data to the application in JSON format.

Here is an example XML string, which is shown on several lines for clarity:
<Employee>
   <EmpNo>10</EmpNo>
	   <Name>Smith</Name> 
</Employee>
Here is a Record type that matches the example XML string:
Record Employee {XMLValue = XMLStructureKind.sequence}
   EmpNo INT;
   Name STRING;
end

In most cases, the Record type includes a set of field names that each match (in character and case) the name of an element or attribute in the XML string. If the names do not match, you use EGL properties to specify the XML element or attribute name.

EGL support for XML has two aspects:
  • Assigning the XML string from a record. If you are converting a record to an XML string, you can accept defaults when creating the string or can explicitly specify details such as the name that the EGL Runtime assigns to an element or attribute in the XML string.
  • Validating the XML string being written to a record. If you are writing an XML string to a record, the EGL Runtime issues a RuntimeException in the following cases:
    • An element or attribute name does not match an equivalent record-field name (or does not match an override that you specify in a property field); or
    • There is a mismatch in the structure of the XML string and the related record.

Keep in mind this twofold usage: in one case, for XML-string assignment, and in another case, for validation.

Here is an example of an XML string that includes an attribute:
<Sample color="green"></Sample>
The attribute value for color is stored in a second record. The two Record types are as follows:
   Record root 
    		Sample Sample? {@XMLElement {nillable = true}};
   end
   
   Record Sample {@XMLValue = XMLStructureKind.simpleContent}
      color STRING {@XMLAttribute{}};
      value STRING;
	 	end
The EGL Runtime can read the XML shortcut (<Sample color="green"/>), but can write only the longer form:
  • The written output is as follows if root.Sample is an empty string (""):
    	<root><Sample color="green"></Sample></root>
    
  • The written output is as follows if root.Sample is null and if (as mentioned later) the property field nillable is set:
    <root><Sample xsi:nil="true></Sample></root>
    
Here is a third example XML string:
<Employee>
   <EmpNo department="Sales">10</EmpNo>
   <Name>Smith</Name>
</Employee>
Here as the two Record types:
Record Employee{XMLStructure = xmlStructureKind.sequence}
   EmpNo EmpNumber;
   LastName STRING;
end

Record EmpNumber {XMLStructure = xmlStructureKind.simpleContent}
  	detypement STRING {@XMLAttribute{}};
   	value INT;
end
Any of the following data types is valid for a Record field:
  • STRING or one of the following types, which are assignment-compatible with STRING: FLOAT, BIN, or one of the integer equivalents to BIN (INT, SMALLINT, or BIGINT).
  • A data item that is based on one of those primitive types.
  • Another non-structured Record type. The fields of that type are restricted to the previously stated types or to another non-structured Record type. A Record type referenced within a Record type can only include fields of the types listed here.
  • Arrays of the preceding types.

Fields of type ANY are not supported.

One Record type can be referenced from another Record type at any level of nesting.

Nullable fields

A record field related to an XML element may be nullable as indicated by a question mark. For example, the following EmpNo field is not nullable, but the name field is:
Record Employee
   EmpNo INT;
   Name STRING?;
end
Two rules apply when the EGL Runtime is reading an XML String into a record:
  • If the field (for example, EmpNo) is not nullable, the EGL Runtime throws a RuntimeException when trying to read an element that is missing or has no value
  • If the field (for example, Name) is nullable, the EGL Runtime does not throw an exception when trying to read an element that is missing or has no value; and in the latter case, any attributes in the valueless element are retained

For details on the different ways the EGL Runtime treats a null when writing a record to an XML string, see the XMLElement or XMLRootElement annotation, nillable field.

Type annotations

You can use the following annotations when you define a Record or Handler type:
  • The XMLRootElement annotation provides naming and data-type details about the root XML element, which is the topmost, most inclusive element in the XML string.
  • The XMLValue annotation identifies the characteristics of a set of XML elements.

You cannot override those annotations when you declare a record based on the Record type.

Field annotations

You can use the following annotations when you define a field in a Record or Handler type or when you declare a variable based on that type:
  • TheXMLElement annotation provides details for a record field that represents an XML element. By default, that annotation is in effect.
  • The XMLAttribute annotation provides details for a record field that represents an XML attribute.

Namespaces

Rich UI supports reading and writing XML strings that contain namespaces. You can reference a namespace in the following annotations: RootElement, XMLElement, and XMLAttribute.

If the XML contains a default namespace, you must reference the namespace when defining the record fields for each XML element in that namespace. Note that an XML attribute is never in a default namespace; an attribute either has a namespace prefix or is not in a namespace.

Additional information on XML

Many web sites give background detail on XML and on the most popular XML-validation format, XML Schema (XSD). Here are a few suggestions that are present at this writing:
  • W3 Schools offers XML and XSD tutorials, which you can access at the following site, where you search for XML or XSD:

                 http://www.w3schools.com

  • Both XML and XSD are covered in SOA for the Business Developer by Margolis and Sharpe (MC Press, May 2007), which is available from the following site:

                 http://www.mc-store.com/5079.html

  • A detailed overview of XML Schema is available from the World Wide Web Consortium:

                 http://www.w3.org/TR/xmlschema-0/

To gain a full understanding of the alternatives available to you in EGL, review the topics for the XML-related annotations. Also note the EGL Runtime issues an XMLProcessingException in some cases, as stated in “eglx.xml package.”