XMLValue annotation

XMLValue identifies the potential structure of the XML elements that are represented by fields in a Record type.

EGL package name

eglx.xml.binding.annotation

Example use
See "Annotation fields" later.
Annotation detail
Record XMLValue type Annotation
{
   targets = [
      ElementKind.libraryPart,
      ElementKind.programPart,
      ElementKind.handlerPart,
      ElementKind.recordPart,
      ElementKind.servicePart,
      ElementKind.interfacePart
   ]
}
   kind XMLStructureKind = XMLStructureKind.simpleContent;
end
Annotation fields
kind

The explanations that follow describe what happens when you transfer record data to an XML string. However, the relationships also apply in the opposite direction, when the EGL Runtime validates the transfer of an XML string to an input record.

Here are the supported values:
XMLStructureKind.sequence (the default)
On output, the XML string must include every field in the Record type, in the order in which the Record fields are listed. The following Record type and XML string are related:
Record Employee {XMLValue = XMLStructureKind.sequence}
   EmpNo INT;
   LastName STRING;
end

<Employee>
   <EmpNo>10</EmpNo>
   <LastName>Smith</LastName> 
</Employee>
XMLStructureKind.choice
On output, the XML string must include one and only one subordinate element that corresponds to a record field. For example, consider the following Record type:
Record Employee{XMLStructure = XMLStructureKind.choice}
   ImmigrationStatus STRING?; 
   YearsOfCitizenship INT?;
end
Either of the following XML strings is valid:
<Employee>
   <ImmigrationStatus>A1</ImmigrationStatus>
</Employee>
<Employee>
   <YearsOfCitizenship>20</YearsOfCitizenship>
</Employee>

In this case, the XML string cannot include both kinds of elements.

If a record has the XMLStructure value "choice", each field must be nullable, as is indicated by the question marks in our example. Furthermore, the value of one field must be nonnull, and the value of only one field can be nonnull. The function XMLLib.convertToXML issues a RuntimeException if all fields in the input record are null or if more than one field is nonnull.

XMLStructureKind.simpleContent
On output, the simple content transferred to an XML string is the value of a field declared in a superior Record type, along with a set of attributes. For example, the following boldface Record type and XML content are related:
Record Employee{XMLValue = XMLStructureKind.sequence}
   EmpNo EmpNumber;
   LastName STRING;
end

Record EmpNumber {XMLValue = XMLStructureKind.simpleContent}
  	type STRING {@XMLAttribute{}};
  	value INT; // any field name is acceptable here
end

<Employee>
   <EmpNo type="Sales">10</EmpNo>
   <LastName>Smith</LastName> 
</Employee>

The subordinate record (here, EmpNumber) may include zero to many fields that are of type STRING and that have the XMLAttribute annotation. The annotation indicates that a given field represents an attribute. The same subordinate record might have a field that lacks the property XMLAttribute; and that non-attribute field, if any, holds the value of the related element. The non-attribute field can have any name.

XMLStructureKind.unordered
The XML string includes the specified elements in any order. The following Record type describes either of the subsequent XML strings:
Record Employee {XMLValue = XMLStructureKind.unordered}
   EmpNo INT;
   LastName STRING;
end

<Employee>
   <LastName>Jones</LastName> 
   <EmpNo>20</EmpNo>
</Employee>

<Employee>
   <EmpNo>20</EmpNo>
   <LastName>Jones</LastName> 
</Employee>
Comments
Compatibility

Table 1. Compatibility
Target Issue
Java No issues.
JavaScript No issues.