Welcome to JaxMe!

- A Framework for Java/XML binding based on SAX2 -

JaxME General Reference

The following reference sections are available:

Generator Command Line Reference
Default definitions
Element definitions
- Simple element types

Available Managers

The JDBC Manager
The Tamino Manager
The xml:db Manager

Generator Command Line Reference

The JaxMe generator is started by running the following command:

        java -cp jaxme.jar;crimson.jar de.ispsoft.jaxme.generator.Main
          <inputfile> [<options>]

The generator will read the input file by passing it to a SchemaReader. After reading the schema, one or more SourceWriters may be called to create Java sources or other derived files. Possible options are:

Option name Description

--schemaReader=<class>

Defines the SchemaReader that reads the input file. Must be a class implementing SchemaReader. Currently available SchemaReaders are

`XsdSchemaReader`	The default SchemaReader. Reads an XML Schema file.
`XsdJdbcSchemaReader`	A subclass of the XsdSchemaReader that can read parts of the schema from one or more tables via JDBC.
`--sourceWriter=<class>`	Defines a SourceWriter that is called for generating output files. This option may be specified multiple times. By default no SourceWriter is set and the input file is only parsed. Must be a class implementing `SourceWriter`.

Currently available SourceWriters are

JavaSourceWriter

The minimal SourceWriter for generating Java sources. Generates a subclass of JMAnyElement and a SAX2 ContentHandler that can parse XML instances of the given document type. This SchemaReader supports the following options:

xsdschemareader.package	Declares the package in which to place the generated sources. Takes precedence over `xs:annotation/xs:appinfo/jm:package`, which has the same functionality.
xsdschemareader.extends	Declares the class which the generated JaxMe objects are extending. Must be a subclass of JMAnyElement, which is the default. This option takes precedence over `xs:annotation/xs:appinfo/jm:extends`, which has the same functionality.
xsdschemareader.accessors	Declares whether the generated XML objects shall use accessor methods or not. Defaults to true. This option takes precedence over `xs:annotation/xs:appinfo/jm:accessors`, which has the same functionality.

JdbcJavaSourceWriter A subclass of JavaSourceWriter that creates an additional subclass of JMJdbcManager, if the SchemaReader was XsdJdbcSchemaReader. This manager is used to read data from or write to a relational table via JDBC.

BeanWriter

Generates EJB (Enterprise Java Beans) entity beans with BMP (Bean Managed Persistence). The BeanWriter recognizes the following options:

declaredRemoteClassName	If you do not want to use the generated remote interface, but some interface extending it, then the generated home interface has to be changed. This option configures your manually derived subclass.
declaredHomeClassName	Likewise, for the home interface
declaredBeanClassName	Likewise, for the bean implementation class
implDeclaresRemoteException	By default the generated bean method implementations will declare to throw a RemoteException. This option may be used to turn the declaration off.
ejb11compatible	By default the BeanWriter generates sources according to the EJB 2.0 specification. If you set this option to true, then the generated sources will conform to EJB 1.1.

XsdSchemaWriter This SchemaWriter saves an XML Schema that has previously been read. This is most useful, if you want to convert other schema formats into XML Schema. For example, you might want to read a DTD with the DtdReader and then save it with the XsdSchemaWriter.

SampleWriter

Generates sample instances matching the schema. We use this to create a base document that allows XSLT authors to start from the scratch without waiting for the actual logic being implemented. The SampleWriter recognizes the following options:

sampleNumElements	Declares the number of sample instances being generated, defaults to 1.
sampleRootElement	If you are using the option sampleNumElements with a value of 2 or more, the generated documents aren't well formed, because they have multiple root nodes. You may arrange well formedness by adding a special root node. This option declares the root nodes name.

ComparatorWriter Creates an instance of ComparatorFactory, that returns an instance of java.util.Comparator, given an element or attribute name. The Comparator can be used for sorting XML documents by values of one child element or attribute.
The ComparatorWriter takes two options: comparatorPackageName, the name of the Java package, in which the generated ComparatorFactory should reside (defaults to the same package, than the genereted instance of JMAnyElement) and comparatorClassName, the class name (defaults to <doctype>Comparator, where <doctype> is the name of the generated instance of JMAnyElement).

