msv.tahiti.doc.UsersGuide.docbook Maven / Gradle / Ivy

$Id: UsersGuide.docbook 935 2001-07-21 02:41:41Z Bear $ Tahiti User's Guide KAWAGUCHI Kohsuke

2001 Sun Microsystems Sun internal use only. This document describes the general usage of Tahiti.

Getting Started First, you need a grammar. Tahiti supports various schema language, but let's assume you have "foo.rng" file as your grammar. Then the first thing you should do is to run the schema compiler. java -jar tahiti.jar foo.rng]]> Schema compiler will generate Java source codes to the current directory. If you want it to place those files to another directory, then you can use the -d option like this: java Compiler foo.rng -d ../../src]]> Although the compiler takes every effort to extract a meaningful mapping from the schema, often it falls short of your expectation. If that is the case, you can control the way the compiler maps schemas to Java classes by annotating schema files. The annotation depends on the schema language you use. Consult the documentation for your choice of the schema language. RELAX NG annotation

Using the generated classes This section describes how you can use the genrated Java classes to do what you want. You should know two important operations involving the generated classes. One is marshalling and the other is unmarshalling

Unmarshalling Unmarshalling is the process that reads an XML document and creates the corresponding Java objects. The easiest way to do this is to do as follows: The above method will read the document from the specified location and returns the result. org.example.test.Grammar is the name of the compiled grammar, which is generated by the schema compiler. You should replace it with appropriate class name. There are severl other overloaded version of this method, which accepts various type of inputs like org.xml.sax.InputSource or java.io.InputStream. Should any error happens during the process of unmarshalling, an exception is thrown. See javadoc for details.

Marshalling Marshalling is the process that writes XML representation of the Java object model. The easiest way to do this is to use the MarshallerAPI class. This class lets you produce XML in many ways. There are handful of overloaded versions of the marshall method, each support different type of output. Unfortunately, the implementation of the marshaller is rather poor at this moment. Sometimes, the compiler fails to produce a marshaller for a grammar. If it fails, please let us know so that we invent a better algorithm. Also, there is a workaround. If the compiler fails to produce a marshaller, then you can derive that class and implement it by hand.

Creating objects programatically Unmarshalling is not the only way to construct an object model. Instead, you can programatically create it from scratch, much like you can create a DOM tree from scratch by using the createXXX methods of a org.w3c.dom.Document object.