1 Introduction

This document describes the Simple XML Protocol Binder, a suite of Java classes providing the following functionality:

· generation of Java source files defining classes corresponding to simple XML message formats

· serializing objects of these generated classes into XML form (“marshalling”)

· deserializing the objects from XML to Java objects (“unmarshalling”)

· transmission of the XML messages between a server and client utilizing an HTTP transport

· routing of received messages on the server to appropriate handlers, and the retrieval of response messages for return to the client

2 XML Message Format

2.1 Restrictions

The following rules define the range of message formats supported:

· messages are restricted to XML elements and enclosed text

· a message comprises XML elements, their attributes, and child elements, and enclosed text

· only one text string per element is allowed

· child elements may be specified as a single occurrence of an element type, or as an array of unspecified size

· attributes, child elements, and text can be optional or required, providing a basic validation capability

2.2 Schema Language

A simple XML schema language is defined for specifying message formats. It comprises five element types defined in the table below

Name	Purpose	Attributes
<schema>	Required XML root element
<element>	Defines a message element and a corresponding Java class	type the XML element type. The corresponding Java class name will consists of the element type string, with an optional standard prefix for all classes. extends optional name of a parent class which the corresponding Java class extends abstract boolean value declaring the corresponding java class is abstract. Defaults to “false”
<attribute>	Defines message attributes, and corresponding class members of the corresponding Java class	name the attribute name, and the name of the corresponding Java class member type the type of the Java class member requiredboolean value specifying if the attribute is required. Defaults to “false”
<child>	Specifies child elements	name the name of the Java class member containing the reference to the child object type the type of the child element, corresponding to the type attribute of the child <element> definition member required boolean value specifying if the attribute is required. Defaults to “false” array boolean value specifying if multiple occurrences of the child element are allowed. The corresponding class member will be defined as an array of the child element type
<data>	Specifies that the enclosing element can contain text data	required Boolean value specifying if data is required or optional. Default is false

2.3 Supported Attribute Types

The type attribute of the <attribute> element specifies the Java type of the corresponding class member. The following common types are supported:

Boolean
Byte
Short
Integer
Long
Float
Double
String
Date

2.4 Naming Guidelines

For clarity and simplicity, the following naming conventions are recommended. These are optional, but result in java source code adhering to the de facto standard Java naming conventions:

The element types should use the standard Java class name convention, i.e. the first letter of each word in the string is capitalized, and all others are lower case. Exceptions are made for abbreviated acronyms appearing as part of the name
Attribute and child names should use the standard Java class member name convention, i.e. the same as for Class names, expect that the first letter is lower case.

There is a set of reserved names that cannot be applied to child elements or attributes in the schema. These are listed in Section 3.3.

2.5 Example

The following schema defines six element types required to assemble a “Family” message:

</element>

</element>

</element>

</element>

</element>

</element>

</schema>

Here is a message adhering to the above schema. Not shown are the transmitted attributes with the reserved names __class__ and __name__ , which are described in Section 3.3

This is Smith family data

</Father>

</Child>

This is Ricky's stuff

</Child>

This is Sally's stuff

</Child>

</Child>

</Family>

A few things to note:

Elements intended to form the root element of a message are not distinguished in any way from elements which will appear as children
The command and familyName attributes in the <Family> message element is required.
The <Family> element also requires a father child element and at least one Child member corresponding to the father’s sons attribute
The name attribute of an <attribute> element in the schema shows up as an attribute name in a message, e.g. the “command” attribute element in the schema corresponds to a command attribute in the Family element in the message. However, the name attribute of a <child> element in the schema is transported in an extra attribute with the reserved name “__name__”. This is required to support the specification of multiple child elements of the same type.
Father extends Adult which extends Person, which is abstract. Child also extends Person

3 Generated Java Source Code

One java class is generated for each XML message element declared in the schema. The left column in the table below shows the schema definitions introduced earlier. The right column shows the generated class declaration, and the members corresponding to element attributes, child elements, and enclosed text. Method code and class member access modifiers are not included, nor are the boolean flags which define which members are required.)

Schema Element

Java Class Definition

</element>

public class Family extends IdcAbstractElement {

public java.lang.String command;

public java.lang.String familyName;

public java.lang.String description;

public Father father;

public Child[] sons;

public Child[] daughters;

public String __data__ = null;

}

</element>

public abstract class Person
extends IdcAbstractElement {

public java.lang.String name;

public java.util.Date birthday;

public Hobby[] hobbies;

}

</element>

public abstract class Adult extends Person {

public String __data__ = null;

}

