You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@ws.apache.org by di...@apache.org on 2003/09/23 21:24:43 UTC
cvs commit: ws-site/targets/jaxme/manual apa.html apb.html ch01.html ch01s02.html ch02.html ch02s02.html go01.html index.html pr01.html
dims 2003/09/23 12:24:43
Added: targets/jaxme/manual apa.html apb.html ch01.html
ch01s02.html ch02.html ch02s02.html go01.html
index.html pr01.html
Log:
jaxme website
Revision Changes Path
1.1 ws-site/targets/jaxme/manual/apa.html
Index: apa.html
===================================================================
<html><head><META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Appendix A. License</title><meta content="DocBook XSL Stylesheets V1.62.0" name="generator"><link rel="home" href="index.html" title="The JaxMe 2 manual"><link rel="up" href="index.html" title="The JaxMe 2 manual"><link rel="previous" href="ch02s02.html" title="Marshalling objects"><link rel="next" href="apb.html" title="Appendix B. FAQ"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table summary="Navigation header" width="100%"><tr><th align="center" colspan="3">Appendix A. License</th></tr><tr><td align="left" width="20%"><a accesskey="p" href="ch02s02.html">Prev</a> </td><th align="center" width="60%"> </th><td align="right" width="20%"> <a accesskey="n" href="apb.html">Next</a></td></tr></table><hr></div><div class="appendix" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="N10583"></a>Appendix A. License</h2></div></div><div></div></div><p>JaxMe comes to you under the terms of the BSD License:</p><p>Copyright (c) 2003, The JaxMe project. All rights reserved.</p><p>Redistribution and use in source and binary forms, with or without modification, are permitted provided
that the following conditions are met:
<div class="orderedlist"><ol type="1"><li>Redistributions of source code must retain the above copyright notice, this list of conditions
and the following disclaimer.</li><li>Redistributions in binary form must reproduce the above copyright notice, this list of conditions
and the following disclaimer in the documentation and/or other materials provided with the distribution.
</li><li>Neither the name of the JaxMe project nor the names of its contributors may be used to endorse or
promote products derived from this software without specific prior written permission.</li></ol></div>
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED
WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY
OF SUCH DAMAGE.
</p></div><div class="navfooter"><hr><table summary="Navigation footer" width="100%"><tr><td align="left" width="40%"><a accesskey="p" href="ch02s02.html">Prev</a> </td><td align="center" width="20%"><a accesskey="u" href="index.html">Up</a></td><td align="right" width="40%"> <a accesskey="n" href="apb.html">Next</a></td></tr><tr><td valign="top" align="left" width="40%">Marshalling objects </td><td align="center" width="20%"><a accesskey="h" href="index.html">Home</a></td><td valign="top" align="right" width="40%"> Appendix B. FAQ</td></tr></table></div></body></html>
1.1 ws-site/targets/jaxme/manual/apb.html
Index: apb.html
===================================================================
<html><head><META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Appendix B. FAQ</title><meta content="DocBook XSL Stylesheets V1.62.0" name="generator"><link rel="home" href="index.html" title="The JaxMe 2 manual"><link rel="up" href="index.html" title="The JaxMe 2 manual"><link rel="previous" href="apa.html" title="Appendix A. License"><link rel="next" href="go01.html" title="Glossary"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table summary="Navigation header" width="100%"><tr><th align="center" colspan="3">Appendix B. FAQ</th></tr><tr><td align="left" width="20%"><a accesskey="p" href="apa.html">Prev</a> </td><th align="center" width="60%"> </th><td align="right" width="20%"> <a accesskey="n" href="go01.html">Next</a></td></tr></table><hr></div><div class="appendix" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="N10596"></a>Appendix B. FAQ</h2></div></div><div></div></div><p>This section contains a list of frequently asked questions. And, of course, their answers. :-)</p><div class="qandaset"><dl><dt>B.1. <a href="apb.html#N1059D">General questions</a></dt><dd><dl><dt>Q: <a href="apb.html#N105A2">What is it?</a></dt><dt>Q: <a href="apb.html#N105A9">Why should I choose JaxMe and not JAXB?</a></dt><dt>Q: <a href="apb.html#N105BE">Why the name "JaxMe"?</a></dt><dt>Q: <a href="apb.html#N105C7">Are there any reference projects?</a></dt></dl></dd><dt>B.2. <a href="apb.html#N105D6">The Generator</a></dt><dd><dl><dt>Q: <a href="apb.html#N105DB">What is the supported subset of XML Schema?</a></dt><dt>Q: <a href="apb.html#N105F8">What is the supported subset of JAXB?</a></dt><dt>Q: <a href="apb.html#N10606">How is the EJB support working?</a></dt><dt>Q: <a href="apb.html#N10611">What are JaxMe's "find methods" and "list methods"?</a></dt><dt>Q: <a href="apb.html#N1061C">Why are the field names uppercased when using the JaxMeJdbcSG?</a></dt></dl></dd><dt>B.3. <a href="apb.html#N10625">The runtime</a></dt><dd><dl><dt>Q: <a href="apb.html#N1062A">How is Tamino supported?</a></dt><dt>Q: <a href="apb.html#N1063A">How is XML:DB supported?</a></dt></dl></dd></dl><table summary="Q and A Set" border="0"><col align="left" width="1%"><tbody><tr class="qandadiv"><td colspan="2" valign="top" align="left"><a name="N1059D"></a><h3 class="title"><a name="N1059D"></a>B.1. General questions</h3></td></tr><tr colspan="2" class="toc"><td colspan="2" valign="top" align="left"><dl><dt>Q: <a href="apb.html#N105A2">What is it?</a></dt><dt>Q: <a href="apb.html#N105A9">Why should I choose JaxMe and not JAXB?</a></dt><dt>Q: <a href="apb.html#N105BE">Why the name "JaxMe"?</a></dt><dt>Q: <a href="apb.html#N105C7">Are there any reference projects?</a></dt></dl></td></tr><tr colspan="2" class="toc"><td colspan="2" valign="top" align="left"><p>This subsection contains questions concerning the whole project as such.</p></td></tr><tr class="question"><td valign="top" align="left"><a name="N105A2"></a><a name="N105A3"></a><b>Q:</b></td><td valign="top" align="left"><p>What is it?</p></td></tr><tr class="answer"><td valign="top" align="left"><b>A:</b></td><td valign="top" align="left"><p>
JaxMe 2 is an implementation of JAXB, the specification for Java/XML binding. In short you can
describe JaxMe as a source generator that takes various sources as input (for example, an XML schema,
a DTD, a Java bean class) and creates sources that allow you to convert a matching XML document into
a Java object or vice versa, convert the Java object into XML. JaxMe extends JAXB with a lot of features.
See the next question on that topic.</p></td></tr><tr class="question"><td valign="top" align="left"><a name="N105A9"></a><a name="N105AA"></a><b>Q:</b></td><td valign="top" align="left"><p>Why should I choose JaxMe and not JAXB?</p></td></tr><tr class="answer"><td valign="top" align="left"><b>A:</b></td><td valign="top" align="left"><p>That's definitely a question you should ask yourself. The JAXB reference implementation is
implemented by a team of excellent technicians who have a vision. It is supported by Sun and other
large vendors.</p><p>On the other hand, you should understand that JAXB has a limited scope. As a reference
implementation, it has to follow the specification, but can hardly do a step beyond. And in
some sense the scope can be described as the lowest common denominator of Sun and the other
vendors. JaxMe is (at least as of this writing) definitely less tested, less stable, less
mature and all that stuff you don't want. On the other hand, it has some nice features which
you possibly really want:
<div class="orderedlist"><ol type="1"><li>JaxMe is much, much more extensible and customizable than JAXB: It was written
from the ground up for that. And you have the source. The main problem of source generators
has always been whether you have the source or not. If you do, then a source generator can
do everything for you that you want and become really, really useful, grow with your
abilities and the project. On the other hand, without the source you will almost definitely
at some point ask yourself why you didn't implement all the stuff manually.</li><li><p>It includes a persistency layer. The persistency layer is a database abstraction
and allows you to read XML from a database or store it into the database with just a few
instructions. You do not care for the hazzle of low level API's like xml:db or JDBC, you
just say "save it" and it does. The most important advantage of a persistency framework
is that you become more independent from the database. With JaxMe 1 projects have been
developed on an SQL database, for example MySQL and later on moved to Tamino, an XML
database. It also happened vice versa, where it makes sense.</p><p>Even more, you aren't restricted to a single database. You can mix data sources,
depending on the document type, and choose for any document type whichever suites the
most.</p></li><li>We definitely recommend the use of an XML database. After all, why not use the
features that XML gives you? Normalization definitely has its goods and should still be
applied where it makes sense. However, in the real life, this is not always the case.
Besides, some of us (in particular the developers) are still stuck in the relational world.
JaxMe can create a mapping between Java objects and SQL databases for you. The persistency
layer translates "create", "update", "delete" or "read" operations into a set of SQL
instructions. These SQL instructions are performed by JaxMe on your demand. There is almost
no difference (besides the structural limitations, of course) between working with an SQL
database and an XML database.</li></ol></div></p></td></tr><tr class="question"><td valign="top" align="left"><a name="N105BE"></a><a name="N105BF"></a><b>Q:</b></td><td valign="top" align="left"><p>Why the name "JaxMe"?</p></td></tr><tr class="answer"><td valign="top" align="left"><b>A:</b></td><td valign="top" align="left"><p>After working with JAXP, JAXB, JAXM and all the other stuff for quite some time I began to
automatically associate "JAXsomethingE" with anything related to Java and XML. So this is "Me"
JAX or JaxMe.</p><p>The name is ridiculous. I know. Sometimes we'll probably find something better. (And, who
knows, perhaps we even find someone changing the sources then ... :-)</p></td></tr><tr class="question"><td valign="top" align="left"><a name="N105C7"></a><a name="N105C8"></a><b>Q:</b></td><td valign="top" align="left"><p>Are there any reference projects?</p></td></tr><tr class="answer"><td valign="top" align="left"><b>A:</b></td><td valign="top" align="left"><p>As of this writing, JaxMe 2 isn't sufficiently mature for large projects.
However, JaxMe 1 has been used for really serious issues:
<div class="itemizedlist"><ul type="disc"><li>FleetBoard (http://www.fleetboard.com/) is a telematics and logistics solution.
Large parts of it are realized with the JaxMe EJB generator and a DB2 database as the
backend. Other parts are based on a JaxMe predecessor and Tamino.</li><li>Justus II (http://www.softwareag.com/germany/referenzen/PDF/CR_Justus_D.pdf) is
a large XML application running on Tomcat and an Oracle database as the backend. It is
built from the ground up using JaxMe.</li></ul></div>
</p><p>If you know of other projects, please let us know.</p></td></tr><tr class="qandadiv"><td colspan="2" valign="top" align="left"><a name="N105D6"></a><h3 class="title"><a name="N105D6"></a>B.2. The Generator</h3></td></tr><tr colspan="2" class="toc"><td colspan="2" valign="top" align="left"><dl><dt>Q: <a href="apb.html#N105DB">What is the supported subset of XML Schema?</a></dt><dt>Q: <a href="apb.html#N105F8">What is the supported subset of JAXB?</a></dt><dt>Q: <a href="apb.html#N10606">How is the EJB support working?</a></dt><dt>Q: <a href="apb.html#N10611">What are JaxMe's "find methods" and "list methods"?</a></dt><dt>Q: <a href="apb.html#N1061C">Why are the field names uppercased when using the JaxMeJdbcSG?</a></dt></dl></td></tr><tr colspan="2" class="toc"><td colspan="2" valign="top" align="left"><p>The following questions are related to the JaxMe generator</p></td></tr><tr class="question"><td valign="top" align="left"><a name="N105DB"></a><a name="N105DC"></a><b>Q:</b></td><td valign="top" align="left"><p>What is the supported subset of XML Schema?</p></td></tr><tr class="answer"><td valign="top" align="left"><b>A:</b></td><td valign="top" align="left"><p>As of this writing, the following is supported:
<div class="itemizedlist"><ul type="disc"><li>All simple datatypes, excluding time intervals (minor issue, some hours work,
if anyone needs it)</li><li>Atomic elements, with and without attributes</li><li>Complex elements with content type empty, sequence, choice, or all.</li><li>Groups (but not nested groups)</li></ul></div></p><p>The following is not yet supported:
<div class="itemizedlist"><ul type="disc"><li>Complex elements with simple content (minor issue, mainly requires writing a
test suite)</li><li>Mixed content</li><li>Wildcards</li><li>Key specifications</li><li>Recursion (Minor issue, mainly requires writing a test suite)</li></ul></div></p></td></tr><tr class="question"><td valign="top" align="left"><a name="N105F8"></a><a name="N105F9"></a><b>Q:</b></td><td valign="top" align="left"><p>What is the supported subset of JAXB?</p></td></tr><tr class="answer"><td valign="top" align="left"><b>A:</b></td><td valign="top" align="left"><p>Lots of features are missing, in particular:
<div class="itemizedlist"><ul type="disc"><li>External schema binding (requires writing a stylesheet generator)</li><li>Model group binding</li><li>Mixed content</li></ul></div></p></td></tr><tr class="question"><td valign="top" align="left"><a name="N10606"></a><a name="N10607"></a><b>Q:</b></td><td valign="top" align="left"><p>How is the EJB support working?</p></td></tr><tr class="answer"><td valign="top" align="left"><b>A:</b></td><td valign="top" align="left"><p>As of this writing, the following applies for JaxMe 1 only.
EJB support is not yet included in JaxMe 2. This will hopefully change soon.</p><p>JaxMe 1 contains a generator for entity beans with bean managed persistence.
In short these can very well be compared with CMP entity beans, only you use JaxMe
to create it and the query language is unavailable. On the other hand, they are
typically faster, because they follow the design pattern of value objects.</p><p>The bean generator also supports the generation of stateless session beans that perform
queries and return XML data. (So called list methods.)</p></td></tr><tr class="question"><td valign="top" align="left"><a name="N10611"></a><a name="N10612"></a><b>Q:</b></td><td valign="top" align="left"><p>What are JaxMe's "find methods" and "list methods"?</p></td></tr><tr class="answer"><td valign="top" align="left"><b>A:</b></td><td valign="top" align="left"><p>As of this writing, the following applies for JaxMe 1 only.
EJB support is not yet included in JaxMe 2. This will hopefully change soon.</p><p>You know what an SQL view is? Forgetting updateable views, one could describe them as a
stored query, that returns some data in a fixed format. In essence this is what JaxMe's find
and list methods are: You specify a query that is compiled by the source code generator. The
result are Java sources that can perform the specified query, possibly configured with some
parameters that you specify as well.</p><p>The difference between find and list methods is that the former return objects which you
may modify and store back. So find methods are somewhat closer to updateable views, because
they are bound to a specific table.</p></td></tr><tr class="question"><td valign="top" align="left"><a name="N1061C"></a><a name="N1061D"></a><b>Q:</b></td><td valign="top" align="left"><p>Why are the field names uppercased when using the JaxMeJdbcSG?</p></td></tr><tr class="answer"><td valign="top" align="left"><b>A:</b></td><td valign="top" align="left"><p>Field names are built from column names, which are in turn read via JDBC metadata.
However, most databases are storing column names uppercased internally.</p><p>As a workaround, you may specify an alternative field name. See the IPADDRESS column
in the Session example for how to do that.</p></td></tr><tr class="qandadiv"><td colspan="2" valign="top" align="left"><a name="N10625"></a><h3 class="title"><a name="N10625"></a>B.3. The runtime</h3></td></tr><tr colspan="2" class="toc"><td colspan="2" valign="top" align="left"><dl><dt>Q: <a href="apb.html#N1062A">How is Tamino supported?</a></dt><dt>Q: <a href="apb.html#N1063A">How is XML:DB supported?</a></dt></dl></td></tr><tr colspan="2" class="toc"><td colspan="2" valign="top" align="left"><p>The following questions are related to the JaxMe runtime.</p></td></tr><tr class="question"><td valign="top" align="left"><a name="N1062A"></a><a name="N1062B"></a><b>Q:</b></td><td valign="top" align="left"><p>How is Tamino supported?</p></td></tr><tr class="answer"><td valign="top" align="left"><b>A:</b></td><td valign="top" align="left"><p>Software AG, the vendor of Tamino, is the employer of Jochen Wiedmann (JaxMe's head
developer). Jochen uses Tamino in his daily work, so support for Tamino is essential. He
considers work with Tamino as definitely much more fun than using DB2, Oracle, or
whatsoever.</p><p>The current Tamino manager is a simple thing implementing native HTTP access to Tamino.
It is a generic manager, not a specific manager per document type. (Working with XML databases
is much simpler for an XML application than using JDBC.) However, the following is not yet
supported, although it really should:
<div class="itemizedlist"><ul type="disc"><li>Tamino transactions</li><li>Find and list methods (truly important for the XQuery language)</li><li>Use of the official TaminoAPI4J (the current manager is based on a simple SAX handler)</li></ul></div></p></td></tr><tr class="question"><td valign="top" align="left"><a name="N1063A"></a><a name="N1063B"></a><b>Q:</b></td><td valign="top" align="left"><p>How is XML:DB supported?</p></td></tr><tr class="answer"><td valign="top" align="left"><b>A:</b></td><td valign="top" align="left"><p>There is a generic XmlDbManager, which is tested in a JUnit test against eXist. It
is a generic manager, not a specific manager per document type. (Working with XML databases
is much simpler for an XML application than using JDBC.) However, so far no productive use
is known.</p></td></tr></tbody></table></div></div><div class="navfooter"><hr><table summary="Navigation footer" width="100%"><tr><td align="left" width="40%"><a accesskey="p" href="apa.html">Prev</a> </td><td align="center" width="20%"><a accesskey="u" href="index.html">Up</a></td><td align="right" width="40%"> <a accesskey="n" href="go01.html">Next</a></td></tr><tr><td valign="top" align="left" width="40%">Appendix A. License </td><td align="center" width="20%"><a accesskey="h" href="index.html">Home</a></td><td valign="top" align="right" width="40%"> Glossary</td></tr></table></div></body></html>
1.1 ws-site/targets/jaxme/manual/ch01.html
Index: ch01.html
===================================================================
<html><head><META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Chapter 1. First steps</title><meta content="DocBook XSL Stylesheets V1.62.0" name="generator"><link rel="home" href="index.html" title="The JaxMe 2 manual"><link rel="up" href="index.html" title="The JaxMe 2 manual"><link rel="previous" href="pr01.html" title="Introduction"><link rel="next" href="ch01s02.html" title="Working with XML"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table summary="Navigation header" width="100%"><tr><th align="center" colspan="3">Chapter 1. First steps</th></tr><tr><td align="left" width="20%"><a accesskey="p" href="pr01.html">Prev</a> </td><th align="center" width="60%"> </th><td align="right" width="20%"> <a accesskey="n" href="ch01s02.html">Next</a></td></tr></table><hr></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="N10023"></a>Chapter 1. First steps</h2></div></div><div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="ch01.html#N10035">Generating Java code</a></span></dt><dd><dl><dt><span class="sect2"><a href="ch01.html#N1003A">Creating a JaxMe schema</a></span></dt><dt><span class="sect2"><a href="ch01.html#N1004D">Running the generator</a></span></dt></dl></dd><dt><span class="sect1"><a href="ch01s02.html">Working with XML</a></span></dt><dd><dl><dt><span class="sect2"><a href="ch01s02.html#N10118">Writing XML documents</a></span></dt><dt><span class="sect2"><a href="ch01s02.html#N10149">Reading XML</a></span></dt></dl></dd></dl></div><p>This chapter introduces the first steps of using JaxMe. In what follows,
we will create some simple examples. All examples deal with addresses,
stored in XML documents like the following, quoted from the file
<tt class="filename">examples/misc/address.xml</tt> in the JaxMe 2 distribution:
<pre class="programlisting">
<?xml version="1.0"?>
<!-- A sample document for the Address.xsd schema. This
sample document is used in the docs, see
docs/GenerateJava.html. -->
<Address xmlns="http://ws.apache.org/jaxme/examples/misc/address">
<Name>
<First>Jane</First>
<Middle>Lee</Middle>
<Middle>Chris</Middle>
<Last>Doe</Last>
<Initials>(JD)</Initials>
</Name>
... further details omitted for brevity ...
</Address>
</pre>
</p><p>Our target is to convert this into convenient Java code, much like the
following:
<pre class="programlisting">
Address address = new Address();
Name name = new Name();
address.setName(name);
name.setFirst("Jane");
name.addMiddle("Lee");
name.addMiddle("Chris");
name.setSur("Doe");
name.setInitials("JD");
...
</pre></p><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="N10035"></a>Generating Java code</h2></div></div><div></div></div><p>After you've downloaded JaxMe, you're ready to use it. In this section
we will demonstrate how to generate sources.</p><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N1003A"></a>Creating a JaxMe schema</h3></div></div><div></div></div><p>With the address example in mind, we create the XML Schema. The schema can
be regarded as a description of compliant document instances, in our case
addresses. For example like this, quoting the file
<tt class="filename">examples/misc/address.xsd</tt> in the JaxMe 2 distribution:
<pre class="programlisting">
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema
xmlns:xs="http://www.w3.org/2001/XMLSchema"
xml:lang="EN"
targetNamespace="http://ws.apache.org/jaxme/examples/misc/address"
elementFormDefault="qualified"
attributeFormDefault="unqualified">
<xs:element name="Address">
<xs:complexType>
<xs:sequence>
<xs:element name="Name">
<xs:annotation><xs:documentation>
A name consists of two required (first and last name)
and two optional parts (middle name and initials).
</xs:documentation></xs:annotation>
<xs:complexType>
<xs:sequence>
<xs:element name="First" type="xs:string"/>
<xs:element name="Middle" type="xs:string" minOccurs="0" maxOccurs="unbounded"/>
<xs:element name="Last" type="xs:string"/>
<xs:element name="Initials" minOccurs="0" type="xs:string"/>
</xs:sequence>
</xs:complexType>
</xs:element>
... further details omitted for brevity ...
</xs:sequence>
<xs:attribute name="id"/>
</xs:complexType>
</xs:element>
</xs:schema>
</pre>
You will easily note that <span class="token">xs:element</span> is used to define elements.
An attribute is added using <span class="token">xs:attribute</span>, and so on.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N1004D"></a>Running the generator</h3></div></div><div></div></div><p>The easiest way to run the generator is by invoking an Ant task. Here's how
this might look like:
<pre class="programlisting">
<target name="taskdef">
<path id="generate.class.path">
<pathelement location="jaxme.jar"/>
<pathelement location="jaxmejs.jar"/>
<pathelement location="jaxmexs.jar"/>
<pathelement location="jaxb-api.jar"/>
<pathelement location="jax-qname.jar"/>
<pathelement location="namespace.jar"/>
</path>
<taskdef name="xjc"
classname="org.apache.ws.jaxme.generator.XJCTask"
classpathref="generate.class.path"/>
<xjc schema="examples/misc/address.xsd" target="build/src">
<produces includes="org/apache/ws/jaxme/examples/misc/address/*.java"/>
</xjc>
</target>
</pre></p><p>The example demonstrates how a classpath called <span class="token">generate.class.path</span> is
created. The class path is used, when a new ant task called "xjc" is created. In what follows
the new task is used to compile a schema file called <tt class="filename">examples/misc/address.xsd</tt>.
The generated sources will reside in the directory <tt class="filename">build/src</tt>. The target
package is <span class="token">org.apache.ws.jaxme.examples.misc.address</span>, hence the effective location is
<tt class="filename">build/src/org/apache/ws/jaxme/examples/misc/address</tt>.</p><p>Looking into that directory, we find that the following files have been created:
<div class="variablelist"><p class="title"><b>Files generated by the JaxMe binding compiler</b></p><dl><dt><span class="term"><tt class="filename">Address.java</tt></span></dt><dd><p>Contains the Java interface describing the document type
<span class="token">Address</span>. This interface is extending the interface
specified by <tt class="filename">AddressType.java</tt>.</p></dd><dt><span class="term"><tt class="filename">AddressType.java</tt></span></dt><dd><p>Contains the Java interface describing the inner contents
of the document type <span class="token">Address</span>. The best way to think of it is
to assume that they are the same, except that the latter is anonymous and
doesn't have an element name.</p></dd><dt><span class="term"><tt class="filename">Configuration.xml</tt></span></dt><dd><p>This file is used by the JaxMe runtime internally. Typically
you'll never notice that it is even there. The main task of the file is a mapping
between XML element names (like <span class="token">Address</span> in namespace
<span class="token">http://ws.apache.org/jaxme/examples/misc/address</span>) and Java classes.</p><div class="tip" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Tip</h3><p>In theory you are able to replace the implementations generated by
<span class="application">JaxMe</span>
with your own classes. This is particularly useful, if you want to modify a certain
behaviour by deriving a subclass.</p></div></dd><dt><span class="term"><tt class="filename">jaxb.properties</tt></span></dt><dd><p>This file is used by the <span class="acronym">JAXB</span> properties. Typically you'll
never notive that it is even there. The task of the file is to ensure that
the <span class="acronym">JAXB</span> runtime is to make sure that the <span class="application">JaxMe</span>
runtime is properly initialized.</p></dd><dt><span class="term"><tt class="filename">impl/AddressHandler.java</tt></span></dt><dd><p>A <span class="acronym">SAX2</span> <tt class="classname">ContentHandler</tt>, which can
convert XML documents of type <span class="token">Address</span> into instances of the Java
interface <tt class="classname">Address</tt>. You'll rarely need it, because it is
created and invoked automatically by the <span class="acronym">JAXB</span>
<tt class="classname">Marshaller</tt>.</p></dd><dt><span class="term"><tt class="filename">impl/AddressImpl.java</tt></span></dt><dd><p>Default Implementation of the <tt class="classname">Address</tt> interface.</p></dd><dt><span class="term"><tt class="filename">impl/AddressType.java</tt></span></dt><dd><p>Default Implementation of the <tt class="classname">AddressType</tt>
interface.</p></dd><dt><span class="term"><tt class="filename">impl/AddressTypeHandler.java</tt></span></dt><dd><p>Similar to its subclass <tt class="classname">AddressHandler</tt>,
this is a <span class="acronym">SAX2</span> <tt class="classname">ContentHandler</tt> for reading
instances of <tt class="classname">AddressType</tt>. The
main difference to the subclass is that the subclass doesn't have a fixed
element name.</p></dd><dt><span class="term"><tt class="filename">impl/AddressTypeImpl.java</tt></span></dt><dd><p>Default implementation of <tt class="classname">AddressType</tt>.</p></dd><dt><span class="term"><tt class="filename">impl/AddressTypeSerializer.java</tt></span></dt><dd><p>This class is able to convert instances of <tt class="classname">AddressType</tt>
into XML documents. It is also used to convert instances of <tt class="classname">Address</tt>.</p></dd></dl></div>
</p></div></div></div><div class="navfooter"><hr><table summary="Navigation footer" width="100%"><tr><td align="left" width="40%"><a accesskey="p" href="pr01.html">Prev</a> </td><td align="center" width="20%"><a accesskey="u" href="index.html">Up</a></td><td align="right" width="40%"> <a accesskey="n" href="ch01s02.html">Next</a></td></tr><tr><td valign="top" align="left" width="40%">Introduction </td><td align="center" width="20%"><a accesskey="h" href="index.html">Home</a></td><td valign="top" align="right" width="40%"> Working with XML</td></tr></table></div></body></html>
1.1 ws-site/targets/jaxme/manual/ch01s02.html
Index: ch01s02.html
===================================================================
<html><head><META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Working with XML</title><meta content="DocBook XSL Stylesheets V1.62.0" name="generator"><link rel="home" href="index.html" title="The JaxMe 2 manual"><link rel="up" href="ch01.html" title="Chapter 1. First steps"><link rel="previous" href="ch01.html" title="Chapter 1. First steps"><link rel="next" href="ch02.html" title="Chapter 2. Reference"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table summary="Navigation header" width="100%"><tr><th align="center" colspan="3">Working with XML</th></tr><tr><td align="left" width="20%"><a accesskey="p" href="ch01.html">Prev</a> </td><th align="center" width="60%">Chapter 1. First steps</th><td align="right" width="20%"> <a accesskey="n" href="ch02.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="N1010D"></a>Working with XML</h2></div></div><div></div></div><p>In this section we'll show how to create XML. XML (or better an XML document) exists in various
flavours: You might want to have it serialized into a String. Sometimes you may prefer character or
byte streams, aka instances of <tt class="classname">Writer</tt> or <tt class="classname">OutputStream</tt>.
In other cases you will prefer a DOM representation. The main things of interest are: How to I
create a serialized XML document (a String, a character or byte stream)? And, vice versa, how
do I read such a document and convert it back into Java objects?</p><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N10118"></a>Writing XML documents</h3></div></div><div></div></div><p>In the case of JaxMe you'll have simple Java beans. An address is created by instantiating
a class <tt class="classname">AddressImpl</tt>, which is implementing an interface <tt class="classname">Address</tt>.
For example:
<pre class="programlisting">
import java.io.FileWriter;
import java.io.Writer;
import javax.xml.bind.JAXBContext;
import javax.xml.bind.JAXBException;
import javax.xml.bind.Marshaller;
import org.apache.ws.jaxme.examples.misc.address.Address;
import org.apache.ws.jaxme.examples.misc.address.AddressType.EmailDetailsType.EmailType;
import org.apache.ws.jaxme.examples.misc.address.AddressType.PhoneDetailsType.PhoneType;
import org.apache.ws.jaxme.examples.misc.address.impl.AddressImpl;
import org.apache.ws.jaxme.examples.misc.address.impl.AddressTypeImpl.EmailDetailsTypeImpl;
import org.apache.ws.jaxme.examples.misc.address.impl.AddressTypeImpl.EmailDetailsTypeImpl.EmailTypeImpl;
import org.apache.ws.jaxme.examples.misc.address.impl.AddressTypeImpl.PhoneDetailsTypeImpl;
import org.apache.ws.jaxme.examples.misc.address.impl.AddressTypeImpl.PhoneDetailsTypeImpl.PhoneTypeImpl;
import org.apache.ws.jaxme.examples.misc.address.impl.AddressTypeImpl.NameTypeImpl;
import org.apache.ws.jaxme.examples.misc.address.impl.AddressTypeImpl.PostalTypeImpl;
public class AddressCreator {
public static void writeAddress(Writer pWriter) throws JAXBException {
// Create the element:
Address addr = new AddressImpl();
addr.setName(new NameTypeImpl());
addr.getName().setFirst("Jane");
addr.getName().setLast("Doe");
addr.setPostal(new PostalTypeImpl());
addr.getPostal().setStreet("34 Main Street");
addr.getPostal().setCity("Boston");
addr.getPostal().setState("MA");
addr.getPostal().setZIP("02215");
addr.setEmailDetails(new EmailDetailsTypeImpl());
/* Lots of similar lines omitted for brevity ...
* ...
*/
// And save it into the file "Address.xml"
JAXBContext context = JAXBContext.newInstance("org.apache.ws.jaxme.examples.misc.address");
Marshaller marshaller = context.createMarshaller();
marshaller.marshal(addr, pWriter);
}
public static void main(String[] args) throws Exception {
FileWriter fw = new FileWriter("Address.xml");
writeAddress(fw);
fw.close();
}
}
</pre>
The example is quoted from the file
<tt class="filename">src/java/org/apache/ws/jaxme/examples/misc/address/AddressCreator.java</tt>,
which comes to you as part of the JaxMe distribution.
</p><p>There are several things you should note here:
<div class="itemizedlist"><ul type="disc"><li>The class and property names are obviously taken from element and
attribute names.</li><li>Although the <span class="token">Address</span> document uses namespaces, attributes,
and child elements, the example requires by no means knowledge of XML. For example,
you do not need to care for character escaping.</li><li>Complex child elements are java beans themselves, like the <span class="token">Address</span>
element. For example, the <span class="token">Name</span> element has to be instantiated
</li><li>To convert the object into an XML string, the <tt class="classname">JAXBContext</tt>
and <tt class="classname">Marshaller</tt> are used. These are objects specified by the
<span class="acronym">JAXB</span> specification. The example uses no JaxMe specific
features and should in practice run with any JAXB implementation.</li></ul></div>
</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N10149"></a>Reading XML</h3></div></div><div></div></div><p>The example on writing XML was surprisingly simple. In fact, the only
nasty part was creating the object, which requires invocation of lots of
setters and getters. Quite opposed to the marshalling, which took place in
three lines. And, as we soon will see: Unmarshalling (the process of reading
a document) is by no means more complex.</p><p>To demonstrate the unmarshalling process, we'll quote an example from
the JaxMe distribution again. This time it's the file
<tt class="filename">src/java/org/apache/ws/jaxme/examples/misc/address/AddressPrinter.java</tt>:
<pre class="programlisting">
package org.apache.ws.jaxme.examples.misc.address;
import java.io.File;
import java.io.FileInputStream;
import java.io.StringWriter;
import javax.xml.bind.JAXBContext;
import javax.xml.bind.JAXBException;
import javax.xml.bind.Marshaller;
import javax.xml.bind.Unmarshaller;
import org.apache.ws.jaxme.examples.misc.address.Address;
import org.xml.sax.InputSource;
public class AddressPrinter {
public static Address getAddress(InputSource pSource) throws JAXBException {
JAXBContext context = JAXBContext.newInstance("org.apache.ws.jaxme.examples.misc.address");
Unmarshaller unmarshaller = context.createUnmarshaller();
return (Address) unmarshaller.unmarshal(pSource);
}
public static String getAddressAsString(Address pAddress) throws JAXBException {
StringWriter sw = new StringWriter();
JAXBContext context = JAXBContext.newInstance("org.apache.ws.jaxme.examples.misc.address");
Marshaller marshaller = context.createMarshaller();
marshaller.marshal(pAddress, sw);
return sw.toString();
}
public static void main(String[] args) throws Exception {
File f = new File("Address.xml");
InputSource isource = new InputSource(new FileInputStream(f));
isource.setSystemId(f.toURL().toString());
Address addr = getAddress(isource);
// A simpler variant might be:
// Address addr = unmarshaller.unmarshal(f);
if (addr.getName() == null) {
System.out.println("Loaded address without name.");
} else {
System.out.println("Loaded address " + addr.getName().getLast() +
", " + addr.getName().getFirst() + ".");
}
System.out.println("Details:" + getAddressAsString(addr));
}
}
</pre></p><p>What the example does (see the method <tt class="function">main()</tt>)
<div class="orderedlist"><ol type="1"><li>It reads the file <tt class="filename">Address.xml</tt>. This is the
very same file, which we have created in the first example.</li><li>It creates an instance of <tt class="classname">InputSource</tt>. The
<tt class="classname">InputSource</tt> is specified by the <span class="acronym">SAX</span>
API and can be viewed as an abstraction of the data source where to
read XML from, typically an <tt class="classname">InputStream</tt> or a <tt class="classname">Writer</tt>.</li><li>The method <tt class="function">getAddress()</tt> is invoked
to convert the XML document into an instance of <span class="token">Address</span>.
These are the promised three lines, again using classes and methods
from <span class="acronym">JAXB</span>.</li><li>Finally the method <tt class="function">getAddressAsString</tt>
is invoked to convert the <span class="token">Address</span> instance back into a
printable String, which we may use to verify that everything went fine.
(It is always nice to see a result being displayed on the screen. :-)</li></ol></div></p></div></div><div class="navfooter"><hr><table summary="Navigation footer" width="100%"><tr><td align="left" width="40%"><a accesskey="p" href="ch01.html">Prev</a> </td><td align="center" width="20%"><a accesskey="u" href="ch01.html">Up</a></td><td align="right" width="40%"> <a accesskey="n" href="ch02.html">Next</a></td></tr><tr><td valign="top" align="left" width="40%">Chapter 1. First steps </td><td align="center" width="20%"><a accesskey="h" href="index.html">Home</a></td><td valign="top" align="right" width="40%"> Chapter 2. Reference</td></tr></table></div></body></html>
1.1 ws-site/targets/jaxme/manual/ch02.html
Index: ch02.html
===================================================================
<html><head><META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Chapter 2. Reference</title><meta content="DocBook XSL Stylesheets V1.62.0" name="generator"><link rel="home" href="index.html" title="The JaxMe 2 manual"><link rel="up" href="index.html" title="The JaxMe 2 manual"><link rel="previous" href="ch01s02.html" title="Working with XML"><link rel="next" href="ch02s02.html" title="Marshalling objects"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table summary="Navigation header" width="100%"><tr><th align="center" colspan="3">Chapter 2. Reference</th></tr><tr><td align="left" width="20%"><a accesskey="p" href="ch01s02.html">Prev</a> </td><th align="center" width="60%"> </th><td align="right" width="20%"> <a accesskey="n" href="ch02s02.html">Next</a></td></tr></table><hr></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="N1018C"></a>Chapter 2. Reference</h2></div></div><div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="ch02.html#N10191">The JaxMe Ant task</a></span></dt><dd><dl><dt><span class="sect2"><a href="ch02.html#N102A5">The Up-to-date check</a></span></dt></dl></dd><dt><span class="sect1"><a href="ch02s02.html">Marshalling objects</a></span></dt><dd><dl><dt><span class="sect2"><a href="ch02s02.html#N102BE">Marshaller methods</a></span></dt><dt><span class="sect2"><a href="ch02s02.html#N1039F">Marshaller properties</a></span></dt></dl></dd></dl></div><p>This chapter is more formal and can be assumed to be the JaxMe reference documentation.</p><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="N10191"></a>The JaxMe Ant task</h2></div></div><div></div></div><p>The JaxMe Ant task was written with the following in mind:
<div class="itemizedlist"><ul type="disc"><li>Preserve as much compatibility as possible to the JAXB xjc task</li><li>Provide access to the JaxMe extensions</li></ul></div>
In other words, if you have existing build scripts using JAXB's xjc, you should
be able to convert them to JaxMe with a single switch (by exchanging the
class name in the task definition). However, if you like to make use of JaxMe's
extensions at a later time, you are free to do so.</p><p>A typical use of the Ant task looks like this:
<pre class="programlisting">
<target name="taskdef">
<taskdef name="xjc"
classname="org.apache.ws.jaxme.generator.XJCTask"
classpathref="generate.class.path"/>
</target>
<target name="generate" depends="taskdef">
<xjc schema="schema.xsd" target="build/src">
<produces includes="com/acme/*.java"/>
</xjc>
</target>
</pre>
</p><p>In other words: Typically you define a target like "taskdef", which loads the
ant task under a given name ("xjc" in the above example, or "jaxme"). The task is
actually used in another target.</p><p>The ant task supports the following attributes:
<div class="table"><a name="N101A6"></a><p class="title"><b>Table 2.1. Attributes of the JaxMe ant task</b></p><table summary="Attributes of the JaxMe ant task" border="1"><colgroup><col><col><col></colgroup><thead><tr><th>Name</th><th>Description</th><th>Origin</th><th>Required/Default</th></tr></thead><tbody><tr><td>binding</td><td><p>Name of an external binding file being applied to the schema file; this
attribute and the nested <binding> element are mutually exclusive.</p><p>As of this writing, external schema bindings are unsupported by JaxMe.
A BuildException is thrown, if you use this attribute anyways.</p></td><td>JAXB XJC</td><td>No</td></tr><tr><td>extension</td><td><p>If this attribute has the value "true", then the XJC binding compiler
will run in the extension mode. Otherwise, it will run in the strict conformance mode.</p><p>Extension mode indicates that the proprietary "xjc" tags are accepted, which are
specified by the JAXB binding compiler.</p></td><td>JAXB XJC</td><td>No, defaults to "false"</td></tr><tr><td>force</td><td><p>Setting this option to "true" forces the up-to-date check to fail, in
which case the nested <produces> elements are ignored.</p><p>This attribute isn't of much use for the JaxMe user. It is mainly designed
for JaxMe developers who want to specify a value from the command line, because
they have updated the schema compiler and want to run the new version.</p></td><td>JaxMe</td><td>No, defaults to "false"</td></tr><tr><td>package</td><td>Specifies the package name of the generated sources. If this attribute is
specified, then it overrides values specified in the schema bindings, if any.</td><td>JAXB XJC</td><td>No, defaults to values specified in the schema bindings or to a package name
derived from the target namespace URI.</td></tr><tr><td>schema</td><td>Name of a schema file being compiled; this attribute and the nested
<schema> element are mutually exclusive.</td><td>JAXB XJC</td><td>Yes, unless a nested <schema> element is present</td></tr><tr><td>readonly</td><td>If this attribute has the value "true", then the generated source files
will have read-only mode.</td><td>JAXB XJC</td><td>No, defaults to "false"</td></tr><tr><td>removeOldOutput</td><td><p>If one or more nested <produces> elements are specified and this attribute is
set to "true", then the Ant task will ensure that only generated files will remain. In other
words, if you had removed an element named "Foo" from the previous schema version, then the
Ant task will remove <tt class="filename">Foo.java</tt>.</p><p>Note, that this behaviour is slightly different from the JAXB ant task "xjc", which
removes all files matched by any <produces> element, before running the binding
compiler.</p></td><td>JAXB XJC</td><td>No, defaults to "false"</td></tr><tr><td>schemaReader</td><td>Configures the schema reader to use. Defaults to
"org.apache.ws.jaxme.generator.sg.impl.JAXBSchemaReader", which is the JAXB compliant
schema reader. An alternative schema readers is, for example,
"org.apache.ws.jaxme.generator.sg.impl.JaxMeSchemaReader" (a subclass of JAXBSchemaReader
with JaxMe specific extensions).</td><td>JaxMe</td><td>No, defaults to "org.apache.ws.jaxme.generator.sg.impl.JAXBSchemaReader"</td></tr><tr><td>stackSize</td><td><p>Specifies the thread stack size for the XJC binding compiler (J2SE SDK v1.4
or higher). The XJC binding compiler can fail to compile large schemas with
StackOverflowError and, in that case, this option can be used to extend the
stack size. If unspecified, the default VM size is used. The format is equivalent
to the -Xss command-line argument for Sun Microsystems JVM. This value can be
specified in bytes (stackSize="2097152"), kilobytes (stackSize="2048kb"),
or megabytes (stackSize="2mb").</p><p>This attribute is ignored by the JaxMe ant task and present for compatibility
reasons only. A warning is emitted, if you use it.</p></td><td>JAXB XJC</td><td>No</td></tr><tr><td>target</td><td>Specifies the target directory, where generated sources are being created
in a package structure. For example, if the "target" attribute has the value
"src" and the "package" attribute is "com.acme", then the directory
<tt class="filename">src/com/acme</tt> will be used.</td><td>JAXB XJC</td><td>No, defaults to the current directory</td></tr><tr><td>validating</td><td>Depending on this attributes value, the XML parser used to parse the XML
schema file will either be validating or not.</td><td>JaxMe</td><td>No, defaults to "false"</td></tr></tbody></table></div></p><p>The ant task also supports the following nested elements:
<div class="table"><a name="N10235"></a><p class="title"><b>Table 2.2. Nested elements of the JaxMe ant task</b></p><table summary="Nested elements of the JaxMe ant task" border="1"><colgroup><col><col><col></colgroup><thead><tr><th>Name</th><th>Description</th><th>Origin</th><th>Multiplicity</th></tr></thead><tbody><tr><td>arg</td><td><p>This nested element is ignored by the JaxMe ant task and exists for
compatibility to the JAXB ant task only. A warning is logged, if you use it
anyways.</p><p>In the case of JAXB it specifies additional command line arguments being
passed to the XJC. For details about the syntax, see the relevant section in
the Ant manual.</p><p>This nested element can be used to specify various options not natively
supported in the JAXB xjc Ant task. For example, currently there is no native
support for the following xjc command-line options:
<div class="itemizedlist"><ul type="disc"><li>-nv</li><li>-catalog</li><li>-use-runtime</li><li>-schema</li><li>-dtd</li><li>-relaxng</li></ul></div></p></td><td>JAXB XJC</td><td>0..Unbounded</td></tr><tr><td>binding</td><td><p>Multiple external binding files may be specified. The element syntax is equivalent
to a nested <fileset>. Use of a nested <binding> element is
mutually exclusive with the use of a "binding" attribute.</p><p>As of this writing, external schema bindings are unsupported by JaxMe.
A BuildException is thrown, if you use this attribute anyways.</p></td><td>JAXB XJC</td><td>0..Unbounded</td></tr><tr><td>classpath</td><td><p>This nested element specifies the classpath for loading user defined classes.
For example, the schema reader specified by the "schemaReader" attribute may be such
a type.</p><p>The JAXB binding compiler is using this classpath for loading user defined types,
as specified by the <javaType> customization. This is currently not the case
for JaxMe: The type names are simply compiled in without an attempt to actually load
them. This has the advantage, that user defined classes may refer generated sources.
</p></td><td>JAXB XJC</td><td>0..Unbounded</td></tr><tr><td>depends</td><td><p>By default the JaxMe Ant tasks up-to-date check considers the specified
schema and binding files only. This is insufficient, if other schema files are included,
imported or redefined.</p><p>The nested <depends> element allows to specify additional files to consider
for the up-to-date check. Typically these are the additional schema files.</p><p>Syntactically the <depends> element specifies a nested <fileset>.</p></td><td>JAXB XJC</td><td>0..Unbounded</td></tr><tr><td>produces</td><td>Specifies the set of files being created by the JaxMe ant task. These
files are considered as targets for the up-to-date check. The syntax of the <produces>
element is equivalent to a nested <fileset>. However, you typically do not
need to set the "dir" attribute, because it defaults to the target directory.
(Note that the JAXB XJC requires setting the "dir" attribute.)</td><td>JAXB XJC</td><td>0..Unbounded</td></tr><tr><td>property</td><td>Sets a property value. These properties may be used by the various source
generators to configure the behaviour. For example, the JDBC schema reader uses
the options "jdbc.driver", "jdbc.url", "jdbc.user", and "jdbc.password" to
configure the database connection. Each property must have attributes "name" (the
property name) and "value" (the property value).</td><td>JaxMe</td><td>0..Unbounded</td></tr><tr><td>schema</td><td>Multiple schema files may be compiled in one or more nested <schema>
elements. The element syntax is equivalent to a nested <fileset>.
Use of a nested <schema> element is mutually exclusive with the use
of a "schema" attribute.</td><td>JAXB XJC</td><td>0..Unbounded</td></tr></tbody></table></div>
</p><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N102A5"></a>The Up-to-date check</h3></div></div><div></div></div><p>By default, the JaxMe ant task will always run the generator and create new files. This
is typically inappropriate for an ant script where your desire is to have as little
modifications as possible, because new files also need to be recompiled, which is slow
and time consuming.</p><p>To achieve a better behaviour, use the nested <produces> and <depends> elements.
If one or more <produces> element is specified, then an up-to-date check is performed
as follows:
<div class="orderedlist"><ol type="1"><li>If the "force" attribute is set to true, then the up-to-date check fails.</li><li>If there are no nested <produces> elements, then the up-to-date check fails.</li><li>Otherwise the set of target files will be computed by evaluating all the nested
<produces> elements. If either of these nested elements computes an empty set, then
the up-to-date check fails.</li><li>Otherwise the set of source files will be created by considering the
"schema" and "binding" attributes, and the nested <schema>, <binding>, and
<depends> elements. If either of the files in the source set is more recent than
any of the files in the target set, then the up-to-date check fails.</li><li>Otherwise the up-to-date check succeeds.</li></ol></div></p></div></div></div><div class="navfooter"><hr><table summary="Navigation footer" width="100%"><tr><td align="left" width="40%"><a accesskey="p" href="ch01s02.html">Prev</a> </td><td align="center" width="20%"><a accesskey="u" href="index.html">Up</a></td><td align="right" width="40%"> <a accesskey="n" href="ch02s02.html">Next</a></td></tr><tr><td valign="top" align="left" width="40%">Working with XML </td><td align="center" width="20%"><a accesskey="h" href="index.html">Home</a></td><td valign="top" align="right" width="40%"> Marshalling objects</td></tr></table></div></body></html>
1.1 ws-site/targets/jaxme/manual/ch02s02.html
Index: ch02s02.html
===================================================================
<html><head><META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Marshalling objects</title><meta content="DocBook XSL Stylesheets V1.62.0" name="generator"><link rel="home" href="index.html" title="The JaxMe 2 manual"><link rel="up" href="ch02.html" title="Chapter 2. Reference"><link rel="previous" href="ch02.html" title="Chapter 2. Reference"><link rel="next" href="apa.html" title="Appendix A. License"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table summary="Navigation header" width="100%"><tr><th align="center" colspan="3">Marshalling objects</th></tr><tr><td align="left" width="20%"><a accesskey="p" href="ch02.html">Prev</a> </td><th align="center" width="60%">Chapter 2. Reference</th><td align="right" width="20%"> <a accesskey="n" href="apa.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="N102B9"></a>Marshalling objects</h2></div></div><div></div></div><p>This section describes the various ways of marshalling JaxMe objects and
how to configure the marshalling process. Note, that this section uses both
methods and features, which are specified by JAXB and others, which are
proprietary to JaxMe. Explicit remarks will tell you about the latter,
so that you are still able to write 100% portable code.</p><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N102BE"></a>Marshaller methods</h3></div></div><div></div></div><p>The following methods are specified by JAXB. We'll present each method,
followed by a small piece of example code.</p><div class="variablelist"><p class="title"><b>Marshaller methods</b></p><dl><dt><span class="term"><tt class="function">public void marshal(Object, OutputStream) throws JAXBException</tt></span></dt><dd><p>Marshals the object into the given <tt class="classname">java.io.OutputStream</tt>.</p><div class="example"><a name="N102D1"></a><p class="title"><b>Example 2.1. Marshalling into an OutputStream</b></p><pre class="programlisting">
public void writeToFile(JAXBContext pContext, Object pObject, String pFileName)
throws JAXBException, IOException {
java.io.FileOutputStream fos = new FileOutputStream(pFileName);
Marshaller marshaller = pContext.createMarshaller();
marshaller.setProperty(Marshaller.JAXB_ENCODING, "UTF-8");
marshaller.marshal(pObject, fos);
fos.close();
}
</pre></div><p>The important thing to note in our case is the use of an encoding.
Depending on the encoding, the <tt class="classname">Marshaller</tt> will convert
characters (16 bit entities) into bytes (8 bit entities). The encoding may
also have influence on the marshallers decision, which characters to escape
using <span class="token">&#ddd;</span> or not.</p></dd><dt><span class="term"><tt class="function">public void marshal(Object, Writer) throws JAXBException</tt></span></dt><dd><p>Marshals the object into the given <tt class="classname">java.io.Writer</tt>.</p><div class="example"><a name="N102EA"></a><p class="title"><b>Example 2.2. Marshalling into a Writer</b></p><pre class="programlisting">
public void writeToFile(JAXBContext pContext, Object pObject, String pFileName)
throws JAXBException, IOException {
java.io.FileWriter fw = new FileWriter(pFileName);
Marshaller marshaller = pContext.createMarshaller();
marshaller.setProperty(Marshaller.JAXB_ENCODING, "UTF-8");
marshaller.marshal(pObject, fw);
fw.close();
}
</pre></div><p>This example is almost equivalent to the previous example with an <tt class="classname">OutputStream</tt>
as the target. In practice, the result may be slightly different anyways, for example, because the
<tt class="classname">Marshaller</tt> may choose a different set of characters to escape.</p><div class="example"><a name="N102F8"></a><p class="title"><b>Example 2.3. Marshalling into a <tt class="classname">String</tt></b></p><pre class="programlisting">
public String asString(JAXBContext pContext, Object pObject)
throws JAXBException {
java.io.StringWriter sw = new StringWriter();
Marshaller marshaller = pContext.createMarshaller();
marshaller.setProperty(Marshaller.JAXB_ENCODING, "UTF-8");
marshaller.marshal(pObject, sw);
return sw.toString();
}
</pre></div><p>The example shows, how to convert a JaxMe object into a <tt class="classname">String</tt>. Note
that the use of an encoding still applies, although there occurs no conversion from characters into
bytes. (In the former example using the <tt class="classname">FileWriter</tt> there has been an implicit
conversion, because any file is in fact a byte stream.) However, the <tt class="classname">Marshaller</tt>
may still choose to escape characters or not.</p></dd><dt><span class="term"><tt class="function">public void marshal(Object, org.w3c.dom.Node) throws JAXBException</tt></span></dt><dd><p>This method is used to convert a JaxMe object into a DOM tree. An instance
of <tt class="classname">org.w3c.dom.Element</tt> will be created and appended to the given node.
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>The <tt class="classname">node</tt> must be ready to accept an element as a child.
Suitable nodes are, for example, documents, document fragments, or elements.</div>
As an example, we'll demonstrate how to convert the JaxMe object into an instance
of <tt class="classname">org.w3c.dom.Document</tt>.</p><div class="example"><a name="N1031F"></a><p class="title"><b>Example 2.4. </b></p><pre class="programlisting">
public Document asDOMDocument(JAXBContext pContext, Object pObject,
javax.xml.parsers.DocumentBuilderFactory pFactory)
throws JAXBException, javax.xml.parsers.ParserConfigurationException {
org.w3c.dom.Document result = pFactory.newDocumentBuild().newDocument();
Marshaller marshaller = pContext.createMarshaller();
marshaller.marshal(pObject, result);
return result;
}
</pre></div><p>Note, that no encoding issues arise in this example, because the DOM tree
is an abstract representation of the XML documents, much like JaxMe objects.
However, the same issues are still to be applied, if you serialize the DOM tree
into an <tt class="classname">OutputStream</tt> or <tt class="classname">Writer</tt>.</p></dd><dt><span class="term"><tt class="function">public void marshal(Object, org.xml.sax.ContentHandler) throws JAXBException</tt></span></dt><dd><p>This method is by far the most powerfull of all the marshaller methods: A ContentHandler
is in fact just a generic XML processor, implemented as an event handler. In the case of
JaxMe all the other marshalling methods are just thin wrappers around this one: XML serialization
is implemented by the <tt class="classname">XMLWriter</tt>, which is just an extension of the
<tt class="classname">ContentHandler</tt>. As an example, we'll demonstrate how to transform a
JaxMe object using an XSL stylesheet, writing the result into an <tt class="classname">OutputStream</tt>:
</p><div class="example"><a name="N1033C"></a><p class="title"><b>Example 2.5. Transformation of a JaxMe object using an XSL stylesheet</b></p><pre class="programlisting">
public void transformToFile(JAXBContext pContext, Object pObject,
TransformerFactory pFactory, String pStylesheetFileName,
String pOutputFileName)
throws JAXBException, TransformerConfigurationException {
javax.xml.transform.Source stylesheetSource =
new javax.xml.transform.StreamSource(new java.io.File(pStylesheetFileName));
javax.xml.transform.Result outputResult =
new javax.xml.transform.StreamResult(new java.io.File(pOutputFileName));
javax.xml.transform.sax.TransformerHandler handler =
((SAXTransformerFactory) pFactory).newTransformerHandler(stylesheetSource);
handler.setResult(outputResult);
handler.getTransformer().setOutputProperty("output.encoding", "UTF-8");
Marshaller marshaller = pContext.createMarshaller();
marshaller.marshal(pObject, handler);
}
</pre></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>The SAX ContentHandler receives an abstract representation of the JaxMe object. So there's no
need to set the <tt class="classname">Marshaller</tt>'s encoding. This is the same as in the
DOM example.</p><p>However, the above example contains in fact two transformations: The first one is the
stylesheet transformation, performed by the <tt class="varname">transformerHandler</tt>.
But there is another, implicit, transformation, which the
<tt class="varname">transformerHandler</tt> also performs, because we have choosen an
instance of <tt class="classname">StreamResult</tt> as the transformers destination. In other
words, its the <tt class="classname">Transformer</tt> who needs to know the desired encoding and not the
<tt class="classname">Marshaller</tt>. That's why we set the stylesheet parameter
<span class="token">output.encoding</span>.</p></div></dd><dt><span class="term"><tt class="function">public void marshal(Object, javax.xml.transform.Result) throws JAXBException</tt></span></dt><dd><p>This marshalling method is a generalization of the methods we've seen so far. An instance
of <tt class="classname">Result</tt> is an abstraction of the marshalling destination. Concrete
implementations are the <tt class="classname">StreamResult</tt> (writing to an
<tt class="classname">OutputStream</tt> or <tt class="classname">Writer</tt>), the
<tt class="classname">DOMResult</tt> (creating a DOM tree), and the <tt class="classname">SAXResult</tt>,
which fires <span class="acronym">SAX</span> events into a <tt class="classname">ContentHandler</tt>.</p><p>In theory, a <tt class="classname">Result</tt> can encapsulate arbitrary destinations. In
practice one is restricted to the above standard cases, because the <tt class="classname">Result</tt>
has no useful methods at all. In other words, a new implementation can only be used, if all
users of the <tt class="classname">Result</tt> know how to deal with it. In our case the users
include <span class="application">JaxMe</span>.</p><p>The above limitations are best described, if we use the <span class="application">JaxMe</span>
implementation of the method as an example:</p><div class="example"><a name="N10391"></a><p class="title"><b>Example 2.6. <span class="application">JaxMe</span>'s implementation of the <tt class="classname">Result</tt>
destination</b></p><pre class="programlisting">
public void marshal(Object pObject, Result pResult) throws JAXBException {
if (pResult instanceof SAXResult) {
ContentHandler ch = ((SAXResult) pResult).getHandler();
if (ch == null) {
throw new MarshalException("The SAXResult doesn't have its ContentHandler set.");
}
marshal(pObject, ch);
} else if (pResult instanceof StreamResult) {
StreamResult sr = (StreamResult) pResult;
Writer w = sr.getWriter();
if (w == null) {
OutputStream s = sr.getOutputStream();
if (s == null) {
throw new MarshalException("The StreamResult doesn't have its Writer or OutputStream set.");
}
marshal(pObject, s);
} else {
marshal(pObject, w);
}
} else if (pResult instanceof DOMResult) {
Node node = ((DOMResult) pResult).getNode();
if (node == null) {
throw new MarshalException("The DOMResult doesn't have its Node set.");
}
marshal(pObject, node);
} else {
throw new MarshalException("Unknown type of Result: " + pResult.getClass().getName() +
", only SAXResult, StreamResult and DOMResult are supported.");
}
}
</pre></div><p>In other words, the method is implemented as a thin wrapper around the
others we've seen so far. (Funny enough, it would have been possible to go the
other way and implement all others as wrappers around this one. However, that
would require the presence of an XSLT implementation at runtime and most
possibly quite inefficient.</p></dd></dl></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N1039F"></a>Marshaller properties</h3></div></div><div></div></div><p>In the previous section we've already seen how to configure the <tt class="classname">Marshaller</tt>'s
encoding by setting a <span class="token">property</span>. In this section we'll present a complete list of all
the properties supported by the <span class="application">JaxMe</span> <tt class="classname">Marshaller</tt>.
</p><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="N103B1"></a><span class="acronym">JAXB</span> standard <tt class="classname">Marshaller</tt> properties</h4></div></div><div></div></div><p>The following properties are part by the <span class="acronym">JAXB</span> specification. In other
words: You are safe to use them with any <span class="acronym">JAXB</span> compliant implementation,
including <span class="application">JaxMe</span>. Whenever possible, we recommend to use only this
properties and no others.</p><div class="variablelist"><p class="title"><b><span class="acronym">JAXB</span> standard <tt class="classname">Marshaller</tt> properties</b></p><dl><dt><span class="term"><span class="token">jaxb.encoding</span>, </span><span class="term"><tt class="classname">Marshaller</tt>.<tt class="constant">JAXB_ENCODING</tt></span></dt><dd><p>As we have already seen, this property specifies the encoding used by the
<tt class="classname">Marshaller</tt>, if applicable. The encoding is used to determine
<div class="itemizedlist"><ul type="disc"><li>when a character will be escaped using the notation &#ddd; and</li><li>if the method <tt class="function">marshal(Object, OutputStream)</tt> is used,
how the character is converted into bytes</li></ul></div></p><p>For example, if we have the encoding <tt class="constant">ISO-8859-1</tt> (also known as
<span class="token">Latin-1</span>), which is mainly used in the U.S. and western europe (Great
Britain, France, Germany, ...) then the <tt class="classname">Marshaller</tt> knows, that
no other characters that the character set should be limited to the Unicode points
0..255. In other words, all other characters will be escaped. The <span class="token">Latin-1</span>
characters, however, will be passed through to the <tt class="classname">Writer</tt>, or
<tt class="classname">OutputStream</tt>, because they are immediately mapped to the
corresponding bytes.</p></dd><dt><span class="term"><span class="token">jaxb.formatted.output</span>, </span><span class="term"><tt class="classname">Marshaller</tt>.<tt class="constant">JAXB_FORMATTED_OUTPUT</tt></span></dt><dd><p>By default, any <tt class="classname">Marshaller</tt> will create formatted output,
when marshalling to an <tt class="classname">OutputStream</tt> or <tt class="classname">Writer</tt>.
In other words, the created output will look roughly like the following:
<pre class="programlisting">
<Person>
<FullName>
<FirstName>Jochen</FirstName>
<SurName>Wiedmann</SurName>
</FullName>
</Person>
</pre>
As opposed to unformatted output:
<pre class="programlisting">
<Person><FullName><FirstName>Jochen</FirstName><SurName>Wiedmann</SurName></FullName></Person>
</pre>
The following example turns off the default handling and creates a String containing
unformatted XML:</p><div class="example"><a name="N10418"></a><p class="title"><b>Example 2.7. Creating unformatted XML</b></p><pre class="programlisting">
public String asUnformattedString(JAXBContext pContext, Object pObject, String pFileName)
throws JAXBException {
java.io.StringWriter sw = new StringWriter();
Marshaller marshaller = pContext.createMarshaller();
marshaller.setProperty(Marshaller.JAXB_ENCODING, "UTF-8");
marshaller.setProperty(Marshaller.JAXB_FORMATTED_OUTPUT, Boolean.FALSE);
marshaller.marshal(pObject, sw);
return sw.toString();
}
</pre></div></dd></dl></div></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="N1041E"></a><span class="application">JaxMe</span> specific <tt class="classname">Marshaller</tt>properties</h4></div></div><div></div></div><div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Warning</h3>The following properties must not be used for portable applications, because they are
proprietary to <span class="application">JaxMe</span>.</div><div class="variablelist"><p class="title"><b><span class="application">JaxMe</span> specific <tt class="classname">Marshaller</tt>properties</b></p><dl><dt><span class="term"><span class="token">jaxme.datatype.converter</span>, </span><span class="term"><tt class="classname">JMControllerImpl</tt>.<tt class="constant">JAXME_DATATYPE_CONVERTER</tt></span></dt><dd><p>The <tt class="classname">javax.xml.bind.DatatypeConverterInterface</tt> is used by
<span class="acronym">JAXB</span> implementations to convert various data types into strings
and vice versa. For example, there is a method <tt class="function">parseInt(String)</tt>,
converting the given string into a primitive integer. Likewise, there is a reverse
method <tt class="function">printInt(int)</tt>, converting the same integer back into a
string. The various "parse" methods are used by the <tt class="classname">Unmarshaller</tt>
and the "print" methods are used by the <tt class="classname">Marshaller</tt>.</p><p>The datatype converter is accessible for two reasons: First of all, you need one
when writing custom parse and print methods (as specified by the
<span class="token">jaxb:property/jaxb:conversion</span> tags in the schema). In that case you
can use a datatype converter by invoking the static methods of the class
<tt class="classname">DatatypeConverter</tt>, which is internally using a single, global
instance of <tt class="classname">DatatypeConverterInterface</tt>.</p><p>In the special case of <span class="application">JaxMe</span>, however, you are by no
means restricted to the global instance. In contrary, any <span class="application">JaxMe</span>
<tt class="classname">Marshaller</tt> or <tt class="classname">Unmarshaller</tt> holds an
internal instance, by default the global instance from
<tt class="classname">DatatypeConverter</tt>.</p><p>The advantage is, that you may customize how documents marshalled by JaxMe may
look like. As an example, we'll show how to customize the look of the data type
<span class="token">xs:datetime</span>. The XML Schema specification requests, that timestamps
are marshalled as <span class="token">yyyy-MM-ddThh:mm:ss</span>, which only few people will
like. Additionally the specification requires that timestamps are given in UTC
time, not local time.</p><p>The specification does so for good reason: Timezone and Locale issues are eliminated.
If your XML instances conform to the XML Schema format, it is most likely that you won't
have interoperability problems with foreign software. Fact is, however, that
not all of us are working in a multinational environment and prefer human readable
formats and local time.</p><div class="example"><a name="N1047F"></a><p class="title"><b>Example 2.8. Using a custom datatype converter</b></p><pre class="programlisting">
// Create a subclass of the JaxMe datatype converter, overriding its parseDateTime() and
// printDateTime() methods.
public class MyDatatypeConverter extends org.apache.ws.jaxme.impl.DatatypeConverterImpl {
public Calendar parseDateTime(String arg0) {
DateFormat df = DateFormat.getDateTimeInstance();
Calendar cal = Calendar.getInstance();
try {
cal.setTime(df.parse(arg0));
} catch (ParseException e) {
if (df instanceof SimpleDateFormat) {
SimpleDateFormat sdf = (SimpleDateFormat) df;
throw new IllegalArgumentException("Failed to parse dateTime " + arg0 +
" with pattern " + sdf.toPattern());
} else {
throw new IllegalArgumentException("Failed to parse dateTime " + arg0);
}
}
return cal;
}
public String printDateTime(Calendar arg0) {
return DateFormat.getDateTimeInstance().format(arg0.getTime());
}
}
// Convert a JaxMe object into a String, using the above converter
public String asString(JAXBContext pContext, Object pObject)
throws JAXBException {
java.io.StringWriter sw = new StringWriter();
Marshaller marshaller = pContext.createMarshaller();
marshaller.setProperty(Marshaller.JAXB_ENCODING, "UTF-8");
marshaller.setProperty(JMControllerImpl.JAXME_DATATYPE_CONVERTER, new MyDatatypeConverter());
marshaller.marshal(pObject, sw);
return sw.toString();
}
</pre></div><div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Warning</h3>The above example may cause problems, because it depends on a suitable implementation
of the local date format. For example, in some asiatic locales, the default format will
contain local characters. The effect is, that you'll need to specify a proper encoding.
<span class="token">UTF-8</span> is always the recommended choice.
</div></dd><dt><span class="term"><span class="token">jaxme.indentation.separator</span>, </span><span class="term"><tt class="classname">JMMarshallerImpl</tt>.<tt class="constant">JAXME_INDENTATION_SEPARATOR</tt></span></dt><dd><p>This property is used in conjunction with formatted output. If formatted output is
turned on, it contains the string which is used as a line terminator. The property is
ignored, if formatted output is turned off or marshalling to a <span class="acronym">DOM</span>
tree or <span class="acronym">SAX</span> <tt class="classname">ContentHander</tt> occurs.</p><p>The default property value is <span class="token">Line Feed</span> (<span class="acronym">ASCII</span> 10,
or <span class="token">\n</span>), which is
the standard on Linux or Unix. On Windows the standard is <span class="token">Carriage Return</span>,
followed by a <span class="token">Line Feed</span> (<span class="acronym">ASCII</span> 13 and 10, or
<span class="token">\r\n</span>). Rumours are, they are even using a single <span class="token">Carriage Return</span>
on some Apple Macintosh boxes.</p><p>If you want to see the problem live, just take a file with Unix line terminators
and open it in the Windows application <span class="application">Notepad</span>. No matter,
which version of Windows you choose, it remains the same after 20 years of development:
You'll see a text file containing a single line and where you'd expect the lines being
splitted, the editor will show you black boxes only. But rumbling doesn't help, we've got
to live with it.</p><p>The following example shows how to turn on Windows line terminators:</p><div class="example"><a name="N104C2"></a><p class="title"><b>Example 2.9. Turning on Windows line terminators</b></p><pre class="programlisting">
public String asUnformattedString(JAXBContext pContext, Object pObject, String pFileName)
throws JAXBException {
java.io.StringWriter sw = new StringWriter();
Marshaller marshaller = pContext.createMarshaller();
marshaller.setProperty(Marshaller.JAXB_ENCODING, "UTF-8");
marshaller.setProperty(JMMarshallerImpl.JAXME_INDENTATION_STRING, "\r\n");
marshaller.marshal(pObject, sw);
return sw.toString();
}
</pre></div></dd><dt><span class="term"><span class="token">jaxme.indentation.string</span>, </span><span class="term"><tt class="classname">JMMarshallerImpl</tt>.<tt class="constant">JAXME_INDENTATION_STRING</tt></span></dt><dd><p>This property is used in conjunction with formatted output. If formatted output is
turned on, it contains the string which is used to indent one element: By default " " (two
blanks). The property is ignored, if formatted output is turned off or when marshalling
to a <span class="acronym">DOM</span> tree or <span class="acronym">SAX</span> <tt class="classname">ContentHandler</tt>
occurs.</p><p>To demonstrate the effect, we'll show two example documents. First an instance with
default indentation:
<pre class="programlisting">
<Person>
<FullName>
<FirstName>Jochen</FirstName>
<SurName>Wiedmann</SurName>
</FullName>
</Person>
</pre>
If we set the indentation string to " " (four blanks), we'll get
<pre class="programlisting">
<Person>
<FullName>
<FirstName>Jochen</FirstName>
<SurName>Wiedmann</SurName>
</FullName>
</Person>
</pre>
</p></dd><dt><span class="term"><span class="token">jaxme.private.</span>, </span><span class="term"><tt class="classname">JMControllerImpl</tt>.<tt class="constant">JAXME_PRIVATE_</tt></span></dt><dd><p>When writing custom code for formatting or parsing element or attribute values,
you will most probably find at any time, that you wish to access data, which isn't
available by default. In most cases you have the data, when invoking the
<tt class="classname">Marshaller</tt> but not inside the formatter or parser.
A typical example might be, that you want to localize the resulting XML
document by using a resource bundle.</p><p>The <span class="application">JaxMe</span> <tt class="classname">Marshaller</tt> allows
to set arbitrary, application specific properties, but only if they are prefixed
with <span class="token">jaxme.private.</span>. The idea is that an unknown property name
is most probably just a typo or a similar problem and it is better to throw
an exception to let the programmer know that there's something wrong. However,
if the property name is prefixed with <span class="token">jaxme.private.</span>, the
<span class="application">JaxMe</span> user advises, that "this unknown property is
fine".</p><div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Warning</h3>Custom property values are arbitrary. However, you should not attempt to
distinguish the between the cases <span class="token">null</span> and missing, because the
JAXB specification has nothing like a collections method
<tt class="function">contains(Object)</tt>.</div></dd><dt><span class="term"><span class="token">jaxme.xml.declaration</span>, </span><span class="term"><tt class="classname">JMMarshallerImpl</tt>.<tt class="constant">JAXME_XML_DECLARATION</tt></span></dt><dd><p>When writing to an <tt class="classname">OutputStream</tt> or <tt class="classname">Writer</tt>,
it is likely that you want your resulting XML document to have an XML declaration like
<pre class="programlisting">
<?xml version="1.0" encoding="UTF-8"?>
</pre>
By default JaxMe does not create such a declaration, because that would make it difficult
to embed the resulting XML into a larger document.</p><p>An XML declaration is particularly important, if you use another encoding than
<tt class="constant">UTF-8</tt>. In that case you should consider a declaration as
mandatory.</p><p>The property has no effect, when marshalling to DOM trees, or SAX handlers.</p><div class="example"><a name="N10532"></a><p class="title"><b>Example 2.10. Enabling an XML declaration</b></p><pre class="programlisting">
// Convert a JaxMe object into a String, using the above converter
public String asString(JAXBContext pContext, Object pObject)
throws JAXBException {
java.io.StringWriter sw = new StringWriter();
Marshaller marshaller = pContext.createMarshaller();
marshaller.setProperty(Marshaller.JAXB_ENCODING, "UTF-8");
marshaller.setProperty(JMMarshallerImpl.JAXME_XML_DECLARATION, Boolean.TRUE);
marshaller.marshal(pObject, sw);
return sw.toString();
}
</pre></div></dd><dt><span class="term"><tt class="constant">jaxme.xml.writer</tt>, </span><span class="term"><span class="application">JMMarshallerImpl</span>.<tt class="constant">JAXME_XML_WRITER</tt></span></dt><dd><p>If the above properties still don't satisfy your needs, this property is your
friend. It allows to take complete control on the created XML document, when
marshalling to an <tt class="classname">OutputStream</tt> or <tt class="classname">Writer</tt>.
(It takes no effect otherwise.)</p><p>The property value is an instance of <tt class="classname">java.lang.Class</tt>
implementing <tt class="classname">org.apache.ws.jaxme.XMLWriter</tt>, which is in turn
extending <tt class="classname">org.xml.sax.ContentHandler</tt>. That means, that you
can do arbitrary things, including use of an XSLT stylesheet and stuff like that.</p><p><span class="application">JaxMe</span> comes with three ready-to-use implementations:
<div class="variablelist"><dl><dt><span class="term"><tt class="classname">org.apache.ws.jaxme.impl.XMLWriterImpl</tt></span></dt><dd><p>This is the default implementation, suitable for any encoding and Java
platform. It is very simple: It is in fact using the <span class="token">US-ASCII</span>
encoding, escaping all Unicode points above 126.</p></dd><dt><span class="term"><tt class="classname">org.apache.ws.jaxme.impl.CharSetXMLWriter</tt></span></dt><dd><p>This implementation is used, whenever you are running Java 1.4 or newer.
It is internally using the class <tt class="classname">java.nio.charset.CharsetEncoder</tt>
to determine the Unicode points being escaped.</p></dd><dt><span class="term"><tt class="classname">org.apache.ws.jaxme.impl.PassThroughXMLWriter</tt></span></dt><dd><p>This implementation does no escaping at all.</p></dd></dl></div></p><p>As an example, we'll write and use and <tt class="classname">XMLWriter</tt> which is
escaping the german Umlauts, but no other characters.</p><div class="example"><a name="N1057D"></a><p class="title"><b>Example 2.11. Implementation of an XMLWriter escaping german Umlauts</b></p><pre class="programlisting">
public class UmlautXMLWriter extends org.apache.ws.jaxme.impl.XMLWriterImpl {
protected boolean canEncode(char c) {
switch (c) {
case 228:
case 246:
case 252:
case 196:
case 214:
case 220:
case 223:
return false;
default:
return true;
}
}
}
// Convert a JaxMe object into a String, using the above XMLWriter
public String asString(JAXBContext pContext, Object pObject)
throws JAXBException {
java.io.StringWriter sw = new StringWriter();
Marshaller marshaller = pContext.createMarshaller();
marshaller.setProperty(Marshaller.JAXB_ENCODING, "UTF-8");
marshaller.setProperty(JMMarshallerImpl.JAXME_XML_WRITER, UmlautXMLWriter.class);
marshaller.marshal(pObject, sw);
return sw.toString();
}
</pre></div></dd></dl></div></div></div></div><div class="navfooter"><hr><table summary="Navigation footer" width="100%"><tr><td align="left" width="40%"><a accesskey="p" href="ch02.html">Prev</a> </td><td align="center" width="20%"><a accesskey="u" href="ch02.html">Up</a></td><td align="right" width="40%"> <a accesskey="n" href="apa.html">Next</a></td></tr><tr><td valign="top" align="left" width="40%">Chapter 2. Reference </td><td align="center" width="20%"><a accesskey="h" href="index.html">Home</a></td><td valign="top" align="right" width="40%"> Appendix A. License</td></tr></table></div></body></html>
1.1 ws-site/targets/jaxme/manual/go01.html
Index: go01.html
===================================================================
<html><head><META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Glossary</title><meta content="DocBook XSL Stylesheets V1.62.0" name="generator"><link rel="home" href="index.html" title="The JaxMe 2 manual"><link rel="up" href="index.html" title="The JaxMe 2 manual"><link rel="previous" href="apb.html" title="Appendix B. FAQ"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table summary="Navigation header" width="100%"><tr><th align="center" colspan="3">Glossary</th></tr><tr><td align="left" width="20%"><a accesskey="p" href="apb.html">Prev</a> </td><th align="center" width="60%"> </th><td align="right" width="20%"> </td></tr></table><hr></div><div class="glossary"><div class="titlepage"><div><div><h2 class="title"><a name="N10641"></a>Glossary</h2></div></div><div></div></div><dl><dt><a name="BSDLicense"></a>BSD License</dt><dd><p>One of the worlds most important open source licenses, originally developed
for BSD Unix. It is very liberal: Basically it allows you to redistribute both sources and binaries,
as you want. Unlike the GPL you may even sell derivated works. See also
<a href="http://www.opensource.org/licenses/bsd-license.php" target="_top">
http://www.opensource.org/licenses/bsd-license.php</a>.</p></dd><dt><a name="JAXB"></a>Java specification for XML Binding</dt><dd><p>
JAXB (<a href="http://java.sun.com/xml/jaxb/" target="_top">http://java.sun.com/xml/jaxb/</a>)
is the SUN specification for Java/XML binding.
It is also available as a reference implementation. JaxMe aims to become another
JAXB implementation at some time. However, full JAXB support is far from complete.
</p></dd></dl></div><div class="navfooter"><hr><table summary="Navigation footer" width="100%"><tr><td align="left" width="40%"><a accesskey="p" href="apb.html">Prev</a> </td><td align="center" width="20%"><a accesskey="u" href="index.html">Up</a></td><td align="right" width="40%"> </td></tr><tr><td valign="top" align="left" width="40%">Appendix B. FAQ </td><td align="center" width="20%"><a accesskey="h" href="index.html">Home</a></td><td valign="top" align="right" width="40%"> </td></tr></table></div></body></html>
1.1 ws-site/targets/jaxme/manual/index.html
Index: index.html
===================================================================
<html><head><META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>The JaxMe 2 manual</title><meta content="DocBook XSL Stylesheets V1.62.0" name="generator"><link rel="home" href="index.html" title="The JaxMe 2 manual"><link rel="next" href="pr01.html" title="Introduction"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table summary="Navigation header" width="100%"><tr><th align="center" colspan="3">The JaxMe 2 manual</th></tr><tr><td align="left" width="20%"> </td><th align="center" width="60%"> </th><td align="right" width="20%"> <a accesskey="n" href="pr01.html">Next</a></td></tr></table><hr></div><div class="book" lang="en"><div class="titlepage"><div><div><h1 class="title"><a name="N10001"></a>The JaxMe 2 manual</h1></div><div><div class="author"><h3 class="author"><span class="firstname">Jochen</span> <span class="surname">Wiedmann</span></h3></div></div><div><p class="copyright">Copyright © 2003 The JaxMe project</p></div></div><div></div><hr></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="preface"><a href="pr01.html">Introduction</a></span></dt><dt><span class="chapter"><a href="ch01.html">1. First steps</a></span></dt><dd><dl><dt><span class="sect1"><a href="ch01.html#N10035">Generating Java code</a></span></dt><dd><dl><dt><span class="sect2"><a href="ch01.html#N1003A">Creating a JaxMe schema</a></span></dt><dt><span class="sect2"><a href="ch01.html#N1004D">Running the generator</a></span></dt></dl></dd><dt><span class="sect1"><a href="ch01s02.html">Working with XML</a></span></dt><dd><dl><dt><span class="sect2"><a href="ch01s02.html#N10118">Writing XML documents</a></span></dt><dt><span class="sect2"><a href="ch01s02.html#N10149">Reading XML</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="ch02.html">2. Reference</a></span></dt><dd><dl><dt><span class="sect1"><a href="ch02.html#N10191">The JaxMe Ant task</a></span></dt><dd><dl><dt><span class="sect2"><a href="ch02.html#N102A5">The Up-to-date check</a></span></dt></dl></dd><dt><span class="sect1"><a href="ch02s02.html">Marshalling objects</a></span></dt><dd><dl><dt><span class="sect2"><a href="ch02s02.html#N102BE">Marshaller methods</a></span></dt><dt><span class="sect2"><a href="ch02s02.html#N1039F">Marshaller properties</a></span></dt></dl></dd></dl></dd><dt><span class="appendix"><a href="apa.html">A. License</a></span></dt><dt><span class="appendix"><a href="apb.html">B. FAQ</a></span></dt><dt><span class="glossary"><a href="go01.html">Glossary</a></span></dt></dl></div><div class="list-of-tables"><p><b>List of Tables</b></p><dl><dt>2.1. <a href="ch02.html#N101A6">Attributes of the JaxMe ant task</a></dt><dt>2.2. <a href="ch02.html#N10235">Nested elements of the JaxMe ant task</a></dt></dl></div><div class="list-of-examples"><p><b>List of Examples</b></p><dl><dt>2.1. <a href="ch02s02.html#N102D1">Marshalling into an OutputStream</a></dt><dt>2.2. <a href="ch02s02.html#N102EA">Marshalling into a Writer</a></dt><dt>2.3. <a href="ch02s02.html#N102F8">Marshalling into a String</a></dt><dt>2.4. <a href="ch02s02.html#N1031F"></a></dt><dt>2.5. <a href="ch02s02.html#N1033C">Transformation of a JaxMe object using an XSL stylesheet</a></dt><dt>2.6. <a href="ch02s02.html#N10391">JaxMe's implementation of the Result
destination</a></dt><dt>2.7. <a href="ch02s02.html#N10418">Creating unformatted XML</a></dt><dt>2.8. <a href="ch02s02.html#N1047F">Using a custom datatype converter</a></dt><dt>2.9. <a href="ch02s02.html#N104C2">Turning on Windows line terminators</a></dt><dt>2.10. <a href="ch02s02.html#N10532">Enabling an XML declaration</a></dt><dt>2.11. <a href="ch02s02.html#N1057D">Implementation of an XMLWriter escaping german Umlauts</a></dt></dl></div></div><div class="navfooter"><hr><table summary="Navigation footer" width="100%"><tr><td align="left" width="40%"> </td><td align="center" width="20%"> </td><td align="right" width="40%"> <a accesskey="n" href="pr01.html">Next</a></td></tr><tr><td valign="top" align="left" width="40%"> </td><td align="center" width="20%"> </td><td valign="top" align="right" width="40%"> Introduction</td></tr></table></div></body></html>
1.1 ws-site/targets/jaxme/manual/pr01.html
Index: pr01.html
===================================================================
<html><head><META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Introduction</title><meta content="DocBook XSL Stylesheets V1.62.0" name="generator"><link rel="home" href="index.html" title="The JaxMe 2 manual"><link rel="up" href="index.html" title="The JaxMe 2 manual"><link rel="previous" href="index.html" title="The JaxMe 2 manual"><link rel="next" href="ch01.html" title="Chapter 1. First steps"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table summary="Navigation header" width="100%"><tr><th align="center" colspan="3">Introduction</th></tr><tr><td align="left" width="20%"><a accesskey="p" href="index.html">Prev</a> </td><th align="center" width="60%"> </th><td align="right" width="20%"> <a accesskey="n" href="ch01.html">Next</a></td></tr></table><hr></div><div class="preface" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="N10010"></a>Introduction</h2></div></div><div></div></div><p>JaxMe 2 is a Java source generator. It is used as the base of XML
application frameworks. Using JaxMe, you get code that
<div class="itemizedlist"><ul type="disc"><li>Converts XML documents into Java beans</li><li>Stores Java beans into a database. It is recommended to use
an XML database as a backend, but relational databases are supported
through an objectrelational mapper. (If your XML documents are
sufficiently simple, that is.) It is even possible to mix different
database engines, depending on the document type.</li><li>Query the database for previously stored data and convert
this data into Java beans.</li><li>The database can be accessed directly or by EJB entity or
session beans. These beans may be generated by JaxMe.</li><li>Finally, Java beans can be mapped into XML.</li></ul></div>
If you follow the above items, you will note, that the complete workflow
of a typical application is supported: Gathering, storing, processing,
and presenting data.</p><p>JaxMe is an open source project: You may redistribute sources, or
binaries, as you like. JaxMe comes to you under the BSD license, a
very liberal license: You are even allowed to redistribute derived works
under a modified license. This is in contrast to the GPL, which requires
that derived works are GPL'ed again.</p></div><div class="navfooter"><hr><table summary="Navigation footer" width="100%"><tr><td align="left" width="40%"><a accesskey="p" href="index.html">Prev</a> </td><td align="center" width="20%"><a accesskey="u" href="index.html">Up</a></td><td align="right" width="40%"> <a accesskey="n" href="ch01.html">Next</a></td></tr><tr><td valign="top" align="left" width="40%">The JaxMe 2 manual </td><td align="center" width="20%"><a accesskey="h" href="index.html">Home</a></td><td valign="top" align="right" width="40%"> Chapter 1. First steps</td></tr></table></div></body></html>