Correspondence between an XML string and an EGL variable

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

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.

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:

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

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

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.

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.
• The complex property @XMLArray provides details for a Record field that represents an array of XML elements.

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:

• 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/