JBind 1.2

1.1 Consistency

When writing applications that process XML data a common problem is to ensure consistency between the XML data and the code that processes the data. Validating XML parsers play an important role here because they can check that XML data is valid according to its schema. Yet, they can not guarantee that the code that does the further processing is prepared to process that kind of data.

This is where data binding comes in. Data binding takes as its input a schema and generates code that reflects the schema. In other words, data binding is a means to transport the information contained in a schema into programming languages. Thereby consistency between a schema and its processing code is guaranteed.

In general, the more complicated the XML data is the more difficult is to ensure the consistency. JBind supports nearly 100% of the XML schema recommendation. Therefore it can be used in situations with rather complex XML data.

1.2 Adding Behaviour to Data

XML schema is a great possibility to describe the data aspect of an application. Yet, that data has no behaviour (or semantic/meaning). One possibility to add behaviour is to add it from "outside" by having code that interprets the data. Data binding allows another possibility namely to add behaviour directly to the data. This is done by augmenting the generated code with methods.

Having data and its behaviour together the result is nothing else than objects in terms of object oriented programming. At this point it is of great advantage that XML schema is object oriented with respect to two central features: inheritance and polymorphism. This allows a natural mapping of XML schemas into object oriented code.

JBind introduces the concept of XML code that allows the seamless integration of manually implemented behavioural code with generated code that reflects the data aspect (cf. 6 XML Code). Having XML data augmented with behaviour lots of possibilities open for developers.

1.3 XML Meta Data

This topic is closely related to the first two mentioned topics namely "Consistency" and "Adding Behaviour to Data" but adds another twist. Several reasons cause the usage of XML meta data in applications:

1. Information that is explicitly available in form of XML meta data can easily be used by different parts of an application. Thereby meta data can help to guarantee the consistency between different parts of an application. (Think of a web application where some HTML input fields must match the fields in a relational database.)

2. Information that is available explicitly in form of meta data is less error-prone than the same information contained implicitly in (lots of) source code. If meta data is stored in XML documents then it can be validated using a parser.

3. Meta data makes applications configurable thereby allowing non-programmers to modify the application. If the configuration data also contains behaviour then the applications are also easily extensible.

Conventional applications that use meta data are often more complicated at first sight than corresponding hardwired applications because the use of meta data comes with additional complexities. JBind eases the use of meta data essentially. The ability of JBind to generate methods that access referenced data (reflecting attributes of type IDREF and IDREFS or keyref constraints) allows to adequately handle not only meta data that has a simple hierarchical structure but also meta data that has an arbitrary structure. There is no more reason to hardwire specific data and behaviour in applications.

1.4 Domain Specific Languages and Application Frameworks

In case that not only a single application is to be developed but a whole family of applications the use of a domain specific language bears lots of advantages. XML schema can be used to describe the syntax of a domain specific language and JBind can be used to define its (operational) semantic by adding behaviour code.

The extensibility mechanisms of XML schema allows to carry on this idea to full fledged application frameworks. An application framework can be defined by an XML schema with the types having default behaviour. An instance document of the framework schema corresponds to an (executable) application. The framework schema can easily be extended by deriving new customized types from the framework types and using them in framework instance documents.

1.5 Processing

At the time being most people familiar with XML techniques agree that XML is the ideal way to exchange data between applications whereas the use of XML inside applications is not that clear. Using generic data structures like [DOM] is awkward. Therefore applications often internally use data structures that are better suited for their processing needs but have to be converted into XML when they are to be exchanged.

JBind allows to have data structures that are well suited for internal processing and that are in an XML form at the same time. Another benefit of having the internal data in an XML form is the ease of using powerful XML techniques like XPath/XSLT not only for exchange (and rendering) but also for internal processing (cf. 5.2.3 XPath Methods and 6.3 Maze Game for an XSLT example).

1.6 A Word of Care - Relating JBind to other Data Binding Frameworks

The main focus of JBind is to ease the intergration of manually written code with generated code and to support nearly all of the XML schema specification. Performance is not a primary design goal of JBind.

Java-XML data binding links the Java world with the XML world. Most data binding frameworks have a major focus on the Java part of the story whereas the XML part is often a compromise with respect to complexity, usability, and performance. JBind clearly has its focus on the XML part which caused some compromises at the Java side.

Yet, JBind allows to plug-in so called cartridges that are responsible for code generation. The cartridges are provided with easily usable information about the schemas to be processed. Developers interested in developing/contributing new cartridges may contact the author.

3.1 Generated Sources

Given an XML schema four kinds of sources are generated:

The graphic contains the UML diagram of an example that shows the relationship between the four kinds of generated sources. The schema of this example is presented in section 3.4 Example Schema. The names of interfaces have the prefix "I" and the names of data classes/interfaces have the suffix "Data". The graphic demonstrates that the behaviour class/interface of a type can be missing. In this case the inheritance hierarchy uses the next available class/interface that follows in the hierarchy. An abstract type is also contained in the example for which no data class is generated.

The design goal of the inheritance hierarchy was to have a separation between the always generated parts that reflect the data aspect of a type and the manually implemented parts that add behaviour. (The methods declared in data interfaces are already available for usage in the derived behaviour classes.)

3.2 Invoking the Schema Compiler

The schema compiler is invoked by the command line:

java org.jbind.xml.schema.compiler.Compiler -schemaUrl <url> [-validateOnly]
  [-package <package>] [-destinationDir <dir>] [-dataDir <dir>] [-behaviourDir <dir>]

• schemaUrl: A url to an XML schema.

• validateOnly: If specified then the schema and code generation is validated only. No code is output.

• package: The Java package that contains the generated classes/interfaces.

• destinationDir: Used for data and behaviour classes/interfaces if no more specific directory is specified.

• dataDir: Used as destination directory for data classes/interfaces.

• behaviourDir: Used as destination directory for behaviour classes/interfaces

• url: A url to an XML schema.

• file: A file containing an XML schema.

