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