DebugWriter Doesn't generate any files, but displays the schema tree on System.out. Useful for debugging the SchemaReader only.

--logLevel=<level> Sets a Log4J log level. Typical values are debug, info or error (default).

--logFile=<filename> Used to redirect logging output to the given file. By default logging occurrs to System.out.

--option=<name=value>
--option=<name=target=value> Sets a SchemaReader or SourceWriter option with the given name to the specified value. If the target is omitted, then the option is set for all readers and writers that support it. If a target is specified, then it is only set for those readers or writers, that are an instance of the given target class.

--sourceDirectory=<dir> By default the SourceWriter creates files in the current directory or in a subdirectory. This option selects another directory.

Default definitions

JaxMe allows to specifiy various defaults in the element xs:schema/xs:annotation/xs:appinfo/jm:defaults. This defaults overwrite builtin defaults, but may again be overwritten in xs:schema/xs:element/xs:annotation/xs:appinfo/jm:type. The following attributes of an element defaults in namespace http://ispsoft.de/namespaces/jaxme/schema are recognized by the XsdSchemaReader and its subclasses:

Attribute name Description

package Specifies the Java package, in which the generated sources should live. As a consequence, the files are generated in the respective subdirectory. By default the root package is choosen. Can also be specified on the command line with the option xsdschemareader.package.

extends Specifies the superclass of the generated element classes. Must be a subclass of JMAnyElement (default). Can also be specified on the command line with the option xsdschemareader.extends.

accessors By default, child elements and attributes are mapped as public instance variables. Setting this attribute to true makes the instance variables private and causes the generation of public getXXX() and setXXX() accessors. Can also be specified on the command line with the option xsdschemareader.accessors.

An example may help to understand these details:

        <xs:schema
          xmlns:xs="http://www.w3.org/2001/XMLSchema"
          xmlns:jm="http://ispsoft.de/namespaces/jaxme/schema"
          >
          <xs:annotation>
            <jm:defaults package="com.mycompany.schema"/>
          </xs:annotation>
        </xs:schema>

The XsdJdbcSchemaReader has an own default element in the namespace http://ispsoft.de/namespaces/jaxme/jdbc-mapping which recognizes additional attributes:

Attribute name Description

datasource A JNDI name that can be used to lookup a JDBC DataSource. This datasource name will be used to obtain a database connection where schema definitions can be read from. Takes precedence over the specification of driver and url.
This value can also be set from the command line by setting the option jdbc.datasource.

driver If a database connection cannot be obtained via a JNDI lookup, then you may also specifiy a JDBC driver and a JDBC URL. Used in conjunction with the url attribute. Ignored, if a datasource attribute is present.
This value can also be set from the command line by setting the option jdbc.driver.

url Used in conjunction with the driver attribute. Ignored, if a datasource attribute is present.

user Database user for connecting to the database. Used in conjunction with the password attribute.
This value can also be set from the command line by setting the option jdbc.user.

password Password for connecting to the database. Used in conjunction with the user attribute.
This value can also be set from the command line by setting the option jdbc.password.

usedatasource By default the generated JMManager is extending JMJdbcManager. This means that the specification of a JDBC driver and url are required at runtime to connect to the database. If you set this attribute to true, then the generated JMManager will be extending JMJdbcDataSourceManager and a JNDI name has to be specified at runtime, that is used to lookup a JDBC DataSource. The default depends on the presence of a datasource attribute.

Again, an example may help:

        <xs:schema
          xmlns:xs="http://www.w3.org/2001/XMLSchema"
          xmlns:jdm="http://ispsoft.de/namespaces/jaxme/jdbc-mapping"
          >
          <xs:annotation>
            <jdm:defaults driver="org.hsqldb.jdbcDriver"
              url="jdbc:hsqldb:dbdir"/>
          </xs:annotation>
        </xs:schema>

Additionally the following options are supported:

Name Description

