[Practicalxml-commits] SF.net SVN: practicalxml:[156] branches/dev-1.1/src/main/java/net/sf/ pract
Brought to you by:
kdgregory
Menu
▾
▴
[Practicalxml-commits] SF.net SVN: practicalxml:[156] branches/dev-1.1/src/main/java/net/sf/ practicalxml/converter/bean/package.html
|
From: Auto-Generated S. C. M. <pra...@li...> - 2009-09-24 01:21:23
|
Revision: 156
http://practicalxml.svn.sourceforge.net/practicalxml/?rev=156&view=rev
Author: kdgregory
Date: 2009-09-24 01:21:05 +0000 (Thu, 24 Sep 2009)
Log Message:
-----------
update BeanConverter package docs
Modified Paths:
--------------
branches/dev-1.1/src/main/java/net/sf/practicalxml/converter/bean/package.html
Modified: branches/dev-1.1/src/main/java/net/sf/practicalxml/converter/bean/package.html
===================================================================
--- branches/dev-1.1/src/main/java/net/sf/practicalxml/converter/bean/package.html 2009-09-23 23:42:59 UTC (rev 155)
+++ branches/dev-1.1/src/main/java/net/sf/practicalxml/converter/bean/package.html 2009-09-24 01:21:05 UTC (rev 156)
@@ -29,51 +29,83 @@
<p>
Additional conversion rules are as follows:
-<table border="1">
+<table border="1" >
<tr><th>Java Object Type
- <th>{@link #convertToXml}
- <th>{@link #convertToJava}
+ <th>Java to XML
+ <th>XML to Java
+<tr><td>Null Values
+ <td>By default, any field containing a null value is ignored and not
+ written to the output.
+ <td>By default, any element that does not contain a Text child is treated
+ as <code>null</code>, and ignored (because bean fields should already
+ be null at construction). Optionally requires an <code>xsi:nil</code>
+ attribute for values that are legally null, and throws if an empty
+ element appears without it.
<tr><td>Primitives, Wrapper objects, and String
- <td>
- <td>
+ <td>By default, calls <code>toString()</code> on the object; optionally
+ uses a Schema-compliant formatter (only applies to dates and floating
+ point numbers).
+ <td>Uses the built-in parsers for the destination type, except where
+ instructed to use Schema-compliant parsing.
<tr><td>Arrays
- <td>Elements of the array are written in sequence to the DOM, using the
- element name "<code>data</code>". Elements are given an attribute
- named "<code>index</code>", which contains the element's position
- within the array.
- <td>Elements of the array are processed in sequence, ignoring both
- element name and "index" attribute.
+ <td>By default, arrays are converted using one "container" element to
+ represent the array, and multiple children of that container to
+ represent the elements in the array. The container element is named
+ after the field being converted. By default, the child elements are
+ named "data", but optionally may be named after the field or a
+ depluralized version of the field (eg, if the field is named "widgets"
+ the child elements may be named "widgets" or "widget" depending on
+ options).
+ <p>
+ An alternate option is to output the array's elements directly, as
+ repeated elements named after the field, without a "container" element
+ (eg, if a bean has a field named "widgets" with 3 elements, then the
+ XML produced from that bean will have three Elements named "widgets",
+ each of which contains the data from the corresponding array element).
+ <p>
+ Elements may also be given an "index" attribute, holding their index
+ within the array (numbered from 0). This attribute is not output by
+ default, as its chief use is self-documenting data.
+ <td>The DOM must have a "container" element; the children of this element
+ become the elements of the array. The names of the children are ignored,
+ as is any "index" attribute. The children are converted according to the
+ base element type of the array.
<tr><td>Lists and Sets
- <td>The collection is iterated, and elements are written in sequence to
- the DOM, using the element name "<code>data</code>". Elements are
- given an attribute named "<code>index</code>", which contains the
- element's position within the iteration (meaningful only for lists).
- <td>Elements of the are processed in sequence, ignoring both element
- name and "index" attribute.
+ <td>The collection is written as if it were an array (qv). Child elements are
+ output in iterator order.
+ <td>The collection is processed as it if were an array (qv), with one (major)
+ difference: since all collections inherently contain Objects, there is no
+ type information to drive conversion. If an <code>xsi:type</code> attribute
+ is present, it will be used to drive conversion. Otherwise, the element will
+ be converted as a <code>String</code> (which will fail for complex types,
+ because string conversion assumes a single text node).
<p>
- If an <code>xsi:type</code> attribute is present, it will be used
- to drive conversion of the element. Otherwise, the element will be
- converted as a <code>String</code> (which will fail for complex
- types, because string conversion assumes a single text node).
- <p>
Where the caller specifies an interface as the conversion class, the
converter will choose an appropriate implementation class:
<ul>
<li> <code>ArrayList</code> for <code>List</code> or <code>Collection</code>
<li> <code>TreeSet</code> for <code>SortedSet</code>
- <li> <code>HashSet</code> for <code>Set</code>
+ <li> <code>HashSet</code> for all other <code>Set</code>s
</ul>
<tr><td>Maps
- <td>The collection is iterated, and elements are written in sequence to
- the DOM. Depending on the output options, either the entry key will
- be used as the element name, or the name will be "<code>data</code>"
- and the key stored in an attribute named "<code>key</code>". The
- former option is only permitted if all keys in the map are valid
- XML element names; otherwise the converter will throw.
- <td>Elements are processed in sequence. The converter first looks for
- a "<code>key</code>" attribute, and will use it as the entry key
- if found. Otherwise, it will use the element name. If your maps
- are being reduced to a single entry, look for a missing attribute.
+ <td>The map itself is represented by a "container" element, which holds one
+ child per map entry. The map's entry-set is iterated, and children are
+ emitted in the order of this iteration.
+ <p>
+ By default, child elements have the name "<code>data</code>", with an
+ attribute "<code>key</code>" that contains the key used to reference
+ the item in the map. Optionally, the map key may be used as the element
+ name, meaning that the output of a map is indistinguishable from that
+ of a bean. However, if this option is used, all map keys must be valid
+ XML element names, or the converter will throw.
+ <td>The converter expects a "container" element with one child per map
+ entry. Elements are processed in sequence, which means that later
+ elements with the same key value will overwrite earlier elements.
+ <p>
+ When processing an element, the converter first looks for an attribute
+ named "<code>key</code>", and will use it as the entry key if found.
+ Otherwise, it will use the element name. If your maps are being reduced
+ to a single entry, look for a missing attribute.
<p>
If an <code>xsi:type</code> attribute is present, it will be used
to drive conversion of the element. Otherwise, the element will be
@@ -82,11 +114,21 @@
<p>
Where the caller specifies an interface as the conversion class,
the converter will choose an appropriate implementation class:
- <code>TreeMap</code> for <code>SortedMap</code>, and <code>HashMap
- </code> for <code>Map</code>.
+ <ul>
+ <li> <code>TreeMap</code> for <code>SortedMap</code>
+ <li> <code>HashMap</code> for all other <code>Map</code>s
+ </ul>
<tr><td>Bean-structured Objects
<td>The object is introspected, and properties are written in the order
- provided by the <code>Introspector</code>.
+ provided by the <code>Introspector</code>. Note that this means you
+ can't validate beans against a schema, as the order of elements may
+ change.
+ <p>
+ <strong>Warning</strong>:
+ Bean-to-XML conversion uses <code>java.beans.Introspector</code>, which
+ holds a cache of introspected objects. If you use this conversion in an
+ app-server you should call <code>Introspector.flushCaches()</code> during
+ deploy.
<td>The bean class must provide a no-argument constructor (otherwise it
doesn't follow the bean spec, and we can't use it).
<p>
@@ -109,11 +151,5 @@
<td>not supported
</table>
-<strong>Warning</strong>:
-Bean-to-XML conversion uses <code>java.beans.Introspector</code>, which
-holds a cache of introspected objects. If you use this conversion in an
-app-server you should call <code>Introspector.flushCaches()</code> during
-deploy.
-
</body>
</html>
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
