Skip to main content
Previous sectionNext section

XML-Enabled Objects Compared to XML Virtual Documents

When developing a production with XML messages, you can use either of the following structures to contain the XML document:

  • XML Virtual Documents

  • XML-enabled objects

If you need to access a small number of the elements in the input XML document, you can use XML Virtual Documents, but if you need to access most of the elements in the input XML document, you should choose XML-enabled objects because they are more efficient, especially when an object with many elements is processed by a transformation. The following business services and operations are provided to handle XML-enabled objects:

  • EnsLib.XML.Object.Service.FileService

  • EnsLib.XML.Object.Service.FTPService

  • EnsLib.XML.Object.Operation.FileOperation

  • EnsLib.XML.Object.Operation.FTPOperation

The XML-enabled object business services read a file containing an XML document and convert it to one or more objects. You specify a property that defines the XML element to convert to objects. If the XML root document contains a single element, then the service converts it to one object, but if the XML root document contains a series of these elements, then the service converts them to separate objects.

To use the XML-enabled object services, you do the following:

  1. Define a class that matches the structure of the input XML documents that you are processing. The class can either match the entire XML document or a repeating element within the root XML document. You can use the XML Schema Wizard to define this class. You can optionally define a NAMESPACE parameter for this class. This parameter specifies the XML namespace.

  2. Specify the classname in the business service Class Name field.

  3. Optionally, specify the element name in the Element Name field. If you specify this field, the service looks for one or more XML elements with this name within the root XML object. Each occurrence of this element is converted to an instance of the specified class. If you do not specify this field, the service matches the root document to the specified class.

  4. Optionally, specify the Format parameter and optionally select Ignore Null. The Format parameter can have a value of "literal", "encoded", or "encoded12". These parameters specify the corresponding parameters for the %XML.Adaptor class.

The XML-enabled object business operations convert an object to an XML document and write the document to a file. In addition to specifying information about the XML class and element, you can specify properties that are used when the operation invokes the %XML.Writer class.

Specify the following properties in the operations:

  • Root Element Name — If you specify this property, it is used as the root element name. If you omit this element, the operation uses the input element name.

  • Namespace — Specifies the XML namespace except if the class defines a NAMESPACE property. In that case, the operation always uses the XML namespace defined in the class.

  • Expected Class Name — Class name of the XML-enabled object. If the expected name does not match the actual name, the %XML.Writer adds an xsi:type attribute to the XML element.

  • Indentation Type — Specifies the corresponding property for %XML.Writer. Indentation Type specifies if indentation of the XML output should take place and what type of indentation.

  • Indentation Depth — Specifies the corresponding property for %XML.Writer. Indentation Depth specifies the number of indentation characters to be used for indentation. The default for "tab" is 1. The default for "space" is 4.

  • Charset — Specifies the corresponding property for %XML.Writer. Charset is the charset to use for encoding the XML output. The default depends upon the output destination. "UTF-8" is the default for output to files and binary streams. On a Unicode system, "UTF-16 is the default for output to character streams and strings. On an 8-bit system, the default charset for the locale is the default charset for output to character streams and strings

  • No XML Declaration — Specifies the corresponding property for %XML.Writer. If No XML Declaration is 1 (true), the %XML.Writer does not write the XML declaration. The default is for the %XML.Writer to write the XML declaration unless Charset is not specified and the output is directed to a string or character stream in which case it does not write an XML declaration.

  • Runtime Ignore Null — Specifies the corresponding property for %XML.Writer.

  • Element Qualified — Specifies the corresponding property for %XML.Writer.

  • Attribute Qualified — Specifies the corresponding property for %XML.Writer.

  • Default Namespace — Specifies the corresponding property for %XML.Writer.

  • Suppress xmlns — Specifies the corresponding property for %XML.Writer.

  • Format — Specifies the corresponding property for %XML.Writer.

  • References inline — Specifies the corresponding property for %XML.Writer.