<Quick> <JXML> <Download> <QDML>
A QJML binding schema is used by Quick to bind the elements and attributes of an XML markup language to various Java classes.
When developing an application using Quick, the first step is to create a QDML schema, which describes the XML documents to be processed. QDML files can be created by hand, or a DTD file can be converted to QDML using the DTD2QDML utility.
The second step is to convert that QDML schema into a QJML binding schema, which specifies how the XML elements and attributes are converted into Java objects. This is done using the QDML2QJML utility, though it is best to edit the results and change the generated names to something more meaningful.
Once you have a QJML file, you need to integrate it with your existing code. The QJML Wizard will help you find where the QJML file doesn't conform with your code.
On the other hand, if you are writting code from scratch, then use the QJML2Java utility to create an initial draft of your code based on the information found in the QJML binding schema.
Each QDML element is described as follows:
The following color scheme is used:
|
The qjml element is the root element of the document. It serves the purpose of providing the single root element that is required of a well-formed XML document, as well as identifying the document as a QJML binding schema.
Sample XML
<timesheet name="Bill la Forge">
<day date="19990913">
<entry hours="8" project="quite"/>
</day>
<day date="19990914">
<entry hours="6" project="quite"/>
<entry hours="2" project="admin"/>
</day>
<day date="19990915">
<entry hours="8" project="quite"/>
</day>
<day date="19990916">
<entry hours="8" project="vacation"/>
</day>
<day date="19990917">
<entry hours="8" project="quite"/>
</day>
</timesheet>
QDML
<qdml root="timesheet"> . . <!--timesheet elements--> . </qdml>
QJML
<qjml root="timesheet"> . . <!--timesheet elements--> . </qjml>
Java: none
This is an example of a fragment of a QJML binding schema. In this example, we are defining a markup language, timesheet, which has a root element of timesheet.
Attributes
A qjml element has a required attribute, root. This attribute identifies the outermost element of the markup language being defined by the QJML binding schema.
Content Model
Every qjml element must contain one or more element elements. These subordinate elements specify the various elements that comprise the markup language being defined by the QJML binding schema.
|
Property Editors are easy to write and provide a standard interface for data validation and for conversion of that data into an object. In the QJML binding schema, the programmer can identify the appropriate Property Editor for validating every data item held by an XML document.
Property Editors are bi-directional, in that they also contain the logic for converting an object into text when the object's toString method does not return appropriate values.
The targetEditor element binds a JavaBeans[tm] PropertyEditor to an attribute or to an element:
When an attribute is bound to a Property Editor, the type attribute in the attribute definition must not be specified.
When an element is bound to a Property Editor, the content attribute in the element definition must be assigned a value of PCDATA.
Quick uses the Property Editors identified in the QJML binding schema to convert the attribute value or element content to an object, and also to convert an object into an attribute value or element content.
Perhaps most importantly, the Property Editor is used to validate the element content or attribute value when a document is parsed. By specifying the appropriate Property Editors, the programmer can be assured that only valid data will be passed to the application.
Sample XML
<date>19990916</date>
QDML
<element name="date"
content="PCDATA">
</element>
QJML
<element name="date"
content="PCDATA">
<targetEditor target="com.jxml.quick.examples.timesheet.Date"
editor="com.jxml.quick.examples.timesheet.YYYYMMDDEditor"/>
</element>
Java
package com.jxml.quick.examples.timesheet;
import java.beans.*;
public class YYYYMMDDEditor extends PropertyEditorSupport
{
public static final int[] maxDay=
{
31,29,31,30,31,30,31,31,30,31,30,31
};
public void setAsText(String text) throws java.lang.IllegalArgumentException
{
if (text.length()!=8)
throw new IllegalArgumentException
("YYYYMMDD length is not 8: "+text);
int i=Integer.parseInt(text);
int d=i%100;
int m=(i/100)%100;
if (m==0 || m>12)
throw new IllegalArgumentException
("YYYYMMDD month is invalid: "+text);
if (d==0 || d>maxDay[m])
throw new IllegalArgumentException
("YYYYMMDD day is invalid: "+text);
Date date=new Date(i);
setValue(date);
}
}
In this example we have bound the property editor YYYYMMDDEditor to element date.
The property editor overrides the setAsText method on the class PropertyEditorSupport, which gives the property editor the ability to validate the text content of the element and to create a Date object.
In the case of the Date class, the toString method returns a reasonable value, so nothing more is required of the property editor. In cases where the toString method does not return a reasonable value, the property editor must also override the getAsText method.
Attributes
The targetEditor element has the following attributes:
The target attribute specifies the class of the object which the property editor creates.
This attribute is required.
The editor attribute specifies the class of the property editor to which the element or attribute being defined is bound.
This attribute is optional. When not specified, the property editor class is derived from the target attribute.
Content Model: EMPTY
|
The targetClass element binds an XML element or attribute directly to a Java class. When the element or attribute are parsed, that Java class is used to create an object. And when expressing a structure of objects, instances of that class are expressed as the element or attribute to which it is bound.
(The binding of a Java class to an element need not be unique, so long as it is not ambiguous within the scope of a content model. A Java class can be bound to more than one element or attribute.)
There are several cases when we can bind to a Java class using targetClass:
When an attribute is bound to a Java class and the type attribute in the attribute definition has not been specified.
In this case, there are several requirements placed on the Java class:
The Java class must have a public constructor which accepts a String,
the constructor must perform any and all validation of that String, and
the toString method on that class must return a value which reflects the value passed to the constructor.
If any of these conditions are not met by the Java class, then you will need to write your own Property Editor and bind it to the attribute using targetEditor.
When an element is bound to a Java class and the content attribute in the element definition has been assigned a value of PCDATA.
In this case, there are several requirements placed on the Java class:
The Java class must have a public constructor which accepts a String,
the constructor must perform any and all validation of that String, and
the toString method on that class must return a value which reflects the value passed to the constructor.
If any of these conditions are not met by the Java class, then you will need to write your own Property Editor and bind it to the element using targetEditor.
When an element is bound to a Java class and the content attribute in the element definition has been assigned a value of EMPTY or the content attribute has not been specified.
In this case, the Java class must have a public constructor which has no parameters (sometimes called a null-constructor).
When an element is bound to a Java class and the content attribute in the element definition has been assigned a value of BIMODAL.
In this case, the Java class must have a public constructor which has no parameters sometimes called a null-constructor).
The Java class must also implement the QBiModal interface. (The getQText and setQText methods in this interface are used by Quick to pass and retrieve the element's text content.)
Sample XML
<configuration href="http://www.jxml.com/quick/test32/test.cfg"/>
QDML
<element name="configuration"
content="EMPTY">
<attribute name="href"
status="REQUIRED">
</element>
QJML
<element name="configuration"
content="EMPTY">
<targetClass>com.jxml.quick.test32.Configuration</targetClass>
<attribute name="href"
status="REQUIRED"
field="href">
<targetClass>java.net.URL</targetClass>
</attribute>
</element>
Java
package com.jxml.quick.test32;
import java.net.*;
public class Configuration
{
public URL href=null;
public Configuration()
{
};
}
In this example we have bound the configuration element to the Configuration class (case 3 above), and bound the href attribute to the URL class (case 1 above) using targetClass.
Attributes: none
Content Model
The content of a targetClass element is the full class name of a Java class.
|
The targetFactory element binds an implementation of QTargetFactory.
Target factories are largely used in the implementation of Quick. There is a small speed advantage to using target factories rather than depending on Java reflection, as is the case with targetClass.
Attributes: none
Content Model
The content of a targetClass element is the full class name of a Java class which implements QTargetFactory.
|
The extends element is used to model Java inheritance. An element defined with an extends element can occur anywhere the element referenced by the extends element can occur. (For example, if the referenced element can be a root element, then so can the new element being defined with extends.)
Attributes: none
Content Model
The content of an extends element is the tag name (or label) of the element being referenced.
|
The implements element is used to model Java inheritance. An element defined with an implements element can occur anywhere the element referenced by the implements element can occur. (For example, if the referenced element can be a root element, then so can the new element being defined with implements.)
Attributes: none
Content Model
The content of an implements element is the tag name (or label) of the element being referenced.
|
The element element specifies both the validation requirements and the binding of an XML element.
The QJML element differs from the QDML element with the inclusion of extends and implements elements, a targetClass, targetEditor, or targetFactory element, and cref elements. The content attribute can be assigned additional values, which serve as an implicit specification of a targetEditor. The label, abstract, and interface attributes have been added as well.
Sample XML
<timesheet name="Bill la Forge">
<day date="19990913">
<entry hours="8" project="quite"/>
</day>
<day date="19990914">
<entry hours="6" project="quite"/>
<entry hours="2" project="admin"/>
</day>
<day date="19990915">
<entry hours="8" project="quite"/>
</day>
<day date="19990916">
<entry hours="8" project="vacation"/>
</day>
<day date="19990917">
<entry hours="8" project="quite"/>
</day>
</timesheet>
QDML
<qdml root="timesheet">
<element name="timesheet">
.
. <!--attribute, child, selection, and sequence elements-->
.
</element">
<element name="day">
.
. <!--attribute, child, selection, and sequence elements-->
.
</element">
<element name="entry" content="EMPTY">
.
. <!--attribute elements-->
.
</element">
</qdml>
QJML
<qjml root="timesheet">
<element name="timesheet">
<targetClass>com.jxml.quick.examples.timesheet.Timesheet</targetClass>
.
. <!--attribute, child, selection, and sequence elements-->
.
</element">
<element name="day">
<targetClass>com.jxml.quick.examples.timesheet.Day</targetClass>
.
. <!--attribute, child, selection, and sequence elements-->
.
</element">
<<element name="entry" content="EMPTY">
<targetClass>com.jxml.quick.examples.timesheet.Entry</targetClass>
.
. <!--attribute elements-->
.
</element">
</qjml>
In this fragment of the QJML binding schema for the timesheet markup language, we have now specified and bound three elements: timesheet, day, and entry.
The assignment of EMPTY to the content attribute on the specification of the entry element indicates that this element will contain neither text nor elements.
Attributes
An element element has the following attributes:
name
The name attribute is used to identify the element being defined.
This attribute is required.
label
The label attribute is used to uniquely identify the element being defined when there are several elements with the same name. When this happens, the child element references the element label rather than the element name.
This attribute is optional and, when not present, defaults to the value of name.
wild
The wild attribute is used when processing opaque data, where the names of the elements being processed are unknown.
Classes which are bound to a "wild" element must implement the QName interface.
This attribute defaults to "False".
content
In XML, the content of an element can be text (PCDATA), (CDATA), one or more elements, or a mix of text and elements (MIXED). An element can also have no content (EMPTY).
Quick does not support mixed content, but it does allow elements to contain either text or elements (BIMODAL). (BIMODAL is not part of standard XML terminology.) Classes which are bound to a BIMODAL element must implement the QBiModal interface.
Content types of int, short, long, byte, boolean, float, double, string, base64, url, char, and BigDecimal are extensions of PCDATA. These extensions implicitly invoke a PropertyEditor to create the appropriate scalar or object.
The content type CDATA is identical to PCDATA, except for specifying that the content should be expressed in CDATA format.
The content attribute is used to specify the type of content held by an element.
This is an optional attribute. The values allowed are PCDATA, CDATA, BIMODAL, EMPTY, int, short, long, byte, boolean, float, double, string, base64, url, char, and BigDecimal.
abstract
The abstract attribute, when true, indicates that the element being defined is not one that will occur in an XML document and that the Java class bound to the element is an abstract class.
The abstract attribute can be used to define multiple roots: An abstract element is used as the root, and the actual root elements then extend the abstract element.
This attribute defaults to "False".
interface
The interface attribute, when true, indicates that the element being defined is not one that will occur in an XML document and that the Java class bound to the element is an interface.
The interface attribute can be used to define multiple roots: An interface element is used as the root, and the actual root elements then extend the abstract element.
This attribute defaults to "False".
Content Model
An element element contains the following elements:
The rem elements are comments which describe the element being defined.
The rem elements are optional and repeating. (Any number of rems are allowed.) Each rem contains a single line of text.
extends and implements
These elements are used to model Java inheritance. In addition, an element which extends or implements another can occur anywhere the base element can. (Among other things, this is useful for defining a multi-root schema.)
targetEditor, targetClass, and targetFactory
The targetEditor, targetClass, and targetFactory elements are used to bind a PropertyEditor or Java class to the element being defined.
Use targetEditor only when the content is PCDATA.
Do not use targetEditor, targetClass, or targetFactory when the content is int, short, long, byte, boolean, float, double, string, base64, url, char, or BigDecimal. (In this case a targetEditor is specified implicitly.)
The attribute elements are used to specify the attributes of the element being defined.
The attribute elements are optional and repeating. (Any number of attributes are allowed.) The order of the attribute elements is not significant, since attributes can appear in any order.
Quick does not support attributes on elements specified with a content of PCDATA. (Use BIMODAL instead of PCDATA if you need to use attributes with text content.)
child, selection, sequence, and cref
The child, selection, sequence, and cref elements are used to specify the content model of the element being defined.
These elements are optional, repeatable, and can occur in any order. Their order is significant, since the content model determines the allowable order of the elements held by the element being defined.
If the element being defined has a content of PCDATA, int, short, long, byte, boolean, float, double, string, base64, url, char, BigDecimal or EMPTY, then none of these elements may occur. And if the element being defined has no content attribute specified, then at lease one of these elements must be present.
|
The attribute element specifies the validation requirements, the binding of an XML attribute, and the relationship between the object bound to the attribute and the object bound to the parent element.
The QJML attribute differs from the QDML attribute:
A targetClass, targetEditor, or targetFactory element is used to bind the attribute.
The type attribute can be assigned additional values, which serve as an implicit specification of a targetEditor.
The field, property, and class attributes have also been included to describe the connection between the attribute object and its parent element object.
Sample XML
<timesheet name="Bill la Forge">
<day date="19990913">
<entry hours="8" project="quite"/>
</day>
<day date="19990914">
<entry hours="6" project="quite"/>
<entry hours="2" project="admin"/>
</day>
<day date="19990915">
<entry hours="8" project="quite"/>
</day>
<day date="19990916">
<entry hours="8" project="vacation"/>
</day>
<day date="19990917">
<entry hours="8" project="quite"/>
</day>
</timesheet>
QDML
<qdml root="timesheet">
<element name="timesheet">
<attribute name="name"
status="REQUIRED"/>
.
. <!--child, selection, and sequence elements-->
.
</element">
<element name="day">
<attribute name="date"
status="REQUIRED"/>
.
. <!--child, selection, and sequence elements-->
.
</element">
<element name="entry"
content="EMPTY">
<attribute name="hours"
status="REQUIRED"/>
<attribute name="project"
status="REQUIRED"/>
</element">
</qdml>
QJML
<qjml root="timesheet">
<element name="timesheet">
<targetClass>com.jxml.quick.examples.timesheet.Timesheet</targetClass>
<attribute name="name"
status="REQUIRED"
type="string"
field="name"/>
.
. <!--child, selection, and sequence elements-->
.
</element">
<element name="day">
<targetClass>com.jxml.quick.examples.timesheet.Day</targetClass>
<attribute name="date"
status="REQUIRED"
field="date">
<targetEditor target="com.jxml.quick.examples.timesheet.Date"
editor="com.jxml.quick.examples.timesheet.YYYYMMDDEditor"/>
</attribute>
.
. <!--child, selection, and sequence elements-->
.
</element">
<element name="entry"
content="EMPTY">
<targetClass>com.jxml.quick.examples.timesheet.Entry</targetClass>
<attribute name="hours"
status="REQUIRED"
type="float"
field="hours"/>
<attribute name="project"
status="REQUIRED"
type="string"
field="project"/>
</element">
</qjml>
This QJML fragment binds the attributes used in the timesheet markup language:
The name attribute in the timesheet element is bound to a String variable, name.
The date attribute in the day element is bound to a Date variable, date, using the YYYYMMDDEditor property editor.
The hours attribute in the entry element is bound to a float variable, hours.
The project attribute in the entry element is bound to a String variable, project.
Attributes
An attribute element has the following attributes:
name
The name attribute is used to identify the attribute being defined.
There is one special case, when name has an assigned value of #ANY. In this case, the attribute being defined will match to attributes without reference to the attribute name.
Classes which are bound to a "#ANY" attribute must implement the QName interface.
This attribute is required.
type
The type attribute is used to specify how the attribute being defined is to be processed:
An id attribute is used to assign an identifier to an element in a document. The value assigned to an element's id attribute is the identifier for that element. Within the context of a document, id values must be unique.
IDs are not attached to the object bound to the parent element. Rather, IDs are mapped to the parent object in a table held by the QDoc object.
An idref attribute is used to reference another element in the same document. The value assigned to an idref attribute is the identifier of the element being referenced.
An implicit targetEditor is specified when the attribute type is int, short, long, byte, boolean, float, double, string, base64, url, char, or BigDecimal.
This is an optional attribute. The values allowed are id, type, int, short, long, byte, boolean, float, double, string, base64, url, char, and BigDecimal.
status
The status attribute is used to specify that the attribute being defined must be present:
A status of REQUIRED indicates that the attribute being defined must always be present. (By default, attributes are optional.)
A status of FIXED indicates that the attribute being defined has a fixed value that can not be changed, though the attribute is not required to be present.
This is an optional attribute. The values allowed are REQUIRED and FIXED.
value
The value attribute is used to supply the default value of an attribute.
This attribute is required when the status of the attribute being defined is FIXED.
This attribute must not be present when the status of the attribute being defined is REQUIRED.
field, property, and class
The field, property, and class attributes are used to attach the object bound to the attribute to the object bound to the parent element:
The field attribute names a public field in the class bound to the parent element.
The property attribute names a JavaBean property on the class bound to the parent element. Both the get and set methods defining the property must be present and public.
Here's an example of an int property, count:
public class foo
{
int myCounter=0;
public int getCount()
{
return myCounter;
}
public void setCount(int counter)
{
myCounter=counter;
}
}
The class attribute names a class used to connect the attribute object to its parent object. This class must implement the QAccess interface.
Content Model
An attribute element contains the following elements:
An attribute element may contain rem elements, which are comments describing the attribute.
The value elements are optional, and there may be more than one.
targetEditor, targetClass, and targetFactory
The targetEditor, targetClass, and targetFactory elements are used to bind a PropertyEditor or Java class to the element being defined.
Do not use targetEditor, targetClass, or targetFactory when the type attribute is is present.
A targetEditor, targetClass, or targetFactory element must be present when the type attribute is is not present.
An attribute element may contain value elements, which enumerate the legal values that may be assigned to the attribute being defined.
The value elements are optional, and there may be more than one.
|
The rem element is used to describe elements and attributes.
The QJML rem is identical to the QDML rem.
|
The value element enumerates through the legal values of an attribute.
The QJML value is identical to the QDML value.
|
A child element is used to specify a child element that is contained within the content model of another element and to describe the relationship between the child and parent objects bound to the these elements.
Sample XML
<timesheet name="Bill la Forge">
<day date="19990913">
<entry hours="8" project="quite"/>
</day>
<day date="19990914">
<entry hours="6" project="quite"/>
<entry hours="2" project="admin"/>
</day>
<day date="19990915">
<entry hours="8" project="quite"/>
</day>
<day date="19990916">
<entry hours="8" project="vacation"/>
</day>
<day date="19990917">
<entry hours="8" project="quite"/>
</day>
</timesheet>
QDML
<qdml root="timesheet">
<element name="timesheet">
<attribute name="name"
status="REQUIRED"/>
<child element="day"
repeating="True"/>
</element">
<element name="day">
<attribute name="date"
status="REQUIRED"/>
<child element="entry"
repeating="True"/>
</element">
<element name="entry"
content="EMPTY">
<attribute name="hours"
status="REQUIRED"/>
<attribute name="project"
status="REQUIRED"/>
</element">
</qdml>
QJML
<qjml root="timesheet">
<element name="timesheet">
<targetClass>com.jxml.quick.examples.timesheet.Timesheet</targetClass>
<attribute name="name"
status="REQUIRED"
type="string"
field="name"/>
<child element="day"
repeating="True"
listField="days"/>
</element">
<element name="day">
<targetClass>com.jxml.quick.examples.timesheet.Day</targetClass>
<attribute name="date"
status="REQUIRED"
field="date">
<targetEditor target="com.jxml.quick.examples.timesheet.Date"
editor="com.jxml.quick.examples.timesheet.YYYYMMDDEditor"/>
</attribute>
<child element="entry"
repeating="True"
listField="entries"/>
</element">
<element name="entry"
content="EMPTY">
<targetClass>com.jxml.quick.examples.timesheet.Entry</targetClass>
<attribute name="hours"
status="REQUIRED"
type="float"
field="hours"/>
<attribute name="project"
status="REQUIRED"
type="string"
field="project"/>
</element">
</qjml>
Here we have the complete QJML binding schema for the timesheet markup language. We have now bound the content model of the timesheet element to the public days variable of the Timesheet class and we have bound the content model of the day element to the public entries variable of the Day class.
Attributes
The label attribute uniquely identifies the child element.
This attribute is optional.
The element attribute provides the name (or label) of the element being included in the content model of the element being defined.
This attribute is required.
The optional and repeating attributes are used to control the number of allowed occurances of an element within the content model:
| optional | repeating | Number of Occurances |
| True | True | Zero or more |
| False | False | Exactly one |
| True | False | No more than one |
| False | True | One or more |
These attributes both default to False when not present.
field, property, class, listField, and listProperty
These attributes are used to define the connection between an object bound to the element being defined and an object bound to a child element:
field
The field attribute names a public field in the class bound to the parent element.
This attribute does not work with repeating child elements.
property
The property attribute names a JavaBean property on the class bound to the parent element. The get method defining the property must be present and public.
The put method defining the property is optional. When present (and public) and an XML document is being parsed, a new object is created for the child element and the put method is used to update the containing parent object. (This behavior is the same as when a field attribute is used instead of a property attribute.)
But when the JavaBean property is defined with only a get method and no put method, the child object must have been created by the constructor of the containing parent object. Now when processing an XML document, the attributes and content of child element are used to update that child object, rather than to create a new child object.
This attribute does not work with repeating child elements.
class
The class attribute names a class used to connect the child element object(s) to its parent object. This class must implement the QAccess interface.
listField
The listField attribute names a public field in the class bound to the parent element. This field must be defined as a reference to java.util.List, or as a reference to a class derived from List.
While the field attribute works with a single, non-repeating child element, this attribute works with both repeating and non-repeating child elements.
listProperty
The listProperty attribute names a JavaBean property on the class bound to the parent element. The get method defining the property must be present and public, and must return a List (or a class which implements List).
(The put method for the property, if present, is ignored.)
While the property attribute works with a single, non-repeating child element, this attribute works with both repeating and non-repeating child elements.
No more than one of these attributes should be specified on a child element.
None of these attributes need be specified so long as they are specified on a containing selection or sequence element.
Content Model: EMPTY
|
The sequence element is used to introduce alternatives to the content model and to describe the relationship between child objects and the parent object which contains them.
Sample XML
<automobile>
<standardTransmission/>
</automobile>
QDML
<element name="automobile">
<selection>
<child element="standardTransmission"/>
<child element="automaticTransmission"/>
</selection>
</element">
QJML
<element name="automobile">
<targetClass>Auto</targetClass>
<selection property="transmission">
<child element="standardTransmission"/>
<child element="automaticTransmission"/>
</selection>
</element">
Java
public class Auto
{
protected Transmission trans;
public Transmission getTransmission()
{
return trans;
}
public void setTransmission(Transmission t)
{
trans=t;
}
}
public class StandardTransmission implements Transmission
{
.
.
.
}
public class AutomaticTransmission implements Transmission
{
.
.
.
}
Here we see a QJML fragment which identifies a JavaBean property, transmission, as the means for connecting the children of Auto. When expressing an Auto object in XML, Quick will make use of the Java instanceof operator to determine which element to express as the child of the automobile element.
Attributes
The label attribute is used to uniquely identify the selection element, allowing the same selection element to be reused in another content model.
This attribute is optional.
The optional and repeating attributes are used to control the number of allowed occurances of the alternatives specified by the child, selection, sequence, and cref elements contained in the selection element:
| optional | repeating | Number of Occurances |
| True | True | Zero or more |
| False | False | Exactly one |
| True | False | No more than one |
| False | True | One or more |
These attributes both default to False when not present.
field, property, class, listField, and listProperty
These attributes are used to define the connection between an object bound to the element being defined and an object bound to a child element:
field
The field attribute names a public field in the class bound to the parent element.
This attribute does not work with repeating child elements, nor if selection contains a sequence element.
property
The property attribute names a JavaBean property on the class bound to the parent element. The get method defining the property must be present and public.
The put method defining the property is optional. When present (and public) and an XML document is being parsed, a new object is created for the child element and the put method is used to update the containing parent object. (This behavior is the same as when a field attribute is used instead of a property attribute.)
But when the JavaBean property is defined with only a get method and no put method, the child object must have been created by the constructor of the containing parent object. Now when processing an XML document, the attributes and content of child element are used to update that child object, rather than to create a new child object.
This attribute does not work with repeating child elements, nor if selection contains a sequence element.
class
The class attribute names a class used to connect the child element object(s) to its parent object. This class must implement the QAccess interface.
listField
The listField attribute names a public field in the class bound to the parent element. This field must be defined as a reference to java.util.List, or as a reference to a class derived from List.
While the field attribute works with a single, non-repeating child element, this attribute works with both repeating and non-repeating child elements.
listProperty
The listProperty attribute names a JavaBean property on the class bound to the parent element. The get method defining the property must be present and public, and must return a List (or a class which implements List).
(The put method for the property, if present, is ignored.)
While the property attribute works with a single, non-repeating child element, this attribute works with both repeating and non-repeating child elements.
No more than one of these attributes should be specified on a selection element.
These attributes are optional.
Content Model
The child, selection, sequence, and cref elements are used to specify alternative content models.
These elements are optional, repeatable, and can occur in any order, so long as there is at least one child, selection, sequence, or cref element present in the selection element content.
|
The sequence element lets us define sequences in the content model and to describe the relationship between child objects and the parent object which contains them.
Sample XML
<map name="Bill la Forge">
<key>Fred Smith</key>
<ssn>101-33-9320</ssn>
<key>John Spade</key>
<ssn>221-56-7890</ssn>
<key>Big Little, Inc.</key>
<cid>04-98789234</cid>
</map>
QDML
<qdml root="map">
<element name="map">
<sequence optional="True"
repeating="True">
<child element="key"/>
<selection>
<child element="ssn"/>
<child element="opaque"/>
</selection>
</sequence>
</element>
<element name="key"
content="PCDATA"/>
<element name="ssn"
content="PCDATA"/>
<element name="opaque"
wild="True">
content="BIMODAL">
<attribute name="#ANY"/>
<child element="opaque"
optional="True"
repeating="True"/>
</element>
</qdml>
QJML
<qjml root="map">
<element name="map">
<targetClass>java.util.ArrayList</targetClass>
<sequence optional="True"
repeating="True"
class="com.jxml.quick.access.QListAccess">
<child element="key"/>
<selection>
<child element="ssn"/>
<child element="opaque"/>
</selection>
</sequence>
</element>
<element name="key"
content="string"/>
<element name="ssn"
content="string"/>
<element name="opaque"
wild="True">
content="BIMODAL">
<targetClass>com.jxml.quick.QDOMEleImpl</targetClass>
<attribute name="#ANY"
class="com.jxml.quick.access.QDOMAttAccess">
<targetClass>com.jxml.quick.QDOMAtt</targetClass>
</attribute>
<child element="opaque"
optional="True"
repeating="True"
listProperty="QElements"/>
</element>
</qjml>
Here we see a QJML schema for a MAP markup language. When a map document is parsed, Quick builds an ArrayList object. The ArrayList will always have an even number of entries, the odd entries being Strings created from the key elements. When the even entry is a String, the input was a ssn element; otherwise the even entry will be an instance of the QDOMEleImpl class.
Attributes
The label attribute is used to uniquely identify the sequence element, allowing the same sequence element to be reused in another content model.
This attribute is optional.
The optional and repeating attributes are used to control the number of allowed occurances of the sequence specified by the child, selection, sequence, and cref elements contained in the sequence element:
| optional | repeating | Number of Occurances |
| True | True | Zero or more |
| False | False | Exactly one |
| True | False | No more than one |
| False | True | One or more |
These attributes both default to False when not present.
class, listField, and listProperty
These attributes are used to define the connection between an object bound to the element being defined and an object bound to a child element:
class
The class attribute names a class used to connect the child element object(s) to its parent object. This class must implement the QAccess interface.
listField
The listField attribute names a public field in the class bound to the parent element. This field must be defined as a reference to java.util.List, or as a reference to a class derived from List.
listProperty
The listProperty attribute names a JavaBean property on the class bound to the parent element. The get method defining the property must be present and public, and must return a List (or a class which implements List).
(The put method for the property, if present, is ignored.)
No more than one of these attributes should be specified on a sequence element.
These attributes are optional.
Content Model
The child, selection, sequence, and cref elements are used to specify a series of content models.
These elements are optional, repeatable, and can occur in any order, so long as there is at least one child, selection, sequence, or cref, element present in the sequence element content.
|
The cref element is used to reference a child, selection, or sequence element used in the definition of another element.
Attributes: none
Content Model
The content of a cref element is the label of the child, selection, or sequence element being referenced.