<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 Vsnapshot" 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="prev" 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"><div class="titlepage"><div><div><h1 class="title"><a name="N10023"></a>Chapter 1. First steps</h1></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><dt><span class="sect1"><a href="ch01.html#N10037">Generating Java Code</a></span></dt><dd><dl><dt><span class="sect2"><a href="ch01.html#N1003C">Creating a JaxMe Schema</a></span></dt><dt><span class="sect2"><a href="ch01.html#N10053">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#N10120">Writing XML Documents</a></span></dt><dt><span class="sect2"><a href="ch01s02.html#N10151">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
<code class="filename">examples/misc/address.xml</code> in the JaxMe 2 distribution):
</p><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><p>Our target is to convert this into convenient, standard Java bean code, much like the
following:
</p><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><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="N10037"></a>Generating Java Code</h2></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"><div class="titlepage"><div><div><h3 class="title"><a name="N1003C"></a>Creating a JaxMe Schema</h3></div></div></div><p>
The usual way to use JaxMe is to start from a schema and generate source code
from that schema. So (with the address example in mind) we create an XML Schema
from which the sources will be generated. When using JaxMe in the wild sometimes
the schema will already exist, in other cases the application developer will
develop the schema as the application develops. In either case, the way
that JaxMe is used is very similar.</p><p>
The schema can
be regarded as a description of compliant document instances (in our case
addresses). For example
(<code class="filename">examples/misc/address.xsd</code> in the JaxMe 2 distribution):
</p><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><p>
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. XML schema
are very expressive (which is why they support source generation so well) but
with this expressiveness comes complexity. Getting to grips with the XML schema
standard is worth the effort but some users may choose to use one of the numerous tools
that help with XML schema generation.</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="N10053"></a>Running The Generator</h3></div></div></div><p>The easiest way to run the generator is by invoking an Ant task. Here is a typical ant target:
</p><pre class="programlisting">
<target name="taskdef">
<!--
Set up the classpath for the generation task.
Include all the standard jaxme jars.
-->
<path id="generate.class.path">
<pathelement location="jaxme2.jar"/>
<pathelement location="jaxmejs.jar"/>
<pathelement location="jaxmexs.jar"/>
<pathelement location="jaxmeapi.jar"/>
</path>
<!--
Defines the generation task using that classpath.
-->
<taskdef name="xjc"
classname="org.apache.ws.jaxme.generator.XJCTask"
classpathref="generate.class.path"/>
<!--
Generate source code.
The 'schema' attribute gives the path to the schema the sources
will be generated from.
The 'target' attribute specifies the base directory that the source
will be generated into. Sources will be created in subdirectories
corresponding to the package structure.
-->
<xjc
schema="examples/misc/address.xsd"
target="build/src">
<!--
The source files being created. The xjc task uses these for
a check, whether they are uptodate. If so, the generation is
skipped, for improved speed.
Specifying the package isn't necessary, unless you have other
files in the target directory as well, for example manually
written files or files created by another generator or xjc call.
If so, these need to be excluded from the uptodate check.
-->
<produces includes="org/apache/ws/jaxme/examples/misc/address/*.java"/>
</xjc>
</target>
</pre><p>The example demonstrates how a classpath called <span class="token">generate.class.path</span> is
created and used to define a new ant task called "xjc".
This new task is used to compile a schema file called <code class="filename">examples/misc/address.xsd</code>.
The generated sources will reside in the directory <code class="filename">build/src</code>. The target
package is <span class="token">org.apache.ws.jaxme.examples.misc.address</span>, hence the effective location is
<code class="filename">build/src/org/apache/ws/jaxme/examples/misc/address</code>.</p><p>After running the task, looking into that directory, we find that the
following files have been created:
</p><div class="variablelist"><p class="title"><b>Files Generated by the JaxMe Binding Compiler</b></p><dl class="variablelist"><dt><span class="term"><code class="filename">Address.java</code></span></dt><dd><p>Contains the Java interface describing the document type
<span class="token">Address</span>. This interface extends the interface
specified by <code class="filename">AddressType.java</code>.</p></dd><dt><span class="term"><code class="filename">AddressType.java</code></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"><code class="filename">Configuration.xml</code></span></dt><dd><p>This file is used by the JaxMe runtime internally. Typically
you'll never notice that it is even there (though you will need to ensure that it remains
on the classpath). 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"><code class="filename">jaxb.properties</code></span></dt><dd><p>The <acronym class="acronym">JAXB</acronym> standard uses this file. Typically you'll
never even notice that it exists (though again, it must be found on the classpath).
The task of the file is to ensure that
the <acronym class="acronym">JAXB</acronym> runtime correctly initializes the <span class="application">JaxMe</span>
runtime.</p></dd><dt><span class="term"><code class="filename">impl/AddressHandler.java</code></span></dt><dd><p>A <acronym class="acronym">SAX2</acronym> <code class="classname">ContentHandler</code>, which can
convert XML documents of type <span class="token">Address</span> into implementations of the Java
interface <code class="classname">Address</code>. This is rarely called directly. Usually it will be
created and invoked automatically by the <acronym class="acronym">JAXB</acronym>
<code class="classname">Marshaller</code>.</p></dd><dt><span class="term"><code class="filename">impl/AddressImpl.java</code></span></dt><dd><p>Default implementation of the <code class="classname">Address</code> interface.</p></dd><dt><span class="term"><code class="filename">impl/AddressType.java</code></span></dt><dd><p>Default implementation of the <code class="classname">AddressType</code>
interface.</p></dd><dt><span class="term"><code class="filename">impl/AddressTypeHandler.java</code></span></dt><dd><p>Similar to its subclass <code class="classname">AddressHandler</code>,
this is a <acronym class="acronym">SAX2</acronym> <code class="classname">ContentHandler</code> for reading
instances of <code class="classname">AddressType</code>. The
main difference to the subclass is that the subclass doesn't have a fixed
element name.</p></dd><dt><span class="term"><code class="filename">impl/AddressTypeImpl.java</code></span></dt><dd><p>Default implementation of <code class="classname">AddressType</code>.</p></dd><dt><span class="term"><code class="filename">impl/AddressTypeSerializer.java</code></span></dt><dd><p>Converts instances of <code class="classname">AddressType</code>
into XML documents. It is also used to convert instances of <code class="classname">Address</code>.</p></dd></dl></div><p>
</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%"> </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>
distrib
>
Mageia
>
7
>
armv7hl
>
media
>
core-release
>
by-pkgid
>
4b613ef39a28aa9afece4551b2ab42b4
>
files
>
5
