1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<title>A basic binding</title>
</head>
<body class="composite">
<div id="bodycol">
<div class="app">
<div class="h3">
<h3><a name="intro">Getting Started</a></h3>
<p>Here's a simple example of using JiBX. Suppose you have the following XML
customer information document structure:</p>
<div id="source"><pre><customer>
<person>
<cust-num>123456789</cust-num>
<first-name>John</first-name>
<last-name>Smith</last-name>
</person>
<street>12345 Happy Lane</street>
<city>Plunk</city>
<state>WA</state>
<zip>98059</zip>
<phone>888.555.1234</phone>
</customer>
</pre></div>
<p>JiBX provides great flexibility in binding your XML document structure to
Java objects, so there are really many different ways you can represent this
data using JiBX. For right now I'll stay with a Java object model that matches the
XML document structure, and I'll just use plain Java data classes (fields only)
to keep everything compact. Here's what these might look like for my
customer document:</p>
<div id="source"><pre> public class Customer {
public Person person;
public String street;
public String city;
public String state;
public Integer zip;
public String phone;
}
public class Person {
public int customerNumber;
public String firstName;
public String lastName;
}
</pre></div>
<p>This is keeping almost all the data as <code>String</code>s, with the
exception of the customer number and the zip code. These are both values with
natural representations as numbers, so I've gone ahead and expressed them that
way in the Java classes. I used an <code>int</code> for the customer number
because I can be sure I've got one of those. For the zip code I've instead used
an <code>Integer</code>, as an example of a simple object type.</p>
<p><a href="#figure1">Figure 1</a> shows the XML document, the Java classes, and a JiBX binding that
connects the two. I've highlighted in green the top-level connection between the
<b>customer</b> element and the <code>Customer</code> class, linked by the
<b>mapping</b> element in the binding definition; and in blue the connection
between the <b>person</b> element and the <code>Person</code> class, linked by
the <b>structure</b> element in the binding definition.</p>
<a name="figure1"><b>Figure 1. Simple binding example</b></a><br>
<img src="images/example1.gif" width="578" height="296" alt="Simple binding example"/>
</div>
<div class="h3">
<h3><a name="diggingin">Digging into the binding</a></h3>
<p>The <b>mapping</b> element in the <a href="#figure1">Figure 1</a> binding definition
relates the named element (in this case <b>customer</b>) to a particular class
(<code>Customer</code>). JiBX uses the defined mapping as a default for both marshalling
instances of the class and unmarshalling occurrences of the element. Mappings can
be nested, in which case the inner mappings are only active while marshalling or
unmarshalling with the outer mapping. <b><i>Global</i></b> mappings - ones which are
<i>not</i> nested inside other mappings - define elements that can be root
elements of the XML document, and classes that can be root objects of the object
structure. In <a href="#figure1">Figure 1</a>, the mapping from element <b>customer</b> to Java
class <code>Customer</code> is a global mapping.</p>
<p>The <b>structure</b> element in the binding definition defines the handling
of an element or object class within a particular context. In this case the
context of the <b>structure</b> element is the <b>mapping</b> from element
<b>customer</b> to class <code>Customer</code>. The <b>structure</b> element is
a very versatile player in JiBX binding definitions, with variations used for
several purposes. In the <a href="#figure1">Figure 1</a> binding it's playing its basic role, with both
an element name and an object reference (to the <code>person</code> field of the
<code>Customer</code> class) supplied. This works very similarly to a
<b>mapping</b> definition, but is specific to the context rather than setting a
general rule.</p>
<p>This can be a confusing issue. Since <b>mapping</b> and <b>structure</b> have
a lot in common, why use one instead of the other? Well, there are cases where
you <i>have</i> to use one or the other. The root element for a document to be
unmarshalled must have a <b>mapping</b>, as must the class of a root object to
be marshalled. On the other hand, there are things you can do with a
<b>structure</b> element that you can't do with a <b>mapping</b> (some of which
you'll see in a later section of this tutorial, <a href="%structmap%">Structure mapping</a>).
A good principle to start with is to use a <b>mapping</b> only for the root
element of your document (or the class of your root object, whichever way you
prefer to see this). Later in this tutorial you'll learn about other
circumstances where a <b>mapping</b> should be used, but only using it for the
root element/class works fine for now.</p>
<p>JiBX bindings include a number of elements with attributes that reference
classes, such as the <b>mapping</b> element in the <a href="#figure1">Figure
1</a> binding. In this tutorial I've kept the bindings as simple as possible by
using the default package for all the sample classes. When you're using JiBX
with your own classes you'll need to remember to use <i>fully-qualified</i>
names for all your classes (with leading package information, such as
<code>org.jibx.runtime.Utility</code>).</p>
<p>Just to finish up with the <a href="#figure1">Figure 1</a> binding, besides the <b>mapping</b> and
<b>structure</b> elements I've already discussed, all the other components
of the binding definition are <b>value</b> elements. These are the grunt workers
of the binding definition, handling a single text component. In XML terms, the
text component may be an attribute, element, ordinary character data, or CDATA
section. On the Java side, the text component may be a value of any primitive or
object type that has a defined conversion to and from a simple
<code>String</code> value (JiBX has a set of built-in <a href="%conversions%">basic
conversions</a>, and you can easily <a href="%bindextend%#serdeser">define extensions</a>
using static serialize and deserialize methods). In the <a href="#figure1">Figure 1</a> binding, all the
<b>value</b> elements are defining bindings between an XML element name and a
corresponding Java class field.</p>
<div><p align="center"><a href="%bindextras%"><b>Next: Binding Extras</b></a></p></div>
</div>
</div>
</div>
</body>
</html>
|