</element>

public class Father extends Adult {

public java.lang.String employer;

}

</element>

public class Child extends Person {

public java.lang.String nickname;

public boolean __required__nickname = true;

public String __data__ = null;

}

</element>

public class Hobby extends IdcAbstractElement {

public java.lang.String description;

public java.lang.Boolean hazardous;

}

3.2 Undefined Attributes Values

Attributes specified as optional (by default or specifying required=”false” in the schema), are represented by null object references populated by unmarshalling from an XML message.

3.3 Standard Methods and Attribute Names

The Binder generates the following set of methods for each class. Most are required by the Marshaller, but they all have public access, and are usable by the application code:

No argument constructor
Constructor accepting all attributes
Constructor accepting all attributes and all children
Bean style get and set methods for each argument and child; for child arrays, only the full array form is provided (i.e. not the indexed form for individual array members)
An extra set of set methods for attributes which are of any of the supported numeric types, but with the argument declared as the primitive form rather than the wrapper
setTextElementData and getTextElementData to get or set an element’s contained text
A getAllAttributeNames method
A getAllChildNames method
A getElementType method returning the name of the element corresponding to the Java class

The following two element attributes appear in the transmitted elements, have no correspondence to class members of the generated classes:

· __class__ carries the full class name

· __name__ class member name in the parent object to which the element is to be assigned

Note that elements should not be defined which would cause conflicts with the standard method and reserved attribute names; for example, an attribute named textElementData is invalid. The Binder will throw an exception if such names are encountered.

4 System Generation

System generation is the process of reading the schema file and generating the Java source code of the classes corresponding to the messages defined in the schema. This is performed by the com.protocol.xml.util.Binder class.

The following parameters are required by the Binder:

· path to a schema definition file

target directory path
package to which the generated classes are to belong. The package folder hierarchy will be created below the target directory.
standard prefix for all generated class names (optional)
path to file containing common header for all generated source files (optional)
path to a log file for reporting unresolved child references

These parameters are provided to the Binder in a properties file. Refer to the javadoc of the main() method of the Binder class for more details.

5 Message Delivery

On the client, the com.protocol.xml.client.Connector class is used to send all messages. It contains a single static send() method to perform the marshalling of Java objects into XML messages, and transmission of the messages to the server. This method employs Java reflection to determine the structure and format of the XML message. Thus the schema definition is required only at “system generation” time, when the Java source files are generated, but not at runtime.

Each XML element generated during marshalling includes an additional attribute not defined in the schema. The string “__class__” is reserved for the name of this attribute, which carries the fully qualified name of the Java class bound to the message type.

A single Servlet of class com.protocol.xml.server.Servlet receives the XML messages and unmarshalls them into Java objects of the class specified in the “__class__ attribute. The resulting objects are then dispatched to processing objects (Data Managers) via the com.protocol.xml.server.MessageProcessor interface. If a response object is returned by the MessageProcessor, the servlet marshals it into an XML message, and returns it to the client.

Mappings of messages to MessageProcessor objects are defined in a configuration file. The name and location of the file are specified in a web application <init-param> element in the web.xml file.

6 Protocol Binder Packages

The Simple XML Protocol Binder consists of four packages:

· com.protocol.xml.util: contains the Binder class, which generates the Java source files according the XML message schema.

· com.protocol.xml.client: contains the Connector class for sending XML messages to the server

· com.protocol.xml.server: contains the Servlet class and the MessageProcessor interface for processing received messages

· com.protocol.xml.common: contains classes common to both the client and the server

The util package is not required at application runtime. The client and common packages must be included in the client. The server and common packages must be included in the server web application.

7 Runtime Configuration

7.1 Client

The client side Connector class is initialized with a single static URL as a destination for transmitted messages. Refer to the javadoc for more details.

7.2 Server

The web application configuration file contains one required and one optional Servlet initialization parameter, as shown below:

<init-param>

<param-name>messageMapFile</param-name>

<param-value>WEB-INF\messageMap.xml</param-value>

</init-param>

<init-param>

<param-name>loggingEnabled</param-name>

<param-value>true</param-value>

</init-param>

The required messageMapFile parameter specifies the context-relative path to the message map file. The format of the map file is of the form:

<map>

<message ……etc.

</map>

where MMMM is the type of a message, and PPPP is the package qualified name of the corresponding MessageProcessor class

The optional loggingEnabled parameter turns logging on or off. The default is off. If turned on (true), then each received message is logged, after the successful creation of the Java object, in its full xml document form.