jdbc.driver Same as the driver attribute in the jdm:defaults element

jdbc.datasource Same as the datasource attribute in the jdm:defaults element

jdbc.url Same as the url attribute in the jdm:defaults element

jdbc.user Same as the user attribute in the jdm:defaults element

jdbc.password Same as the password attribute in the jdm:defaults element

jdbc.dbmode This option is not available as an attribute of the jdm:defaults element. There are two possible option values: Generic (default) and Oracle. The latter indicates that the JDBC type java.sql.Types.NUMERIC is handled specially. Depending on the values of precision and scale a mapping is established to types like java.sql.Types.INTEGER and the like.

Element definitions

The default definitions may be overwritten per element in a subelement xs:annotation/xs:appinfo/jm:type (XsdSchemaReader) or xs:annotation/xs:appinfo/jdm:type (XsdJdbcSchemaReader). The same attributes as in the defaults section apply. However, you may use additional attributes. The main difference between the former and the latter is that the default attributes work recursively.

Non-recursive attributes recognized by the XsdSchemaReader are:

Attribute name Description

fieldName By default the generated sources use field names like eSomething (lowercase e, second character upper case) for elements and aSomething for attributes. You may overwrite this with your own field name.
className By default the generated classes are called ClsSomething ("Cls", fourth character upper case). The className attribute overwrites the default.

suppress Setting this attribute to true indicates that the SchemaReader should skip this element and any child elements or attributes.

An example may clarify the above definitions:

      <xs:element name="foo">
        <xs:annotation>
          <xs:appinfo>
            <jm:type fieldName="myFoo" className="Foo"/>
          </xs:appinfo>
        </xs:annotation>
      </xs:element>

In the above example the class name would be Foo rather than ClsFoo. Instances of the class would be named myFoo and not eFoo.

There are also some non-recursive attributes recognized by the XsdSchemaReader and the XsdJdbcSchemaReader. However, they are part of different elements, depending on their use.

Element name Attribute name Description

jm:implements class
interface Specifies a Java interface, that the generated class implements. For example, if you want the handler class MyDocumentHandler to implement the interface java.util.Observable, then you would use <jm:implements class="MyDocumentHandler" interface="java.util.Observable"/>. See implements.xsd for an example and Customizing the generated classes for more details.

jm:validation errorCode By default a generic exception is thrown, if the the elements or attributes validation constraints aren't met. If the errorCode attribute is set, however, then the exception is guaranteed to be an instance of ValidationException with the given error code. The error code must be an integer.

jm:javasource class The body of this element contains a piece of Java code that should be included literally into the generated Java class. For example, to include a method doNothing() into the element class MyDocument, you would use
<jm:javasource class="MyDocument"> public void doNothing() {} </jm:javasource>
See implements.xsd for an example and Customizing the generated classes for more details.

jm:unmarshalling This element is used to configure the default unmarshalling. The default unmarshalling is applied by methods like JMAnyElement.toXML(), or JMAnyElement.toWriter(). Note, that there are alternative methods like JMAnyElement.toXML(NamespaceSupport), that allow alternatives to the default unmarshalling without schema modifications.
Currently the only child elements are the jm:namespace elements, which look like this:
<jm:unmarshalling> <jm:namespace prefix="p1" uri=""/> <jm:namespace prefix="p2" uri="http://ispsoft.de/namespaces/p2"/> </jm:unmarshalling>
By default the unmarshalling process uses the same namespace prefixes, as specified in the schema. The "prefix" and "uri" attributes of the "jm:namespace" elements override these defaults.

jdm:table name If the jdm:table is present in a complex child element, then the elements childs are read from the table or view given by the name attribute. The element structure is assumed to be a sequence. The child types are choosen according to the column types.

keys
If the jdm:table element has an attribute keys, then the attribute is assumed to contain a comma separated list of column names that make up the primary keys of the table. By default the primary keys are read from the JDBC metadata.

By default the generated manager will have standard methods insert(), select(), delete() and update(). You may however specify additional findXXX() methods, that perform certain fixed queries. This is particularly useful in conjunction with the BeanWriter, as the generated beans will have the same findXXX() methods.

