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
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<title>JiBX: Attribute Groups</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: Attribute Groups</h1>
</td>
<td>
<div align="right" id="login"><a href="http://sourceforge.net">
<img src="http://sourceforge.net/sflogo.php?group_id=69358&type=5"
width="210" height="62" border="0" alt="SourceForge.net Logo"></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="http://wiki.jibx.org">Wiki</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="../flexibility.html">Flexibility</a>
</small>
</div>
<div>
<small>
<a href="../performance.html">Performance</a>
</small>
</div>
<div>
<small>
<a href="../clean-code.html">Clean code</a>
</small>
</div>
</div>
<div>
<small>
<a href="../status.html">News and Status</a>
</small>
</div>
<div>
<small>
<a href="../comments.html">User Comments</a>
</small>
</div>
<div>
<small>
<a href="../bugs.html">Bugs</a>
</small>
</div>
<div>
<small>
<a href="../start.html">Getting Started</a>
</small>
<div>
<small>
<a href="../tutorial/binding-tutorial.html">Binding Tutorial</a>
</small>
<div>
<small>
<a href="../tutorial/binding-start.html">A basic binding</a>
</small>
</div>
<div>
<small>
<a href="../tutorial/binding-extras.html">Binding extras</a>
</small>
</div>
<div>
<small>
<a href="../tutorial/binding-structures.html">Structure mapping</a>
</small>
</div>
<div>
<small>
<a href="../tutorial/binding-collects.html">Collections</a>
</small>
</div>
<div>
<small>
<a href="../tutorial/binding-mappings.html">Using mappings</a>
</small>
</div>
<div>
<small>
<a href="../tutorial/binding-advanced.html">Advanced binding</a>
</small>
</div>
<div>
<small>
<a href="../tutorial/binding-extend.html">Method hooks</a>
</small>
</div>
<div>
<small>
<a href="../tutorial/binding-custom.html">Custom code</a>
</small>
</div>
</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>
<a href="../extras.html">JiBX Extras</a>
</small>
</div>
<div>
<small>
<a href="../building.html">Building JiBX</a>
</small>
</div>
</div>
<div>
<small>
<a href="../schema.html">Schema Compatibility</a>
</small>
</div>
<div>
<small>
<a href="../mail-lists.html">Mailing Lists</a>
</small>
</div>
<div>
<small>
<a href="../faq.html">FAQ</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>
<strong>Binding Definition</strong>
<div>
<small>
<a href="binding-overview.html">Definition details</a>
</small>
<div>
<small>
<a href="contexts.html">Definition contexts</a>
</small>
</div>
<div>
<small>
<a href="conversions.html">Conversions</a>
</small>
</div>
<div>
<small>
<a href="xml-summary.html">XML summary</a>
</small>
</div>
<div>
<small>
<a href="binding-element.html"><binding> element</a>
</small>
</div>
<div>
<small>
<a href="include-element.html"><include> element</a>
</small>
</div>
<div>
<small>
<a href="format-element.html"><format> element</a>
</small>
</div>
<div>
<small>
<a href="namespace-element.html"><namespace> element</a>
</small>
</div>
<div>
<small>
<a href="mapping-element.html"><mapping> element</a>
</small>
</div>
<div>
<small>
<a href="value-element.html"><value> element</a>
</small>
</div>
<div>
<small>
<a href="structure-element.html"><structure> element</a>
</small>
</div>
<div>
<small>
<a href="collection-element.html"><collection> element</a>
</small>
</div>
<div>
<small>
<span class="menu-selection">Attribute groups</span>
</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="../jibxtools/index.html">Generator Tools</a>
</small>
</div>
<div>
<small>
<a href="../jibxsoap/index.html">JibxSoap</a>
</small>
</div>
<div>
<small>
<a href="../siteamatic/index.html">SiteAMatic</a>
</small>
</div>
<div>
<small>
<a href="../xsd2jibx/index.html">Xsd2Jibx</a>
</small>
</div>
</div>
</div>
</td>
<td>
<div id="bodycol">
<div class="app">
<div class="h3">
<h3><a name="elements">Attribute Groups</a></h3>
<pThese are the groups of attribute values that are shared between
different element types:</p>
<ul>
<li><a href="#style">style</a> - controls simple value style (as attribute or
element)</li>
<li><a href="#name">name</a> - defines XML attribute or element name</li>
<li><a href="#object">object</a> - provides options for Java object handling</li>
<li><a href="#property">property</a> - controls how a value is accessed from a
Java object</li>
<li><a href="#structure">structure</a> - define ordering and reuse of lists of
child binding components</li>
<li><a href="#string">string</a> - define conversions between Java property
values and text representations</li>
</ul>
<p>All these attributes are optional unless stated otherwise.</p>
<h4><a name="style">style</a></h4>
<table cellpadding="3" cellspacing="2" border="1" width="100%">
<tr class="b">
<td>value-style</td>
<td><p>Defines the binding style for simple values. The allowed values are
"element" (values as child elements with only text content) or
"attribute" (values as attributes).</p></td>
</tr>
</table>
<h4><a name="name">name</a></h4>
<table cellpadding="3" cellspacing="2" border="1" width="100%">
<tr class="b">
<td>name</td>
<td><p>Local (unqualified) name of element or attribute.</p></td>
</tr>
<tr class="a">
<td>ns</td>
<td><p>Gives the namespace URI for the element or attribute name. If this is
not used the default value is the innermost default namespace for this type,
if any.</p></td>
</tr>
</table>
<h4><a name="object">object</a></h4>
<table cellpadding="3" cellspacing="2" border="1" width="100%">
<tr class="b">
<td>factory</td>
<td><p>Defines a factory method for constructing new instances of an object
type. This applies to bindings for unmarshalling only, and if supplied it must
be in the form of a fully-qualified class and method name (e.g.,
"com.sosnoski.jibx.ObjectBuilderFactory.newInstance" specifies
the newInstance() method of the ObjectBuilderFactory class in the
com.sosnoski.jibx package) for a static method returning
an instance of the bound class. As with the other methods in this group
(<b>pre-set</b>, <b>post-set</b>, and <b>pre-get</b>), three different method
signatures are allowed: No arguments; a single argument of type
<code>java.lang.Object</code>, in which case the owning object is passed in the
method call; or a single argument of type
<code>org.jibx.runtime.IUnmarshallingContext</code>, in which case the
unmarshalling context is passed in the method call (this allows access to the
entire stack of objects being unmarshalled). If not supplied, instances of the
bound class are constructed using a null argument constructor.</p></td>
</tr>
<tr class="a">
<td>pre-set</td>
<td><p>Defines a bound class method called on new instances of the class before
they are populated with data from unmarshalling. This can be used for any
initialization or special handling required before a constructed instance is
used. Three different method signatures are supported, as described in the
<b>factory</b> attribute text.</p></td>
</tr>
<tr class="b">
<td>post-set</td>
<td><p>Defines a bound class method called on instances of the class after
they are populated with data from unmarshalling. This can be used for any
postprocessing or validation required by the class. Three different method
signatures are supported, as described in the <b>factory</b> attribute
text.</p></td>
</tr>
<tr class="a">
<td>pre-get</td>
<td><p>Defines a bound class method called on new instances of the class before
they are marshalled. This can be used for any preprocessing or validation
required by the class. Three different method signatures are supported, as
described in the <b>factory</b> attribute text.</p></td>
</tr>
<tr class="b">
<td>marshaller</td>
<td><p>Defines a custom serialization handler class, as the fully-qualified
name of a class implementing the <code>org.jibx.runtime.Marshaller</code>
interface. This is only allowed with an output binding; it is required if an
unmarshaller is defined for an input-output binding.</p></td>
</tr>
<tr class="a">
<td>unmarshaller</td>
<td><p>Defines a custom deserialization handler class, as the fully-qualified
name of a class implementing the <code>org.jibx.runtime.Unmarshaller</code>
interface. This attribute cannot be used in combination with the <b>factory</b>,
or <b>pre-set</b> attributes. It is only allowed with an input binding; it is
required if a marshaller is defined for an input-output binding.</p></td>
</tr>
</table>
<h4><a name="property">property</a></h4>
<table cellpadding="3" cellspacing="2" border="1" width="100%">
<tr class="b">
<td>field</td>
<td><p>Gives the name of the field within the containing class that supplies the
property value. This is required except for auto-generated identity fields, for
values from a collection, or when both <b>get-method</b> (for output bindings)
and <b>set-method</b> (for input bindings) definitions are supplied.</p></td>
</tr>
<tr class="a">
<td>type</td>
<td><p>Supplies the fully-qualified class name for the property value. This can
be used to force a more specific type for a property value defined by the field
definition or access method signature as either a base class or an interface.</p></td>
</tr>
<tr class="b">
<td>usage</td>
<td><p>Defines the usage requirement for this property. The value can either be
"required" (property is always present, the default if not specified) or
"optional" (property is optional).</p></td>
</tr>
<tr class="a">
<td>test-method</td>
<td><p>Defines a method for checking if an optional property is present in an
instance of the containing class. This is the name of a no-argument method with
return type <code>boolean</code>, which must return <code>true</code> if the
property is present and <code>false</code> if it is not present. This is only
allowed in combination with <b>usage="optional"</b>. If not specified,
a simple <code>==</code> comparison is used with primitive types to check for a
value different from the default, and a <code>equals()</code> comparison for
object types with non-null defaults</p></td>
</tr>
<tr class="b">
<td>get-method</td>
<td><p>Defines a "get" method for retrieving the property value from
an instance of the containing class. This is the name of a no-argument method
returning a value (primitive or object)</p></td>
</tr>
<tr class="a">
<td>set-method</td>
<td><p>Defines a "set" method for storing the property value in
an instance of the containing class. This is the name of a method with return
type <code>void</code>, taking a single value (primitive or object) as a
parameter. If both <b>get-method</b> and <b>set-method</b> are defined, the
<b>set-method</b> parameter type must be the same as the <b>get-method</b>
return value.</p></td>
</tr>
</table>
<h4><a name="structure">structure</a></h4>
<table cellpadding="3" cellspacing="2" border="1" width="100%">
<tr class="b">
<td>ordered</td>
<td><p>Defines whether child binding definitions represent an ordered list
(value "true", the default) or an unordered set ("false"). Only optional child
definitions are allowed within an unordered set.</p></td>
</tr>
<tr class="a">
<td>choice</td>
<td><p>Defines whether child binding definitions represent a choice between
alternatives, with only one allowed (value "true") or a set of possibilities of
which one or more may be present ("false", the default). A "true" value for this
attribute is only allowed when all child definitions are elements (no attributes
or text), and also requires <b>ordered="false"</b>. This attribute is ignored on
a <b>collection</b> element.</p></td>
</tr>
<tr class="b">
<td>label</td>
<td><p>Gives a label allowing the list of child components to be referenced
from elsewhere in the binding definition. <b>Note that this technique has been
deprecated, and will not be supported in JiBX 2.0. In most cases an abstract
mapping can be used as a replacement.</b></p></td>
</tr>
<tr class="a">
<td>using</td>
<td><p>References a list of child components defined elsewhere in the binding
definition. The value must match the <b>label</b> value used on a <b>mapping</b>,
<b>structure</b>, or <b>collection</b> element somewhere in the binding
definition. The child binding components of the referenced element are used as
the content of the element making the reference. The object types associated with the binding definition element making
the reference and that defining the reference must match, and the <b>order</b>
established by the element that defined the reference determines whether the
child definitions are considered as ordered or unordered. The element with this attribute must not have
any child definitions. <b>Note that this technique has been
deprecated, and will not be supported in JiBX 2.0. In most cases an abstract
mapping can be used as a replacement.</b></p></td>
</tr>
</table>
<h4><a name="string">string</a></h4>
<table cellpadding="3" cellspacing="2" border="1" width="100%">
<tr class="b">
<td>default</td>
<td><p>Gives the default value for a conversion. This is only allowed for
optional properties. If not specified, the default for primitive types is the
same as the member variable initial state defined by the JLS, and for object
types is "null".</p></td>
</tr>
<tr class="a">
<td>serializer</td>
<td><p>Defines a custom serialization handler method, as the fully-qualified
name of a static method with the signature <code>String xxxx(Target value)</code>,
where <code>xxxx</code> is the method name and <code>Target</code> is the type
of the property (primitive or object type).</p></td>
</tr>
<tr class="b">
<td>deserializer</td>
<td><p>Defines a custom deserialization handler method, as the fully-qualified
name of a static method with the signature <code>Target xxxx(String text)</code>,
where <code>xxxx</code> is the method name and <code>Target</code> is the type
of the property (primitive or object type). Note that when a custom
deserialization handler method is used for an optional object type with no
default value, that method will be called with a <code>null</code> argument
when the corresponding value is missing in the input document. It's up to the
handler method to handle this case appropriately (by returning either a
<code>null</code> or an object of the expected type).</p></td>
</tr>
</table>
</div>
</div>
</div>
</td>
</tr>
</tbody>
</table>
<div id="footer">
<table border="0" cellspacing="0" cellpadding="4">
<tbody>
<tr>
<td> © 2003-2005, Dennis M. Sosnoski (<a href="http://www.sosnoski.com">Sosnoski Software Solutions, Inc.</a>).
Licensed to the JiBX Project for free distribution and use. </td>
</tr>
</tbody>
</table>
</div>
<br>
</body>
</html>
|
