This topic describes the EGL record that corresponds to
an Extensible Markup Language (XML) string. Other topics describe
the functions—serviceLib.convertFromXML and serviceLib.convertToXML—that
are used by a Rich UI developer to convert XML data to or from a variable,
as may be necessary to access a third-party REST service.
XML and EGL records
You can define an EGL
Record part that is the basis of a record (or array of records) 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 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.
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 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 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 can read the XML shortcut
(
<Sample color="green"/>), but can write only
the longer form:
Here is a third example XML string:
<Employee>
<EmpNo department="Sales">10</EmpNo>
<Name>Smith</Name>
</Employee>
Here as 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
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 part. The fields of that part are
restricted to the previously stated types or to another non-structured
Record part. A Record part referenced within a Record part can only
include 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 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 property @XMLElement (or @XMLRootElement),
property field nillable.
Record part properties
You can use the following
properties when you define a Record part:
- The complex property @XMLRootElement provides
naming and data-type details about the root XML element, which is
the topmost, most inclusive element in the XML string.
- The simple property XMLStructure identifies
the characteristics of a set of XML elements.
Details on those properties are in “@RootElement” and
“XMLStructure.”
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 complex property @XMLElement provides
details for a Record field that represents an XML element. By default,
that property is in effect.
- The complex property @XMLAttribute provides
details for a Record field that represents an XML attribute.
Details on those properties are in “@XMLElement” and “@XMLAttribute.”
Namespaces
Rich
UI supports reading and writing XML strings that contain namespaces.
You can reference a namespace in the property @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 websites
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:
To gain a full understanding of the alternatives available
to you in EGL, review the topics for the XML-related properties. Also
note the EGL Runtime issues an XMLProcessingException in
some cases, as stated in “Exception record for XML.”