These findXXX() methods are specified with a subelement jdm:findMethod. It has the same syntax and semantics that the jdm:listMethod of the JaxMe views has. See jdm:view below.

In particular, a jdm:findMethod element may have subelements jdm:pattern (dynamic queries), jdm:param and jdm:placeholders (placeholders).

A jdm:findMethod element may also have an additional child jdm:description that specifies the methods JavaDoc comment.

jdm:select tables The jdm:select element is valid for top level elements only. It allows to join multiple tables to the top level element, if they are in a 1:1 relation. In that case the tables attribute allows to specify a list of table names and a join condition.
The JMJdbcManager uses the tables attribute to build a SELECT statement: SELECT <fieldlist> FROM <tables> WHERE <condition>. The fieldlist is built from the list of child elements, the table list is taken from the tables attribute and the condition is specified at runtime from the user.

where This is an attribute which you should not use. It is only present, because the syntax a JOIN b ON a.c = b.d doesn't seem to be working with hsqldb. It allows to specify an additional condition for the WHERE clause of a SELECT statement. The above example could be realized by setting tables to a, b and where to a.c = b.d.

jdm:view name
This element can be used to specify a JaxMe view. The view has a name (which isn't currently used, actually) and a set of embedded subelements jdm:listMethod with attributes name (the method name) and query (an SQL select query). Each jdm:listMethod may have zero or more jdm:param subelements with attributes name (Parameter name in the generated Java method) and type (an XML schema type).

If the query is exceeding a single line, you may also use a child element jdm:query instead of the query attribute.

Other supported attributes of jdm:listMethod are minResultSize and maxResultSize. If the latter is set to 1, then the generated method is specified to return a single instance or null and not a collection.

A view query may be dynamic by inserting a pattern like {DynamicPart} into the query. The pattern will be replaced by some special method argument, that you specify with a jdm:pattern child element. This child element must have attributes name (the argument name, for example pValue), match (the part being replaced, for example {DynamicPart}) and samp (a default value being inserted, if the argument is null). The sample is in particular important to build a query at generation time, that allows the XsdJdbcSchemaReader to read a schema.

If a dynamic part includes a variable number of placeholders, you might need to specify an additional array of placeholders. This can be done with a jdm:placeholders child element. The element takes a single argument name, which is again the argument name in the created list method.

Any jdm:listMethod may also have a child element jdm:description that specifies the generated methods JavaDoc comment.

jdm:column name This element establishes a mapping between a column name (given by the attribute name) and the element or attribute with the embedded jdm:column clause. For details see the section on Mapping between column names and elements or attributes.

jdm:join follow This element can be embedded into a reference. It is used to declare that a reference shall be followed by the XsdSchemaReader only, but not by the XsdJdbcSchemaReader. In other words, the referencing element shall inherit the XML structure of the referenced element, but not the mapping to an SQL table. The default value of "follow" is "true", a value of "false" disables the join.

Simple element types

Any element has a type, either simple or complex. Supported simple types are:

Names Java type Description

xs:boolean
jm:Boolean
jm:java.lang.Boolean java.lang.Boolean A boolean value; in the XML document it is represented by either true or false.

xs:byte
jm:Byte
jm:java.lang.Byte java.lang.Byte A byte value between -128 and 127

xs:short
jm:Short
jm:java.lang.Short java.lang.Short A short value between -32768 and 32767

xs:integer
jm:Integer
jm:java.lang.Integer java.lang.Integer A long value between -2^15 and 2^15-1

xs:long
jm:Long
jm:java.lang.Long java.lang.Long A long value between -2^31 and 2^31-1

xs:string
jm:String
jm:java.lang.String java.lang.String Any string; this is the default type.

xs:float
jm:Float
jm:java.lang.Float java.lang.Float A float value

xs:double
jm:Double
jm:java.lang.Double java.lang.Double A double value

xs:dateTime
xs:timeInstant
jm:timeInstant
jm:java.util.Date java.util.Date A timestamp value

jm:autoUpdateDateTime java.util.Date Similar to xs:dateTime. However, it is automatically set to the current time and date if a document is inserted into or updated in the database.

jdm:autoSql Depending on the base type This type allows to specify SQL expressions that are stored as a field value when the element is inserted or updated. For example, you might use this to implement an ID column that is created from a sequence or to have a column that updates its value with any update or insert to the current timestamp.
Unlike other types, this one needs additional configuration in the subelement xs:annotation/xs:appinfo/jdm:autoSql.
Example of an ID column:
<xs:element name="ID" type="jdm:autoSql"> <xs:annotation> <xs:appinfo> <-- The column will be filled from a sequence. --> <jdm:autoSql base="xs:integer" insert="myIdSequence.nextval"> </xs:appinfo> </xs:annotation> </xs:element>
Example of an autoupdate column:
<xs:element name="UpdateTime" type="jdm:autoSql"> <xs:annotation> <xs:appinfo> <-- The column will be filled from a sequence. --> <jdm:autoSql base="xs:dateTime" insert="NOW()" update="NOW()"> </xs:appinfo> </xs:annotation> </xs:element>
For more detailed examples see the file auto.xsd.

In the above table the prefixes xs and jm are used. These prefixes are arbitrary, as long as they match the namespaces http://www.w3.org/2001/XMLSchema and http://ispsoft.de/namespaces/jaxme/schema and are properly declared in the document.

Options

Options can be used to configure the SourceWriters and SchemaReaders. An option is specified in the appinfo node, much similar to the jm:type and jm:defaults nodes. Let's take a look at an example:

      <xs:element name="SomeElement">
        <xs:annotation>
          <xs:appinfo>
            <jm:option
              name="SomeOption"
              value="NothingMore"
              target="de.ispsoft.jaxme.generator.BeanWriter"/>
            <jm:option
              name="SomeOtherOption"
              value="NothingLess"/>
          </xs:appinfo>
        </xs:annotation>
      </xs:element>

As you can see from the example, an option has a name and a value. The value can be omitted to restore the default value.

There is also an attribute called target. Which SchemaReaders and SourceWriters are configured by the option, depends on the target. If a target is missing, all Readers and Writers are configured. Otherwise the target may be an interface or class name and a Reader or Writer is only configured, if it is an instance of the given interface or class.

In the above example the option SomeOtherOption configures any SourceWriter or SchemaReader, but the option SomeOption configures only the BeanWriter and its subclasses.

A SourceWriter or SchemaReader doesn't need to care for options. See the concrete Readers or Writers documentation for recognized options.

User defined types

JaxMe includes a number of builtin types. However, it is possible to extend the list with your own, predefined types. For example:

      <xs:schema
          xmlns:jm="http://ispsoft.de/namespaces/jaxme/schema"
          xmlns:my="http://company.com/namespaces/my">
        <xs:annotation>
          <xs:appinfo>
            <jm:declare type="my:clobType" class="de.ispsoft.jaxme.generator.types.OraClobType$URLEncoded"/>
            <jm:declare type="my:blobType" class="de.ispsoft.jaxme.generator.types.OraBlobType"/>
          </xs:appinfo>
        </xs:annotation>
      </xs:schema>

The example would declare that the type named clobType in the namespace http://company.com/namespaces/my is assigned to the class de.ispsoft.jaxme.generator.types.OraClobType$URLEncoded. Likewise, the type blobType in the same namespace is assigned to de.ispsoft.jaxme.generator.types.OraClobType.

Available Managers

Depending on your type of database, you need a different Manager. Available Managers are JMJdbcManager, the Manager for accessing an SQL database through JDBC, the Tamino Manager for using a Tamino native XML database and the XmlDbManager for other XML databases through the xml:db API.

Welcome to JaxMe!

- A Framework for Java/XML binding based on SAX2 -

JaxME General Reference

Generator Command Line Reference

Default definitions

Element definitions

Simple element types

Options

User defined types

Available Managers

The JDBC Manager

The Tamino Manager

The xml:db Manager