• package: The Java package that contains the generated classes/interfaces.

• destinationDir: Used for data and behaviour classes/interfaces if no more specific directory is specified.

• dataDir: Used as destination directory for data classes/interfaces.

• behaviourDir: Used as destination directory for behaviour classes/interfaces

• derivePackages: Boolean attribute that is only relevant if file sets are used. The default is false. If this attribute is false then the schemas selected by file sets get the package specified by the package attribute. If this attribute is true then the package of a schema contained in a file set is derived from its relative location in the file set. In other words, the subdirectory hierarchy of a file set is translated into a corresponding package hierarchy.

<taskdef name="jbind" classname="org.jbind.xml.ant.CompileTask" classpathref="jBind"/>

<target name="xml98Schema" depends="taskDef">
  <jbind url="http://www.w3.org/2001/xml.xsd" destinationDir="${genSrcDir}"/>
</target>
          
<target name="generateExamples" depends="taskDef">
  <jbind  dataDir="${genExamplesSrcDir}" behaviourDir="${examplesDir}" derivePackage="true">
    <fileset dir="${examplesDir}" includes="**/*.xsd"/>
  </jbind>
</target>

3.3 Parameterizing the Code Generation

Code generation is mainly parameterized by attributes that appear inside schema documents. XML schema allows the appearance of arbitrary attributes at nearly all tags as long as they do not belong to the http://www.w3.org/2001/XMLSchema namespace. This feature is used in JBind to add binding information to schemas. [Definition: Let the JBind namespace be "http://www.jbind.org"]. [Definition: A binding attribute is an attribute that belongs to the JBind namespace.] All binding attributes are declared in the JBind schema jBind.xsd.

It is possible to have a schema and its binding information in separate documents. This approach is explained in section 3.5 Schema Adjunct Documents. However, this approach consists of generating a new schema based on an original schema by augmenting it with binding information. The result is a schema that contains the binding attributes that are described in this section.

[Definition: Some binding attributes have an effect only on the tag at which they appear. They are called local binding attributes.] [Definition: Other binding attributes are propagated along nested tags. They are called propagating binding attributes.] In general, local binding attributes are only allowed on dedicated tags for which they bear binding information whereas propagating binding attributes may appear on any tag. Finally there are [Definition: defaulted binding attributes that take their default value from the schema element they are nested in. If a schema is included by another schema then the including schema is also considered.]

The situation is slightly more complicated for attribute and element declarations that are references to other declarations. In this case if a binding attribute is accessed then first the binding attributes of the declaration itself are considered and then - only if no matching attribute was found - the binding attributes of the referenced declaration.

[Definition: All classes/interfaces that are generated for a schema are placed into a common package that is called the schema package]. The schema package can be specified by

1. an argument on the command line,

2. a local binding attribute on the schema tag, or

3. a mapping of namespaces to package names in the JBind configuraiton (cf. 7.6 Namespace to Package Mapping).

If the name of a type contains one or more dots then the name is split into two parts: 1. A prefix reaching until the last dot and 2. a suffix starting after the last dot. The prefix is used to denote a subpackage inside the schema package whereas the suffix is used for the names of the generated classes/interfaces inside their package.

3.4 Example Schema

The following example schema shows the usage of various binding attributes. Looking at the UML diagram presented previously shows that no data class is generated for the MeansOfTransport type and that no behaviour class and no behaviour interface for the Automobile type. This is caused by the fact that the MeansOfTransport type is defined to by abstract and that the Automobile type is defined to have no behaviour.

The attribute manufacturer of the Vehicle type is of type IDREF. This causes the schema compiler to generate the method "IManufacturerData getManufacturer()" to access the referenced manufacturer.

<?xml version="1.0" encoding="UTF-8"?>
<schema
  elementFormDefault="qualified"
  targetNamespace="meansOfTransport"
  xmlns="http://www.w3.org/2001/XMLSchema"
  xmlns:jb="http://www.jbind.org"
  xmlns:t="meansOfTransport"
  jb:package="meansOfTransport"
	jb:elementSubPackage=""
  jb:hasBehaviour="true" jb:setter="normal" jb:checker="normal"
  jb:factoryType="Factory">

  <complexType name="MeansOfTransport" abstract="true">
    <annotation>
      <documentation xml:lang="x-javadoc"><![CDATA[
        Base class for all kinds of <i>means of transport</i>.
      ]]></documentation>
    </annotation>
  </complexType>

  <complexType name="Vehicle">
    <complexContent>
      <extension base="t:MeansOfTransport">
        <attribute name="numberOfWheels" type="int"
          jb:setter="hook" jb:remover="normal">
          <annotation>
            <documentation xml:lang="x-javadoc">
              This attribute is set by a hook method that is manually implemented
              in the {@link Vehicle} class.
            </documentation>
          </annotation>
        </attribute>
        <attribute name="manufacturer" type="IDREF" jb:referencedType="t:Manufacturer"/>
      </extension>
    </complexContent>
  </complexType>

  <complexType name="Automobile" jb:hasBehaviour="false">
    <complexContent>
      <extension base="t:Vehicle">
        <attribute name="fuelType" type="string" use="required" jb:checker="none"/>
        <attribute name="consumptionInLitres" type="decimal" jb:name="consumption"/>
        <sequence>
          <element ref="t:engine"/>
        </sequence>
      </extension>
    </complexContent>
  </complexType>

  <complexType name="Truck">
    <complexContent>
      <extension base="t:Automobile">
        <attribute name="loadCapacityInTons" type="decimal"/>
      </extension>
    </complexContent>
  </complexType>

  <element name="meansOfTransport" type="t:MeansOfTransport" abstract="true"/>
  <element name="vehicle" type="t:Vehicle" substitutionGroup="t:meansOfTransport"/>
  <element name="automobile" type="t:Automobile" substitutionGroup="t:vehicle"/>
  <element name="truck" type="t:Truck" substitutionGroup="t:automobile"/>
	
  <element name="engine"/>
	
  <complexType name="Manufacturer" jb:hasBehaviour="false">
    <attribute name="id" type="ID"/>
  </complexType>

	<element name="manufacturer" type="t:Manufacturer"/>

  <element name="manufacturers">
    <complexType>
      <sequence maxOccurs="unbounded">
        <element name="manufacturer" type="t:Manufacturer"/>
      </sequence>
    </complexType>
  </element>
	
  <element name="meansOfTransports">
		<complexType>
			<sequence maxOccurs="unbounded">
				<element ref="t:meansOfTransport"/>
			</sequence>
		</complexType>
	</element>
  
  <!--
    Factory type that has creation methods for vehicles, automobiles, trucks, and manufacturers.
		The content model of a factory may contain only references to top-level element declarations.
  -->
  <complexType name="Factory" jb:hasBehaviour="false" jb:getter="none" jb:creator="normal">
    <sequence>
      <element ref="t:vehicle"/>
      <element ref="t:automobile"/>
      <element ref="t:truck"/>
      <element ref="t:manufacturer"/>
    </sequence>
  </complexType>

