Copying an XML string to and from an EGL variable

You can define an EGL record that corresponds to an Extensible Markup Language (XML) string. Rich UI developers use the serviceLib.convertFromXML and serviceLib.convertToXML functions to convert XML data to or from a variable, as might be necessary to access a third-party REST service. For detailed information about those functions, see the related links at the end of this topic. The last section in this topic includes sources of additional information about XML.

XML and EGL records

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

When you use the XMLLib.convertToXML function, you write the content of the EGL record to an XML string. When you use the XMLLib.convertFromXML function, you write the XML string into the EGL record. If the string does not fulfill a validation rule that is specified in the record, the EGL runtime code issues an RuntimeException.

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 part that matches the example XML string:
Record Employee {XMLStructure = xmlStructureKind.sequence}
   EmpNo INT;
   Name STRING;
end

In most cases, the Record part 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 either accept the defaults when you create the string or explicitly specify details, such as the name that the EGL runtime code assigns to an element or attribute in the XML string.
  • Validating the XML string that is being written to a record. If you are writing an XML string to a record, the EGL runtime code 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
    • There is a mismatch in the structure of the XML string and the related record.
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 parts are as follows:
   Record root 
    		Sample Sample? {@XMLElement {nillable = true}};
   end
   
   Record Sample {@XMlStructure = xmlStructureKind.simpleContent}
      color STRING {@XMLAttribute{}};
      value STRING;
	 	end
The EGL runtime code can read the XML shortcut (<Sample color="green"/>), but can write only the longer form:
  • If root.Sample is an empty string (""), the written output is as follows:
    	<root><Sample color="green"></Sample></root>
  • If root.Sample is null and the nillable property field is set, the written output is as follows:
    <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 are the two Record parts:
Record Employee{XMLStructure = xmlStructureKind.sequence}
   EmpNo EmpNumber;
   LastName STRING;
end

Record EmpNumber {XMLStructure = xmlStructureKind.simpleContent}
  	department STRING {@XMLAttribute{}};
   	value INT;
end
For a Record field, any of the following data types is valid:
  • 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 part. The fields of that part are restricted to the previously stated types or to another non-structured Record part. A Record part that is referenced within a Record part can include only fields of the types listed here.
  • Arrays of the preceding types

Fields of type ANY are not supported.

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

Nullable fields

A record field that is related to an XML element might be nullable; a nullable record field is 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 code is reading an XML String into a record:
  • If the field (for example, EmpNo) is not nullable, the EGL runtime code 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 code 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 about the different ways the EGL runtime code treats a null when writing a record to an XML string, see the @XMLElement and @XMLRootElement properties or the nillable property field.

Record part properties

You can use the following properties when you define a Record part:
  • The @XMLRootElement complex property provides naming and data-type details about the root XML element, which is the topmost, most inclusive element in the XML string.
  • The XMLStructure simple property identifies the characteristics of a set of XML elements.

For more details about those properties, see “@XMLRootElement” and “XMLStructure” in the help contents.

You cannot override those properties when you declare a record based on the Record part.

Record field properties

You can use the following properties when you define a field in a Record part or when you declare a record based on the Record part:
  • The @XMLElement complex property provides details for a Record field that represents an XML element. By default, that property is in effect.
  • The @XMLAttribute complex property provides details for a Record field that represents an XML attribute.

For more details about those properties, see “@XMLElement” and “@XMLAttribute” in the help contents.

Namespaces

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

If the XML contains a default namespace, you must reference the namespace when you define the record fields for each XML element in that namespace. 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 contain background information about XML and on the XML-validation format, XML Schema (XSD):

To gain a full understanding of the alternatives available in EGL, review the topics for the XML-related properties.


Feedback