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
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<title>JiBX extras</title>
<style type="text/css">
@import url("./style/tigris.css");
@import url("./style/maven.css");
.dtd-comment {
color: #993399;
font-weight: bold;
</style>
<script type="text/javascript">
if (document.layers) {
document.writeln('<link rel="stylesheet" type="text/css" href="./style/ns4_only.css" media="screen" /><link rel="stylesheet" type="text/css" href="./style/maven_ns4_only.css" media="screen" />')
}
</script>
<link rel="stylesheet" type="text/css" href="./style/print.css" media="print" />
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
</head>
<body class="composite">
<div id="banner">
<table border="0" cellspacing="0" cellpadding="8" width="100%">
<tbody>
<tr>
<td><h1>JiBX extras</h1>
</td>
<td>
<div align="right" id="login"><a href="http://sourceforge.net/projects/jibx"><img src="http://sflogo.sourceforge.net/sflogo.php?group_id=69358&type=16" width="150" height="40" border="0" alt="Get JiBX - XML Data Binding for Java at SourceForge.net. Fast, secure and Free Open Source software downloads" /></a></div>
</td>
</tr>
</tbody>
</table>
</div>
<div id="breadcrumbs">
<table border="0" cellspacing="0" cellpadding="4" width="100%">
<tbody>
<tr>
<td>
<div align="right">
<a href="./index.html">Home Page</a> |
<a href="http://www.sourceforge.net/projects/jibx/">SourceForge Page</a> |
<a href="./mail-lists.html">Mailing Lists</a> |
<a href="./bugs.html">Bugs</a> |
<a href="http://sourceforge.net/project/showfiles.php?group_id=69358">Downloads</a>
</div>
</td>
</tr>
</tbody>
</table>
</div>
<table border="0" cellspacing="0" cellpadding="8" width="100%" id="main">
<tbody>
<tr valign="top">
<td id="leftcol" width="20%">
<div id="navcolumn">
<div>
<strong>JiBX Basics</strong>
<div>
<small>
<a href="index.html">Overview</a>
</small>
<div>
<small>
<a href="getting-started.html">Getting Started</a>
</small>
</div>
<div>
<small>
<a href="bindcomp.html">Binding Compiler</a>
</small>
</div>
<div>
<small>
<a href="bindonload.html">Binding on Load</a>
</small>
</div>
<div>
<small>
<a href="runtime.html">Runtime</a>
</small>
</div>
<div>
<small>
<span class="menu-selection">Extras</span>
</small>
</div>
<div>
<small>
<a href="building.html">Building JiBX</a>
</small>
</div>
<div>
<small>
<a href="./jibx-maven-plugin/index.html">Maven</a>
</small>
</div>
<div>
<small>
<a href="contributing.html">Contributing</a>
</small>
</div>
<div>
<small>
<a href="jibx-license.html">License</a>
</small>
</div>
</div>
<div>
<small>
<a href="status.html">News and Status</a>
</small>
</div>
<div>
<small>
<a href="support.html">Support</a>
</small>
<div>
<small>
<a href="faq.html">FAQ</a>
</small>
</div>
<div>
<small>
<a href="mail-lists.html">Mailing Lists</a>
</small>
</div>
<div>
<small>
<a href="bugs.html">Bugs</a>
</small>
</div>
</div>
<div>
<small>
<a href="comments.html">User Comments</a>
</small>
</div>
<div>
<small>
<a href="sponsors.html">Sponsors</a>
</small>
</div>
</div>
<div>
<strong>Start from Code</strong>
<div>
<small>
<a href="fromcode/index.html">Start from Code</a>
</small>
</div>
<div>
<small>
<a href="fromcode/bindgen.html">BindGen</a>
</small>
<div>
<small>
<a href="fromcode/bindgen-examples.html">Example Code</a>
</small>
<div>
<small>
<a href="fromcode/bindgen-example1.html">Example 1</a>
</small>
</div>
<div>
<small>
<a href="fromcode/bindgen-example2.html">Example 2</a>
</small>
</div>
<div>
<small>
<a href="fromcode/bindgen-example3.html">Example 3</a>
</small>
</div>
<div>
<small>
<a href="fromcode/bindgen-example4.html">Example 4</a>
</small>
</div>
</div>
<div>
<small>
<a href="fromcode/bindgen-customs.html">Customizations Reference</a>
</small>
</div>
</div>
<div>
<small>
<a href="fromcode/schemagen.html">SchemaGen</a>
</small>
</div>
<div>
<small>
<a href="fromcode/jibx2wsdl.html">Jibx2Wsdl</a>
</small>
<div>
<small>
<a href="fromcode/jibx2wsdl-examples.html">Examples</a>
</small>
</div>
<div>
<small>
<a href="fromcode/jibx2wsdl-customs.html">Customizations</a>
</small>
</div>
</div>
</div>
<div>
<strong>Start from Schema</strong>
<div>
<small>
<a href="fromschema/index.html">Start from Schema</a>
</small>
</div>
<div>
<small>
<a href="fromschema/codegen.html">CodeGen</a>
</small>
<div>
<small>
<a href="fromschema/codegen-types.html">Schema Datatype Handling</a>
</small>
</div>
<div>
<small>
<a href="fromschema/codegen-examples.html">Example Code</a>
</small>
<div>
<small>
<a href="fromschema/example-default.html">Default Generation</a>
</small>
</div>
<div>
<small>
<a href="fromschema/example-custom1.html">Simple Customizations</a>
</small>
</div>
<div>
<small>
<a href="fromschema/example-custom2.html">More Customizations</a>
</small>
</div>
<div>
<small>
<a href="fromschema/example-modular.html">Modular Generation</a>
</small>
</div>
</div>
<div>
<small>
<a href="fromschema/codegen-customs.html">Customizations Reference</a>
</small>
<div>
<small>
<a href="fromschema/codegen-extends.html">Extensions Reference</a>
</small>
</div>
</div>
</div>
</div>
<div>
<strong>Binding Definition</strong>
<div>
<small>
<a href="binding/tutorial/binding-tutorial.html">Binding Tutorial</a>
</small>
<div>
<small>
<a href="binding/tutorial/binding-start.html">A basic binding</a>
</small>
</div>
<div>
<small>
<a href="binding/tutorial/binding-extras.html">Binding extras</a>
</small>
</div>
<div>
<small>
<a href="binding/tutorial/binding-structures.html">Structure mapping</a>
</small>
</div>
<div>
<small>
<a href="binding/tutorial/binding-collects.html">Collections and arrays</a>
</small>
</div>
<div>
<small>
<a href="binding/tutorial/binding-mappings.html">Using mappings</a>
</small>
</div>
<div>
<small>
<a href="binding/tutorial/binding-advanced.html">Advanced binding</a>
</small>
</div>
<div>
<small>
<a href="binding/tutorial/binding-extend.html">Method hooks</a>
</small>
</div>
<div>
<small>
<a href="binding/tutorial/binding-custom.html">Custom code</a>
</small>
</div>
</div>
<div>
<small>
<a href="binding/precompiled.html">Precompiled Bindings</a>
</small>
</div>
<div>
<small>
<a href="binding/binding-overview.html">Definition details</a>
</small>
<div>
<small>
<a href="binding/contexts.html">Definition contexts</a>
</small>
</div>
<div>
<small>
<a href="binding/conversions.html">Conversions</a>
</small>
<div>
<small>
<a href="binding/date-time.html">Date/time conversions</a>
</small>
</div>
</div>
<div>
<small>
<a href="binding/xml-summary.html">XML summary</a>
</small>
</div>
<div>
<small>
<a href="binding/binding-element.html"><binding> element</a>
</small>
</div>
<div>
<small>
<a href="binding/include-element.html"><include> element</a>
</small>
</div>
<div>
<small>
<a href="binding/format-element.html"><format> element</a>
</small>
</div>
<div>
<small>
<a href="binding/namespace-element.html"><namespace> element</a>
</small>
</div>
<div>
<small>
<a href="binding/mapping-element.html"><mapping> element</a>
</small>
</div>
<div>
<small>
<a href="binding/value-element.html"><value> element</a>
</small>
</div>
<div>
<small>
<a href="binding/structure-element.html"><structure> element</a>
</small>
</div>
<div>
<small>
<a href="binding/collection-element.html"><collection> element</a>
</small>
</div>
<div>
<small>
<a href="binding/binding-attributes.html">Attribute groups</a>
</small>
</div>
</div>
</div>
<div>
<strong>Usage API</strong>
<div>
<small>
<a href="./api/index.html">Runtime JavaDocs</a>
</small>
</div>
</div>
<div>
<strong>Subprojects</strong>
<div>
<small>
<a href="eclipse/index.html">Eclipse Plug-in</a>
</small>
<div>
<small>
<a href="eclipse/index.html">Introduction</a>
</small>
</div>
<div>
<small>
<a href="eclipse/install.html">Install</a>
</small>
</div>
<div>
<small>
<a href="eclipse/usage.html">Usage</a>
</small>
</div>
</div>
<div>
<small>
<a href="jibxws/index.html">JiBX/WS</a>
</small>
</div>
<div>
<small>
<a href="axis2/index.html">Axis2 Usage</a>
</small>
</div>
<div>
<small>
<a href="jibxota/index.html">JiBX/OTA</a>
</small>
</div>
<div>
<small>
<a href="./schema-library/index.html">Schema Library</a>
</small>
</div>
</div>
</div>
</td>
<td>
<div id="bodycol">
<div class="app">
<div class="h3">
<h3><a name="intro">JiBX extras</a></h3>
<p>The <i>/lib/jibx-extras.jar</i> provides a number of
optional (but useful) classes you may want to use in your JiBX work. These
classes are described on this page. To use them, you'll need to include the jar
in your runtime classpath.</p>
</div>
<div class="h3">
<h3><a name="roundtrip">Roundtripping documents</a></h3>
<p>Binding definitions can be complex to construct and verify. It's often useful
to try some tests with a new binding to make sure it's working the way you
expect. In general this is going to require application code to verify that
documents are being marshalled and/or unmarshalled as expected, but you can try
some simple tests just using the code included with JiBX along with your bound
classes.</p>
<p>To support this JiBX includes a pair of classes in the "extras" jar. The
<code>org.jibx.extras.DocumentComparator</code> class provides an easy way of
comparing two XML documents. It uses a pair of parsers to read the documents in
parallel, comparing the streams of components seen from the two documents. The
comparison ignores differences in whitespace separating elements, but treats
whitespace as significant within elements with only character data content. It
also ignores comments and processing instructions included in the documents,
since these are normally not processed by JiBX.</p>
<p>The <code>org.jibx.extras.TestRoundtrip</code> class builds on this support,
using the <code>DocumentComparator</code> to compare the results of a round-trip
conversion. It first unmarshals an input document using your binding definition
and classes, then marshals the resulting object structure to an output document.
It ends with comparing the original documents with the output document, reporting
an error if they down match.</p>
<p>In order to make running a roundtrip test as simple as possible the
<code>TestRoundtrip</code> class is the main class for the jar file. To run a
roundtrip test with your bound classes and a sample XML document file you just
need to go to the root directory of your application class structure and run the
command (as a single line, show split here only for formatting):</p>
<div id="source"><pre>java -jar jibx-root/lib/jibx-extras.jar
org.jibx.extras.TestRoundtrip class-name sample.xml</pre></div>
<p>where <i>jibx-root</i> is the path to the root directory for the JiBX
distribution on your system, <i>class-name</i> is the fully-qualified name
(including the full package
specification, so <i>com.sosnoski.site.Menu</i> to name the <code>Menu</code>
class within the <code>com.sosnoski.site</code> package) for the expected root
unmarshalled object, and <i>sample.xml</i> is the sample document file.</p>
<p>This technique of running <code>TestRoundtrip</code> directly from the jar
only works when all the classes needed by your application are available as
separate class files (rather than jars or such) within a single directory
structure. <code>TestRoundtrip</code> automatically includes the current
execution directory in the classpath for loading your files (along with the
jar files used for the JiBX runtime), so this works well for simple applications.
For applications that need classes from jars or other directories you need to
instead run <code>TestRoundtrip</code> directly using a command line like (on
Unix/Linux; if you're using Windows or MS-DOS you'll need to reverse the slashs
and use ';' instead of ':' as a path separator character):</p>
<div id="source"><pre>java -cp jibx-root/lib/jibx-extras.jar:lib/lib1.jar:lib/lib2.jar:.
class-name sample.xml</pre></div>
<p>This allows you to include any required library files in the classpath you
define for the JVM (in this case <i>lib/lib1.jar</i> and <i>lib/lib2.jar</i>).</p>
<p>You can also use <code>TestRoundtrip</code> in combination with the
<a href="bindonload.html">bind-on-load</a> feature, which can be especially useful when
you're experimenting with binding definitions to use with your classes and
documents. Here's the equivalent to the first of the above command lines, but
this time using the <i>binding.xml</i> binding definition for the test:</p>
<div id="source"><pre>java -cp .:jibx-root/lib/jibx-bind.jar:jibx-root/lib/jibx-extras.jar
org.jibx.binding.Run -b binding.xml org.jibx.extras.TestRoundtrip class-name sample.xml</pre></div>
<p>The direct comparison provided by using <code>DocumentComparator</code> to
match the input document against the output document isn't always an appropriate
test. Some types of binding definition constructs (such as default values, or
unordered child elements) can cause the output to differ from the input even
though both are equivalent in terms of the binding. To handle this type of
situation, <code>TestRoundtrip</code> allows you to supply a third command line
parameter giving the name of a separate comparison document to be matched against
the output. It also allows multiple sets of arguments for testing more than one
binding at a time - see the JavaDocs or source code for details.</p>
<p>If the result of running <code>TestRoundtrip</code> is a successful comparison
it just exits silently. If there's an error in the comparison, it prints out the
error information to the console and saves a copy of the generated output
document as <i>temp.xml</i> in the working directory.</p>
</div>
<div class="h3">
<h3><a name="hashmap">Map handling</a></h3>
<p>Another useful class in <i>jibx-extras.jar</i> supports marshalling and
unmarshalling of <code>java.util.Map</code> instances. This is the
<code>org.jibx.extras.HashMapperStringToComplex</code> class. The support it
provides is limited to maps with <code>java.lang.String</code> keys and
object values with mappings defined by the binding (using <mapping>
elements), and the only flexibility it provides is in choosing the name of the
root element, but it's still useful for many cases. It's also intended as a
sample implementation that can be modified for your own particular requirements.
For more discussion of both this specific code and the use of custom marshallers
and unmarshallers in general, see the binding tutorial section on <a
href="binding/tutorial/binding-custom.html#marunmar"><b>Custom marshallers and unmarshallers</b></a>.</p>
<p>The implementation included in <i>jibx-extras.jar</i> includes some nice
customization features. By subclassing this implementation in your own code you
can override the default names used for the item wrapper element and the key
attribute, as well as control whether an item count is included and the name
used for that attribute if so. There's also an alternative handler for maps with
value objects that correspond to simple schema types (such as
<code>java.lang.String</code>, <code>java.lang.Integer</code>,
<code>java.util.Date</code>, etc.). This is the
<code>org.jibx.extras.HashMapperStringToSchemaTyp</code> class. See the <a
href="./api/index.html">Javadocs</a> for details on both of these classes.</p>
</div>
<div class="h3">
<h3><a name="ididref">ID and IDREF handlers</a></h3>
<p>The <code>org.jibx.extras.IdRefMapperBase</code> and
<code>org.jibx.extras.IdDefRefMapperBase</code> classes support special handling
of objects using ID and IDREFs. These differ from the other classes in
<i>jibx-extras.jar</i> in that they're abstract base classes which need to be
subclassed by the user in order to construct usable marshaller/unmarshallers.
The flexibility they provide is often worth the extra effort, though.</p>
<p><code>org.jibx.extras.IdRefMapperBase</code> lets you use IDREF values
directly in a collection, which is not supported by the basic JiBX code. It
expects the XML structure for each item to be an element with no content and a
single attribute giving the IDREF value (like <b><item ref="abcd"/></b>). When a
subclass is used as the marshaller/unmarshaller for a structure within a
collection the referenced objects will be converted to and from the XML IDREF
representation. Subclasses can also be used as marshaller/unmarshallers outside
of a collection, but in this case you could just as easily use an IDREF value
directly. This class only works with IDREF values which have been defined before
the point of reference.</p>
<p><code>org.jibx.extras.IdDefRefMapperBase</code> is even more flexible.
Subclasses can be used as marshaller/unmarshallers which will use a smart
representation for objects, marshalling the full XML expression of an object the
first time it's referenced and thereafter using only an IDREF representation
(and unmarshalling the same type of structure).</p>
<p>Both of these classes define an abstract method which must be implemented by
subclasses. The abstract method links the base class code to a particular object
type, allowing the base code to load the ID value from an object instance. You
can also override another method to control the name of the ID/IDREF attribute.
See the <a href="./api/index.html">Javadocs</a> for details on both of these classes.</p>
</div>
<div class="h3">
<h3><a name="versioning">Versioned bindings</a></h3>
<p>The <code>org.jibx.extras.BindingSelector</code> class supports marshalling
and unmarshalling documents with different binding versions.
As with the above classes, the support it provides
is limited but useful. In the case of <code>BindingSelector</code>, the root
element of the document needs to have some attribute that identifies
the particular version used for a document. The version attribute value is used
to select the binding to be applied when unmarshalling a document, and a supplied
version can also be used when marshalling a document. See the binding tutorial
section on <a href="binding/tutorial/binding-custom.html#frontend"><b>Controlling JiBX with front-end
code</b></a> for full details.</p>
</div>
<div class="h3">
<h3><a name="docmods">Using document models</a></h3>
<p>The extras also include marshaller/unmarshaller classes that allow you to
use document models for portions of your documents. This can be useful in
situations where documents can contain extension information that's not well
structured, or where you need to work with XML document components (such as
comments or processing instructions) that are not easily handled with data
binding. The classes included currently support <b>dom4j</b> and <b>W3C DOM</b>
models.</p>
<p>The <b>dom4j</b> support is provided by the
<code>org.jibx.extras.Dom4JElementMapper</code> and
<code>org.jibx.extras.Dom4JListMapper</code> marshaller/unmarshaller classes.
To make use of these you'll need to separately download the <b>dom4j</b>
library from the <a href="http://dom4j.org/">project web site</a>, since this is
an optional add-on that's not included in the JiBX distribution. The classes
have been tested using dom4j release 1.4, but should be compatible
with both older and future versions since the dom4j APIs are stable.</p>
<p><code>Dom4JElementMapper</code> works with a single element, which may be
optional or required in your binding definition. When unmarshalling
it creates an instance of <code>org.dom4j.Element</code> to hold the content
of that element, and when marshalling it requires that the object you supply
is of that type. If you specify an element name when you use this in your
binding definition that name will be matched when unmarshalling.</p>
<p><code>Dom4JListMapper</code> works with a linked object type that implements
java.util.List (the actual runtime type - as with <code>Dom4JElementMapper</code>
the declared type in your binding definition is ignored and can be anything).
When unmarshalling it will create an instance of <code>java.util.ArrayList</code>
if a list is not passed in and any content is present, then return with all the
content up to the close tag for the enclosing element added to the list as the
appropriate types of dom4j components. When marshalling, it will simply write
out any content in the list you provide directly (where the items in the list
must be dom4j components).</p>
<p>The <b>DOM</b> support is provided by the
<code>org.jibx.extras.DomElementMapper</code>,
<code>org.jibx.extras.DomListMapper</code>, and
<code>org.jibx.extras.DomFragmentMapper</code> marshaller/unmarshaller classes.
These all make use of the JAXP API support included in recent version of the
Java platform. They have been tested with the version of JAXP included with the
Java 1.4.2 JRE from Sun Microsystems, but should be compatible with most
versions of JAXP (despite being a "standard extension", versions of JAXP have
been known to include broken code and/or incompatibilities between versions; it
was used in this case mainly because it's bundled with the JRE and does not
require a separate download).</p>
<p><code>DomElementMapper</code> works with a single element, which may be
optional or required in your binding definition. When unmarshalling
it creates an instance of <code>org.w3c.dom.Element</code> to hold the content
of that element, and when marshalling it requires that the object you supply
is of that type. If you specify an element name when you use this in your
binding definition that name will be matched when unmarshalling. Since the DOM
API requires that each document component belongs to a particular document, this
will create a <code>org.w3c.dom.Document</code> each time an instance of this
marshaller/unmarshaller class is created.</p>
<p><code>DomListMapper</code> works with a linked object type that implements
<code>java.util.List</code> (the actual runtime type - as with the other
marshaller/unmarshaller classes in this group the declared type in your binding
definition is ignored and can be anything), while <code>DomFragmentMapper</code>
works with an instance of <code>org.w3c.dom.DocumentFragment</code>. When
unmarshalling, each of these will create an instance of the appropriate type
(using <code>java.util.ArrayList</code> for <code>DomListMapper</code>)
if one is not passed in and any content is present, then return with all the
content up to the close tag for the enclosing element added to that instance as
the appropriate types of DOM components. When marshalling, they will simply
write out any content in the list or fragment you provide directly (where the
items in the list must be DOM components). As with <code>DomElementMapper</code>,
these will create a <code>org.w3c.dom.Document</code> each time an instance of
the marshaller/unmarshaller class is created.</p>
</div>
<div class="h3">
<h3><a name="docout">Document model output</a></h3>
<p>The extras jar includes an alternative to the standard output
writers that instead of marshalling into an OutputStream or Writer
creates a document model. Currently there is an implementation for JDOM,
although other implementations like dom4j and W3C DOM are possible.</p>
<p>In order to use the JDOM implementation JDOMWriter you need to put
jdom.jar into your classpath. You should use release 1.0 available from
http://www.jdom.org/.</p>
<p>There a three different usage patterns for JDOMWriter. The first one is
the equivalent of marshalling into e.g. a StringWriter. It creates a new
JDOM Document on every run:</p>
<div id="source"><pre> IBindingFactory bfact = BindingDirectory.getFactory(clazz);
IMarshallingContext mctx = bfact.createMarshallingContext();
JDOMWriter jdomWriter = new JDOMWriter(mctx.getNamespaces());
mctx.setXmlWriter(jdomWriter);
mctx.marshalDocument(example);
mctx.endDocument();
Document document = jdomWriter.getDocument();</pre></div>
<p>(You need to change "clazz" and "example" of course.)</p>
<p>The other two possibilities are appending to an existing Document's root
node or to an existing Element (possibly deeply nested within a
Document). The only thing that changes in the code fragment above is the
JDOMWriter constructor you need to use. You need to pass it your
existing Document or Element instance as second parameter.</p>
<p>The resulting Document can be used as you like. Refer to the JDOM
documentation for more information. Wrapping it into a JDOMSource e.g.
could be the input to a XSLT transformation.</p>
</div>
</div>
</div>
</td>
</tr>
</tbody>
</table>
<div id="footer">
<table border="0" cellspacing="0" cellpadding="4">
<tbody>
<tr>
<td> © 2003-2011, Dennis M. Sosnoski (<a href="http://www.sosnoski.co.nz">Sosnoski Software Associates Ltd</a>).
Licensed to the JiBX Project for free distribution and use. </td>
</tr>
</tbody>
</table>
</div>
<br>
</body>
</html>
|