</schema>

See the sources and the JavaDoc. The vehicle class is inserted here for convenience to show an example of a hook method:

package org.jbind.example.meansOfTransport;

import org.jbind.xml.msg.XmlException;

public abstract class Vehicle extends MeansOfTransport implements IVehicle {
  /**
   * Implementation of the setter using the hook method.
   */
  public void setNumberOfWheels(int anInt) throws XmlException {
    doSetNumberOfWheels(anInt);
  }
  /**
   * Declaration of the hook method. The hook method is implemented by the
   * generated data class.
   */
  protected abstract void doSetNumberOfWheels(int anInt) throws XmlException;
}

3.5 Schema Adjunct Documents

Section 3.3 Parameterizing the Code Generation showed how binding attributes are included in schema documents to parameterize the code generation. This approach works fine if the schema to be bound can be modified to fit the needs of JBind. If a schema can not be modified or the schema is to be shared by several parties with some of them not using JBind then another approach is needed that leaves schema documents untouched.

[Definition: Schema adjunct documents are used by JBind to store binding information for schema documents in separate documents.] This has the advantage that schema documents have not to be touched and that binding information is not scattered all over schema documents. Schema adjunct documents are governed by the jBind-schema-adjunct.xsd schema from which a part is repeated here for convenience:

<complexType name="Adjunct">
  <choice minOccurs="0" maxOccurs="unbounded">
    <any namespace="http://www.jbind.org" processContents="strict"/>
    <element name="adjunct" type="t:Adjunct"/>
  </choice>
  <attribute name="select" use="required">
    <simpleType>
      <restriction base="string">
        <pattern value="[^/].*"/>
      </restriction>
    </simpleType>
  </attribute>
  <attribute name="checkForEmptySelection" type="boolean" default="true"/>
  <anyAttribute namespace="http://www.jbind.org" processContents="strict"/>
</complexType>

<element name="adjuncts">
  <complexType>
    <sequence>
      <element name="adjunct" type="t:Adjunct" minOccurs="0" maxOccurs="unbounded"/>
    </sequence>
  </complexType>
</element>

A schema adjunct document contains arbitrarily nested adjunct elements. Each adjunct element has a required select attribute that holds a relative XPath to select parts of a schema document. The XPaths of top-level adjunct elements are evaluated relative to the document root of a schema document whereas the XPaths of nested adjunct elements are evaluated relative to the selected parts of their parent adjunct elements. The optional checkForEmptySelection attribute controls if an adjunct element with an empty selection is reported. This attribute is useful to detect errors in adjunct documents.

An adjunct element can bear arbitrary binding attributes. and can contain arbitrary extension elements. These are copied into the parts of a schema document that are selected by the corresponding adjunct element. Binding attributes are directly copied whereas extension elements are copied into an annotation/appinfo element. If a selected part has already an annotation element then an additional appinfo element containing the extension elements is appended to the content of the annotation element.

The current implementation for processing schema adjunct documents consists of generating new schema documents. [Definition: A bound schema is the result of applying binding information contained in a schema adjunct document to a schema document.] A bound schema can be registered in the JBind configuration to be used whenever its original schema is addressed (cf. 7.7 Entity Resolver, Import, and Include).

The process of applying binding information contained in schema adjunct documents to schema documents is implemented by a 2 step stylesheet transformation. In the first step, a schema adjunct document is transformed into a stylesheet called the adjunct stylesheet that contains all binding information and knows how to process schema documents accordingly. In the second step, the adjuct stylesheet is applied to a schema document. In principle, a schema adjunct document can contain binding information for several schemas and a schema may be bound by applying several schema adjunct documents sequentially.

This process is illustrated in the next figure. The schema adjunct document adjunct.xml is transformed into the adjunct stylesheet adjunct.xsl by the transformAdjunct.xsl stylesheet. Then the adjunct stylesheet is used to transform the schema document schema.xsd into its bound version bound-schema.xsd.

4.1 Datatype Hierarchy

The datatype hierarchy of XML schema is defined in chapter built-in datatypes in the XML schema specification. A graphic from that chapter is inserted here for convenience.

Datatypes are represented internally by instances of generic type classes. These classes are instantiated either in static setup code (for the built-in types) or when a schema is read in. The corresponding interfaces can be found in the package org.jbind.xml.core.type.

[Definition: Data types that are derived from anySimpleType have a simple storage type. This is the type used to store values of the corresponding type. Simple storage types are either primitive types (like int or double) or they are (simple) reference types (like String or BigDecimal).] Types that are not derived from a simple type, i.e. complex types with a complex content model have no simple storage type. Complex types with a simple content model have the same simple storage type as their content type.

4.2 Data Storage

