Overview of XML and XSD support

Gosu provides support for Extensible Markup Language (XML). XML files describe complex structured data in a text-based format with strict syntax for data interchange. For more information on XML, refer to the World Wide Web Consortium web page http://www.w3.org/XML.

Gosu can parse XML by using an existing XML Schema Definition (XSD) file to produce a statically typed tree with structured data. Alternatively, Gosu can read or write to any XML document as a structured tree of untyped nodes. In both cases, Gosu code interacts with XML elements as native in-memory Gosu objects assembled into a graph, rather than as text data.

All the types from the XSD become native Gosu types, including element types and attributes. All these types appear naturally in the namespace defined by the part of the class hierarchy that you place the XSD. In other words, you put your XSDs side-by-side next to your Gosu classes and Gosu programs.

Suppose you put your XSD in the package directory for the package mycompany.mypackage and your XSD is called mySchema.xsd. Gosu lowercases the schema name because the naming convention for packages is lowercase. Gosu creates new types in the hierarchy:

mycompany.mypackage.myschema.*

For example, the following XSD file is called driver.xsd:

<xs:element name="DriverInfo">
  <xs:complexType>
    <xs:sequence>
      <xs:element ref="DriversLicense" minOccurs="0? maxOccurs="unbounded"/>
      <xs:element name="PurposeUse" type="String" minOccurs="0?/>
      <xs:element name="PermissionInd" type="String" minOccurs="0?/>
      <xs:element name="OperatorAtFaultInd" type="String" minOccurs="0?/>
    </xs:sequence>
    <xs:attribute name="id" type="xs:ID" use="optional"/>
  </xs:complexType>
</xs:element>
<xs:element name="DriversLicense">
  <xs:complexType>
    <xs:sequence>
      <xs:element name="DriversLicenseNumber" type="String"/>
      <xs:element name="StateProv" type="String" minOccurs="0?/>
      <xs:element name="CountryCd" type="String" minOccurs="0?/>
    </xs:sequence>
    <xs:attribute name="id" type="xs:ID" use="optional"/>
  </xs:complexType>
</xs:element>

The following Gosu code uses XSD-based types to manipulate XML objects:

uses xsd.driver.DriverInfo
uses xsd.driver.DriversLicense
uses java.util.ArrayList

function makeSampleDriver() : DriverInfo {
  var driver = new DriverInfo(){:PurposeUse = "Truck"}
  driver.DriversLicenses = new ArrayList<DriversLicense>()
  driver.DriversLicenses.add(new DriversLicense(){:CountryCd = "US", :StateProv = "AL"})
  return driver
}

The example to follow uses the XSD file, Credentials.xsd. In particular, the code relies upon the following portion of the XSD file:

<xs:complexType name= "CredentialsType">
  <xs:sequence>
    <xs:element name="username" type="xs:string" minOccurs="1" maxOccurs= "1"/>
    <xs:element name="password" type="xs:string" minOccurs= "1" maxOccurs= "1"/>
  </xs:sequence>
  <xs:attribute name="key" type="xs:string"/>
</xs:complexType>

<xs:element name="CredentialsElem" type="tns:CredentialsType"/>

<xs:complexType name="CredentialsArrayType">
  <xs:sequence>
    <xs:element ref="tns:CredentialsElem" minOccurs="1" maxOccurs="unbounded"/>
  </xs:sequence>
</xs:complexType>

<xs:element name="CredentialsArray" type="tns:CredentialsArrayType"/>

In this example, the following Gosu code creates a first element defined in the XSD file. This first element is of type CredentialsArray. Next, the code creates a second element defined in the same XSD file. This second element is of type CredentialsElem. The code then adds the second element as a child to the first element:

uses gw.xsd.credentials.*

var e = new CredentialsArray()

// Create a new child element that is legal in the XSD, and add it as a child
var c1 = new CredentialsElem()
c1.setUsername("Harry Truman")
c1.setPassword("password")
e.addChild(c1)