Introduction to the XML element in Gosu

The XmlElement class represents an XML element and encapsulates the following components:

  • The element name as a qualified name, a QName
  • A backing type instance
  • The nillness of the element

Element qualified name

The element’s name is a String value that is a fully qualified name called a QName. A QName represents a more advanced definition of a name than a simple String value. To define a QName, use the javax.xml.namespace.QName class. A QName object contains the following components:

  • A String value that represents the local part, also called the localPart.
  • A String value that represents the namespace URI in which the local part of the name is defined. For example, a namespace can have the value http://www.w3.org/2001/XMLSchema-instance.
  • A suggested prefix name to use if Gosu serializes this element. This prefix is not guaranteed upon serialization because there might be conflicts.

For example, an XML file may contain an element name with the syntax of two parts separated by a colon, such as veh:childelement. The childelement part of the name is the local part. The prefix veh is a convenient shortcut representing the full URI of a namespace previously declared in the XML document, as shown in the following example: 

<?xml version="1.0"?>
<veh:root xmlns:veh="http://mycompany.com/schema/vehiclexsd">
  <veh:childelement/>
</veh:root>

This XML code specifies the following properties of the XML document:

  • The root element of the document has the name root within the namespace http://mycompany.com/schema/vehiclexsd.
  • The text xmlns:veh, followed by the URI, means that elements can use the prefix veh: to represent the longer URI (http://mycompany.com/schema/vehiclexsd).
  • The root element has one child element that has the name childelement and is within the namespace http://mycompany.com/schema/vehiclexsd.

There are three constructors for QName:

  • A constructor specifying the namespace URI, local part, and suggested prefix:
    QName(String namespaceURI, String localPart, String prefix)
  • A constructor specifying the namespace URI and local part:
    QName(String namespaceURI, String localPart)
  • A constructor specifying the local part only:
    QName(String localPart)

You can set the namespace in the QName object to the empty namespace, which is the constant javax.xml.XMLConstants.NULL_NS_URI. The recommended approach for creating QName objects in the empty namespace is to use the QName(String localPart) constructor.

To create multiple QName objects in the same namespace, you can use the optional utility class called XmlNamespace.

Whenever you construct an XmlElement, you must always specify a non-empty QName.

Other Gosu XML APIs use QName objects for other purposes. For example, attributes on an element are names defined within a namespace, even if it is the default namespace for the XML document or the empty namespace. Gosu natively represents both attribute names and element names as QName objects.

Backing type instance

Each element contains a reference to a Gosu type that represents this specific element. To get the backing type instance, use the element's TypeInstance property. For XML elements that Gosu created based on an XSD, Gosu sets this backing type information automatically so it can be used in a type-safe manner.

Whenever you construct an XmlElement, an explicit backing type is optional. If you are constructing the element from an XSD, Gosu automatically sets the backing type based on the XmlElement subclass.

You can use XmlElement as untyped nodes without providing an XSD for your data format. If you are not using an XSD and do not provide a backing type, Gosu uses the default backing type gw.xml.xsd.w3c.xmlschema.types.complex.AnyType. All valid backing types are subclasses of AnyType.

The backing type instance of an XML element is responsible for most of the element’s behavior but does not contain the element’s name. It is important to be aware of the functionality that a particular element's backing type instance supports, especially when using an XSD.

Nillness of an element

An XML element that has no child elements but has attributes is nil. Additionally, an XSD can define whether an element is nillable, meaning it is allowed to be nil.
Note: This state is not exactly the same as being null.

XMLElement constructor

The XmlElement consructor that accepts a String parameter is convenient, because it is equivalent to passing a new QName object with that String as a single argument to a QName constructor. In this case, the namespace and prefix in the QName are null.

The following code creates an in-memory Gosu object that represents an XML element <Root> in the empty namespace:

var el = new XmlElement( "Root" )

In this case, the el.TypeInstance property returns an instance of the default type gw.xsd.w3c.xmlschema.types.complex.AnyType. If you instantiate a type instance, Guidewire recommends that you use a more specific subclass of AnyType, specifying either an XSD-based type or a simple type.

See also