[Definition: Classes/interfaces that are responsible for the storage of values are called storage classes/interfaces]. [Definition: Corresponding to the datatype hierarchy there is a hierarchy of these classes/interfaces that is called the storage hierarchy]. The framework contains interfaces for all built-in storage classes that can be found in the package org.jbind.xml.core.data.

The data classes/interfaces that are generated by the schema compiler are derived from storage classes/interfaces. In other words, each generated class/interface has an ancestor amongst the classes/interfaces of the package org.jbind.xml.core.data. This also true for data classes/interfaces of complex types. If a complex type has complex content then it is derived from anyType. If the type has simple content then its storage class/interface is derived from the storage class/interface of its simple content type.

[Definition: Each storage class whose type is derived from anySimpleType has a simple storage value. A simple storage value is for example an int or a String.] The simple storage values can be accessed by getter and setter methods of the storage classes. For example the interface of the int storage class is:

/*
 * JBind
 *
 * Copyright (c) by Stefan Wachter. All rights reserved.
 *
 * Usage, modification, and redistribution is subject to license terms that are
 * available at 'http://www.jbind.org'. The JBind license is like the
 * 'Apache Software License V 1.1'.
 */
package org.jbind.xml.core.data;

import org.jbind.xml.msg.XmlException;

public interface IIntData extends ILongData {
  int getInt();

  void setInt(int aValue) throws XmlException;
}

The storage classes can be called wrapper classes for the simple storage values. The reason for introducing wrapper classes is that the datatype hierarchy should be reflected by the storage hierarchy.

4.3 Implementation

The implementation of the storage hierarchy is based on the Bridge Pattern (cf. [GOF]). This pattern consists of an abstraction that uses an implementation. In case of JBind the data classes are the abstraction that is backed by default by a simple nested HashMap structure that plays the role of the implementation. [Definition: The implementation is called the data implementation]. It can be configured by specifying the data implementation factory. (cf. 7.5 Data Implementation Factory).

The data implementation of a data class is accessed using its getImpl_() method. It may be useful to access the underlying data implementation directly for example in order to apply a stylesheet.

4.4 Manipulating XML Data

XML data should be manipulated by using the generated accessor methods. In principle, it is also possible to manipulate the underliying data implementation directly but the current version of JBind is not thoroughly tested for this kind of use. In addition, nearly no constraints are checked when manipulating the data implementation directly.

package org.jbind.example.meansOfTransport;

import java.math.BigDecimal;
import java.net.URL;
import org.jbind.xml.core.cmp.ISchema;
import org.jbind.xml.facade.JBindFacade;
import org.jbind.xml.msg.XmlException;

/**
 * Example showing the usage of the schema factory.
 */
public class TruckCreation {
  public static void main(String[] args) {
    URL url = TruckCreation.class.getResource("meansOfTransport.xsd");
    try {
      ISchema schema = JBindFacade.readSchema(url);
      IFactoryData factory = (IFactoryData)schema.getFactory();
      ITruck truck = factory.createTruck();
      truck.setNumberOfWheels(7);
      truck.setFuelType("water");
      truck.setConsumption(12.0);
      truck.setLoadCapacityInTons(new BigDecimal("30"));
    } catch (XmlException e) {
      e.printStackTrace();
    }
  }
}

5.1 Missing Features

The ENTITY and ENTITIES types are supported only syntactically, i.e. it is only checked that data of type ENTITY or ENTITIES is a valid NCName or a list of valid NCNames, respectively. It is not checked that the NCNames match unparsed entity declarations.

5.2 Extensions

The XML schema specification allows arbitrary elements to appear inside appinfo elements. This mechanisms is used by JBind for extending the expressiveness of schemas and to provide additional information for code generation. [Definition: An extension element is an element in the JBind namespace that appears inside an appinfo element]. The following schema shows the various extension elements of JBind. They are explained in the next sections.

<?xml version="1.0" encoding="UTF-8"?>
<schema
  xmlns="http://www.w3.org/2001/XMLSchema"
  elementFormDefault="qualified"
  xmlns:jb="http://www.jbind.org"
  targetNamespace="helloWorld"
  xmlns:t="helloWorld"
  jb:package="helloWorld">

  <complexType name="Country">
    <annotation>
      <appinfo>
        <jb:key name="cityIndex">
          <selector xpath="t:city"/>
          <field xpath="../@countryId"/>
          <field xpath="@cityId"/>
        </jb:key>
        <jb:xPathMethod name="countrySummary" 
          xpath="concat('country ', @countryName, ' has ', count(t:city), ' cities.')"
          type="string"/>
      </appinfo>
    </annotation>
    <sequence maxOccurs="unbounded">
      <element name="city" type="t:City"/>
    </sequence>
    <attribute name="countryId" type="NMTOKEN" use="required"/>
    <attribute name="countryName" type="string" use="required"/>
    <attribute name="area" type="nonNegativeInteger"/>
  </complexType>

  <complexType name="City">
    <attribute name="cityId" type="NMTOKEN" use="required"/>
    <attribute name="cityName" type="string" use="required"/>
  </complexType>

  <complexType name="Person" jb:hasBehaviour="true">
    <annotation>
      <documentation xml:lang="x-javadoc">
        A person has the method &quot;sayHello&quot;.
      </documentation>
      <appinfo>
        <jb:keyref name="city" refer="t:cityIndex" jb:referencedType="t:City">
          <selector xpath="."/>
          <field xpath="@countryId"/>
          <field xpath="@cityId"/>
        </jb:keyref>
        <jb:xPathConstraint 
          test="(@extraterrestrial='true' and not(@countryId) and not(@cityId)) or (@countryId and @cityId)"/>
      </appinfo>
    </annotation>
    <attribute name="personName" type="string" use="required"/>
    <attribute name="countryId" type="NMTOKEN"/>
    <attribute name="cityId" type="NMTOKEN"/>
    <attribute name="extraterrestrial" type="boolean" default="false"/>
  </complexType>

  <complexType name="World" jb:hasBehaviour="true">
    <annotation>
      <appinfo>
        <!-- Counts all countries. -->
        <jb:xPathMethod name="countries" xpath="count(.//t:country)" type="number"/>
        <!-- Selects all countries. -->
        <jb:xPathMethod name="allCountries" xpath=".//t:country" type="select"/>
        <!-- Counts all persons. -->
        <jb:xPathMethod name="persons" xpath="count(.//t:person)" type="number"/>
        <!-- Selects all persons. -->
        <jb:xPathMethod name="allPersons" xpath=".//t:person" type="select"/>
        <!-- Sums the area of all countries. -->
        <jb:xPathMethod name="totalArea" xpath="sum(.//t:country/@area)" type="number"/>
      </appinfo>
    </annotation>
    <choice maxOccurs="unbounded">
      <element name="country" type="t:Country"/>
      <element name="person" type="t:Person"/>
    </choice>
    <attribute name="nbSetupAndTearDownLevels" type="int" use="required"/>
  </complexType>

  <element name="world" type="t:World"/>

</schema>

<complexType name="Country">
  ...
  <jb:key name="cityIndex">
    <selector xpath="t:city"/>
    <field xpath="ancestor::*[@countryId]/@countryId"/>
    <field xpath="@cityId"/>
  </jb:key>
  ...
</complexType>

<complexType name="Person" jb:hasBehaviour="true">
  ...
  <jb:xPathConstraint select="."
    test="(@extraterrestrial and not(@countryId) and not(@cityId)) or (@countryId and @cityId)"/>
  ...
</complexType>       

<?xml version="1.0" encoding="UTF-8"?>
<schema elementFormDefault="qualified" targetNamespace="xPathMethods"
  xmlns="http://www.w3.org/2001/XMLSchema" xmlns:jb="http://www.jbind.org"
  xmlns:t="xPathMethods">
  <element name="element">
    <complexType>
      <annotation>
        <appinfo>
          <jb:xPathMethod name="allElements" xpath=".//t:element" type="select"/>
          <jb:xPathMethod name="totalSum" xpath="sum(.//t:element/@number)" type="number"/>
          <jb:xPathMethod name="overview" 
            xpath="concat('There are ', count(.//t:element[@selected]), ' selected elements.')"
            type="string"/>
          <jb:xPathMethod name="totalAndSelectedSum"
            xpath="sum(.//t:element/@number) &gt; 2 * sum(.//t:element[@selected]/@number)"
            type="test"/>
          <jb:xPathMethod name="maximum"
            xpath=".//t:element[@number and not(@number &lt; //t:element/@number)]"
            type="fetch"/>
        </appinfo>
      </annotation>
      <sequence>
        <element ref="t:element" minOccurs="0" maxOccurs="unbounded"/>
      </sequence>
      <attribute name="number" type="decimal"/>
      <attribute name="selected" type="boolean"/>
    </complexType>
  </element>
</schema>

<?xml version="1.0" encoding="UTF-8" ?>
<element xmlns="xPathMethods">
  <element number="5"/>
  <element number="13"/>
  <element selected="true">
    <element selected="true" number="10"/>
  </element>
</element>

Iterator i = data.selectAllElements();
i.next(); i.next(); i.next(); i.next(); i.next();
assertTrue("1", !i.hasNext());
double d = data.numberTotalSum();
assertTrue("2: " + d, 28 == d);
String s = data.stringOverview();
assertTrue("3: " + s, "There are 2 selected elements.".equals(s));
assertTrue("4:", data.testTotalAndSelectedSum());
xPathMethods.element.IElementData max =
(xPathMethods.element.IElementData)data.fetchMaximum();
assertTrue("5: ", new BigDecimal("13").equals(max.getNumber()));

<?xml version="1.0" encoding="UTF-8" ?>
<manufacturers
  xmlns:xsi=
    "http://www.w3.org/2001/XMLSchema-instance"
  xmlns="meansOfTransport"
  xsi:schemaLocation=
    "meansOfTransport meansOfTransport.xsd">
  <manufacturer id="manuId1"
    name="Daymler-Chrysler"/>
  <manufacturer id="manuId2" name="Volvo"/>
</manufacturers>

<?xml version="1.0" encoding="UTF-8" ?>
<meansOfTransports
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns="meansOfTransport"
  xsi:schemaLocation="meansOfTransport meansOfTransport.xsd">
  <truck manufacturer="manuId1" numberOfWheels="8"
    fuelType="benzin" consumptionInLitres="25.0"
    loadCapacityInTons="30.0">
    <engine/>
  </truck>
  <vehicle xsi:type="Truck" manufacturer="manuId2"
    numberOfWheels="4" fuelType="super"
    consumptionInLitres="5.0" loadCapacityInTons="5.0">
    <engine/>
  </vehicle>
</meansOfTransports>

package org.jbind.example.meansOfTransport;

import org.jbind.xml.core.data.IDataContext;
import org.jbind.xml.instance.builder.DataContext;
import org.jbind.xml.facade.JBindFacade;
import org.jbind.xml.msg.XmlException;
import java.util.Iterator;

public class Main {
  public static void main(String[] args) {
    // Create a shared data context
    IDataContext context = new DataContext(true);
    try {
      // Read manufacturers
      JBindFacade.unmarshal(Main.class.getResource("manufacturers.xml"), context);
      // Read means of transports
      IMeansOfTransportsData data = (IMeansOfTransportsData)
      JBindFacade.unmarshal(Main.class.getResource("meansOfTransports.xml"), context);
      for (Iterator i = data.iterMeansOfTransports(); i.hasNext(); ) {
        IMeansOfTransport mot = (IMeansOfTransport)i.next();
        IManufacturerData man = mot.refManufacturer();
        System.out.println("MeansOfTransport was manufactured by: " + man.getName());
      }
    } catch (XmlException e) {
      e.printStackTrace();
      System.exit(-1);
    }
    System.exit(0);
  }
}

6.1 "Hello World!"

The schema presented in section 5.2 Extensions is used as a base for an XML application. This is done be implementing the IApplication and the ISetupAndTearDown interfaces in the World and Person. behaviour classes, respectively. Note that the getNbSetupAndTearDownLevels method is realized by having a corresponding attribute in the World type. The two classes, an application instance document, and the output of the application are shown below.

package org.jbind.example.helloWorld;

import org.jbind.xml.msg.XmlException;
import java.util.Iterator;

public abstract class World
  extends org.jbind.xml.instance.data.AnyTypeData
  implements IWorld {
  public int execute() {
    try {
      System.out.println("countries: " +
        numberCountries());
      System.out.println("total area: " +
        numberTotalArea());
      for (Iterator i = selectAllCountries();
        i.hasNext(); ) {
        ICountryData c = (ICountryData)i.next();
        System.out.println(c.stringCountrySummary());
      }
      for (Iterator i = selectAllPersons();
        i.hasNext(); ) {
        IPerson p = (IPerson)i.next();
        System.out.println(p.sayHello());
      }
    } catch (XmlException e) {
      e.printStackTrace();
      return -1;
    }
    return 0;
  }
}

package org.jbind.example.helloWorld;

public abstract class Person
extends org.jbind.xml.instance.data.AnyTypeData
implements IPerson {
  public String sayHello() {
    ICityData c = refCity();
    return "Hello World! I am " +
    getPersonName() + " from " + c.getCityName() + ".";
  }
  public void setup(int aLevel) {
    System.out.println("setup (" + aLevel + "): "
    + getPersonName());
  }
  public void tearDown(int aLevel) {
    System.out.println("tear down (" + aLevel + "): " 
    + getPersonName());
  }
}

<?xml version="1.0" encoding="UTF-8" ?>
<world xmlns="helloWorld"
  nbSetupAndTearDownLevels="2"
  xsi:schemaLocation="helloWorld hello.xsd"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <country countryName="Germany"
    countryId="GER" area="357046">
    <city cityName="Berlin" cityId="BER"/>
    <city cityName="Karlsruhe" cityId="KA"/>
  </country>
  <country countryName="United States of America"
    countryId="USA" area="3717796">
    <city cityName="Washington DC" cityId="WAS"/>
  </country>
  <country countryName="United Kingdom"
    countryId="UK" area="244101">
    <city cityName="London" cityId="LON"/>
  </country>
  <country countryName="France"
    countryId="FR" area="543965">
    <city cityName="Paris" cityId="PAR"/>
  </country>
  <person personName="Gerhard Schröder"
    cityId="BER" countryId="GER"/>
  <person personName="George W. Bush"
    cityId="WAS" countryId="USA"/>
  <person personName="Tony Blair"
    cityId="LON" countryId="UK"/>
  <person personName="Jacques Chirac"
    cityId="PAR" countryId="FR"/>
</world>

setup (0): Gerhard Schröder
setup (0): George W. Bush
setup (0): Tony Blair
setup (0): Jacques Chirac
setup (1): Gerhard Schröder
setup (1): George W. Bush
setup (1): Tony Blair
setup (1): Jacques Chirac
countries: 4.0
total area: 4862908.0
country Germany has 2 cities.
country United States of America has 1 cities.
country United Kingdom has 1 cities.
country France has 1 cities.
Hello World! I am Gerhard Schröder from Berlin.
Hello World! I am George W. Bush from Washington DC.
Hello World! I am Tony Blair from London.
Hello World! I am Jacques Chirac from Paris.
tear down (1): Gerhard Schröder
tear down (1): George W. Bush
tear down (1): Tony Blair
tear down (1): Jacques Chirac
tear down (0): Gerhard Schröder
tear down (0): George W. Bush
tear down (0): Tony Blair
tear down (0): Jacques Chirac

6.2 BabelFish SOAP Client

A simple SOAP client for the AltaVista BabelFish service is implemented as another example of an XML application. This service is based on SOAP 1.1 (cf. [SOAP-1.1]).

In order to have JBind "talk" SOAP 1.1 some special steps have to be taken. The reason is that SOAP 1.1 is not based on [XSD-0] but on an intermediate working draft. Two schema documents xml-schema-1999.xsd and xml-schema-instance-1999.xsd are included that contain the definitions from these namespaces that are necessary to talk with the BabelFish service.

The soap11.xsd schema document contains the type Client whose attributes contain the information that is necessary to talk to a SOAP service. In addition, it has a behaviour class where the execute method of the XML application is implemented. The Client class contains only SOAP specific functionalities. It creates a SOAP envelope, validates the envelope, marshals the envelope for transmission, does the networking, and unmarshals the result. All service dependent parts are delegated to an envelopeHandler that must be configured as an element of the client. The following code snippet shows the corresponding lines from the Client class:

ISchema schema = Schemas.getInstance().getSchema("http://www.jbind.org/examples/soap11");
IFactoryData factory = (IFactoryData)schema.getFactory();
IEnvelopeData envelope = (IEnvelopeData)factory.createEnvelope();
getEnvelopeHandler().fillEnvelope(envelope);
JBindFacade.validateData(envelope, null);
URL url = new URL("http", getHost(), getPort(), getFile());
HttpURLConnection connection = (HttpURLConnection)url.openConnection();
connection.setRequestMethod("POST");
connection.setRequestProperty("Content-Type", "text/xml");
connection.setRequestProperty("SOAPAction", getAction());
connection.setDoOutput(true);
OutputStream os = connection.getOutputStream();
JBindFacade.marshal(os, "UTF-8", true, envelope, null, null);
os.flush();
connection.connect();
InputStream is = connection.getInputStream();
InputSource inputSource = new InputSource(is);
IEnvelopeData result = (IEnvelopeData)JBindFacade.unmarshal(inputSource, null);
getEnvelopeHandler().acceptResult(result);
          

The BabelFish specific part includes a schema document with the defintions of the SOAP body blocks of the request/response messages and of the BabelFishEnvelopeHandler. In addition, the methods to fill a SOAP envelope with a corresponding request element and to accept the response have to be implemented. For brevity, only the definition of the soap client, the implementation of the BabelFishEnvelopeHandler, the XML application code, and the result of running the application is shown here:

<complexType 
  name="Client" 
  jb:hasBehaviour="true">
  <sequence>
    <element 
      ref="tns:envelopeHandler"/>
  </sequence>
  <attribute name="host" 
    type="anyURI" 
    use="required"/>
  <attribute name="port"
    type="unsignedShort" 
    use="required"/>
  <attribute name="file" 
    type="string" 
    use="required"/>
  <attribute name="action" 
    type="string" 
    use="required"/>
</complexType>

<complexType 
  name="EnvelopeHandler"
  jb:hasBehaviour="true" 
  abstract="true"/>

<element 
  name="envelopeHandler"
  type="tns:EnvelopeHandler"/>

input : it's raining cats and dogs
output: es regnet Katzen und Hunde

package org.jbind.example.soap.babelFish;

import org.jbind.example.soap.soap11.IEnvelopeData;
import org.jbind.example.soap.soap11.IBodyData;
import org.jbind.xml.msg.XmlException;
import java.util.Iterator;
import org.jbind.base.Console;

public abstract class BabelFishEnvelopeHandler 
extends org.jbind.example.soap.soap11.EnvelopeHandler
implements IBabelFishEnvelopeHandler {
  
  public void fillEnvelope(IEnvelopeData anEnvelope)
  throws XmlException {
    IBodyData body = anEnvelope.createBody();
    IBabelFishData request = (IBabelFishData)body
    .createElement_("urn:xmethodsBabelFish","BabelFish",
    null, null);
    request.createTranslationmode(getTranslationMode());
    request.createSourcedata(getTextToTranslate());
  }
  
  public void doAcceptResult(IEnvelopeData anEnvelope) 
  throws XmlException {
    IBodyData body = anEnvelope.getBody();
    for (Iterator i = 
      body.iterElements_("urn:xmethodsBabelFish",
      "BabelFishResponse"); i.hasNext(); ) {
      IBabelFishResponseData response =
      (IBabelFishResponseData)i.next();
      Console.out("input : " + getTextToTranslate());
      Console.out("output: " + response.getReturn());
    }
  }
}

<?xml version="1.0" encoding="UTF-8" ?>
<soap11:client
  xmlns:soap11="http://www.jbind.org/examples/soap11"
  xmlns:bf="urn:xmethodsBabelFish"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="
    urn:xmethodsBabelFish                     babelFish.xsd
    http://schemas.xmlsoap.org/soap/encoding/ ../soap11/soap-encoding.xsd
    http://schemas.xmlsoap.org/soap/envelope/ ../soap11/soap-envelope.xsd
    http://www.w3.org/1999/XMLSchema          ../soap11/xml-schema-1999.xsd
    http://www.w3.org/1999/XMLSchema-instance ../soap11/xml-schema-instance-1999.xsd
    http://www.jbind.org/examples/soap11      ../soap11/soap11.xsd"
  host="services.xmethods.net" port="80" file="/perl/soaplite.cgi" 
  action="urn:xmethodsBabelFish#BabelFish"
>
  <bf:envelopeHandler translationMode="en_de" textToTranslate="it's raining cats and dogs"/>
</soap11:client>

6.3 Maze Game

The maze game is realized by a simple web application implemented mainly by the MazeServlet class. The maze structure is specified by a schema consisting of rooms and exits linking these rooms. The servlet is configured by a maze instance document and allows to "move" between the different rooms. The HTML view of a room is generated by a stylesheet using an XSLT processor. The room data (i.e. its name and exits) is supplied to the stylesheet by creating a SAXSource for the data.

<element name="maze" type="tns:Maze"/>

<complexType name="Maze" jb:hasBehaviour="true">
  <annotation>
    <appinfo>
      <jb:keyref name="initialRoom"
          refer="tns:roomIndex">
        <selector xpath="."/>
        <field xpath="@initialRoom"/>
      </jb:keyref>
    </appinfo>
  </annotation>
  <choice minOccurs="0" maxOccurs="unbounded">
    <element name="room" type="tns:Room"/>
  </choice>
  <attribute name="initialRoom" type="Name"/>
</complexType>

<complexType name="Room" jb:hasBehaviour="true">
  <annotation>
    <appinfo>
      <jb:key name="roomIndex"
          jb:referencedType="tns:Room">
        <selector xpath="."/>
        <field xpath="@name"/>
      </jb:key>
      <jb:unique name="x" scope="local">
        <selector xpath="exit"/>
        <field xpath="@name"/>
      </jb:unique>
    </appinfo>
  </annotation>
  <sequence>
    <element name="exit" type="tns:Exit" minOccurs="0"
      maxOccurs="unbounded"/>
  </sequence>
  <attribute name="name" type="Name" use="required"/>
</complexType>

<complexType name="Exit">
  <annotation>
    <appinfo>
      <jb:keyref name="toRoom" refer="tns:roomIndex">
        <selector xpath="."/>
        <field xpath="@toRoom"/>
      </jb:keyref>
    </appinfo>
  </annotation>
  <attribute name="name" type="Name"/>
  <attribute name="toRoom" type="Name"/>
</complexType>

<maze xmlns="maze"
   xsi:schemaLocation="maze maze.xsd"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   initialRoom="Room1">
  <room name="Room1">
    <exit name="east" toRoom="Room2"/>
    <exit name="south" toRoom="Room3"/>
  </room>
  <room name="Room2">
    <exit name="west" toRoom="Room1"/>
    <exit name="south" toRoom="Room4"/>
  </room>
  <room name="Room3">
    <exit name="north" toRoom="Room1"/>
  </room>
  <room name="Room4">
    <exit name="north" toRoom="Room2"/>
    <exit name="beam" toRoom="Room1"/>
  </room>
</maze>

<html xsl:version="1.0"  xmlns:x="maze"
  xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
  <xsl:variable name="rName" select="x:room/@name"/>
  <head>
    <title>
      Maze - <xsl:value-of select="$rName"/>
    </title>
  </head>
  <body>
    <h2>
      You are in: <xsl:value-of select="$rName"/>
    </h2>
    <p>Where do you want to go?<p/>
    <p>
      <xsl:for-each select="x:room/x:exit">
        <a href="?room={$rName}&amp;exit={@name}">
          <xsl:value-of select="@name"/>
        </a><br/>
      </xsl:for-each>
    </p>
  </body>
</html>

// Read the maze configuration
String maze = aConfig.getInitParameter("maze");
URL url = getClass().getResource(maze);
myConfigurationCode =
  JBindFacade.createConfigurationCode(url, null);
myConfigurationCode.setup();
myMaze = (IMaze)myConfigurationCode.getCode();
// Read and prepare the XSL
String template = aConfig.getInitParameter("template");
url = getClass().getResource(template);
TransformerFactory transformerFactory =
  TransformerFactory.newInstance();
if (!transformerFactory.getFeature(SAXSource.FEATURE)) {
  throw new ServletException("SAXSource not supported");
}
Source xsl = new StreamSource(url.toString());
myStylesheet = transformerFactory.newTransformer(xsl);

// Determine the next room
IRoom nextRoom = null;
String roomName = aRequest.getParameter("room");
if (null == roomName) {
  nextRoom = myMaze.refInitialRoom();
} else {
  IRoom srcRoom = myMaze.getRoomByName(roomName);
  String exitName = aRequest.getParameter("exit");
  IExitData exit = srcRoom.getExitByName(exitName);
  nextRoom = exit.refToRoom();
}
// Generate the response
aResponse.setContentType("text/html");
PrintWriter out = aResponse.getWriter();
Source request = JBindFacade.createSaxSource(nextRoom);
Result response = new StreamResult(out);
try {
  myStylesheet.transform(request, response);
} catch (TransformerException e) {
  throw new ServletException(e);
}
out.close();

The JBind distribution contains the maze.war file that can directly be deployed in any servlet container. Using JBoss in its standard configuration it can be accessed under the URL http://localhost:8080/maze/.

7.1 Validation Options

7.2 ClassLoader Configuration

7.3 Regular Expressions

The name of a class can be configured that is used to create regular expression. The configured class must implement the IRegExFactory interface.

7.4 XPath

The name of a class can be configured that is used to create XPaths. The configured class must implement the IXPathFactory interface. The used XPath factory is related to the data implementation factory because (normally) XPaths are evaluated base on the data implementation.

7.5 Data Implementation Factory

The name of a class can be configured that is used to create data implementations. The configured class must implement the IDataImplFactory interface. The used data implementation factory is related to the used XPath factory (see above).

7.6 Namespace to Package Mapping

A mapping from namespaces to package names can be configured. This mapping is used to define the schema package of schemas for which no other package information is available. For the precedence of package information see 3.3 Parameterizing the Code Generation.

7.7 Entity Resolver, Import, and Include

The name of the class can be configured that is used to resolve entities for SAX parsers. The configured class must implement the org.xml.sax.EntityResolver interface.

In many cases the default mechanism used by JBind is sufficient. [Definition: Entities are resolved with the help of XML catalogs (cf. [XML Catalogs]). In short, XML catalogs can resolve entities given their public or system identifiers and they can map URIs into URIs.] JBind uses XML catalogs to resolve entities during SAX parsing and to map namespace URIs into schema document URLs.

The keys of the xmlCatalogs node in the configuration specify the XML catalogs to be used. The value a key maps into specifies how a catalog is loaded. Two modes are supported: 1. Catalogs might be accessed by a class loader using the Config.class.getResource method (LOAD_BY_CLASS_LOADER) or 2. by URLs (LOAD_BY_URL). Relative URLs are resolved relative to the current user home directory. In the default configuration JBind tries to load the following catalogs:

The standard configuration of JBind allows the integration of arbitrary XML catalogs very easily because of the predefined application and user catalog. In order to have an XML catalog used by JBind simply name it "catalog.xml" and make it accessible to the class loader or name it ".catalog.xml" and place in the user home directory.

When a namespace is imported by an import element then the location of the schema document for the namespace is determined by trying several options in sequence. The algorithm first determines a resulting URL and then an effective URL that is finally used to access the schema document. The options are:

1. If the namespace URI is mapped into a URL by an XML catalog entry then this URL is used as the resulting URL.

2. If the import element has a schemaLocation attribute then this URL is used as the resulting URL.

3. Otherwise the namespace URI is used as the resulting URL.

The situation, when a schema document of a namespace is introduced in an instance document using the xsi:schemaLocation or xsi:noNamespaceSchemaLocation attribute is treated similarly to importing namespaces:

1. If the namespace URI is mapped into a URL by an XML catalog entry then this URL is used as the resulting URL.

2. Otherwise the specified URL is used as the resulting URL.

When a schema document is included or redefined by an include or redefine element, respectively, then it is also tried to map the URL specified by the schemaLocation attribute using the XML catalog.

7.8 How Instances are Linked with their Schemas

When an instance document is unmarshalled then the corresponding schema information must be available. JBind offers several possiblities to link instance documents with their schemas.

1. By using the xsi:schemaLocation and xsi:noNamespaceSchemaLocation attributes in instance documents.

   This situation is described in section 7.7 Entity Resolver, Import, and Include. In short, the URL of a schema is either looked up in an XML catalog based on either its namespace or the specified URL. If the lookup does not return a URL then the specified URL is used.

2. By explictly reading in and registering schemas before instance documents refer to them.

   While an instance document is unmarshalled JBind looks up schema information for every globally scoped element or attribute using the Schemas singleton. A schema can be read in by the JBindFacade.readSchema method and registered by the Schemas.setSchema method.