rdonkin 2003/08/15 23:30:24
Modified: betwixt/xdocs tasks.xml
betwixt/xdocs/guide binding.xml
Log:
Added pluggable Object<->String conversion strategy documentation
Revision Changes Path
1.20 +14 -0 jakarta-commons/betwixt/xdocs/tasks.xml
Index: tasks.xml
===================================================================
RCS file: /home/cvs/jakarta-commons/betwixt/xdocs/tasks.xml,v
retrieving revision 1.19
retrieving revision 1.20
diff -u -r1.19 -r1.20
--- tasks.xml 29 Jul 2003 21:33:31 -0000 1.19
+++ tasks.xml 16 Aug 2003 06:30:24 -0000 1.20
@@ -236,6 +236,15 @@
<strong>Support for converting output strings</strong>
ConvertUtils is now called to convert output strings (as well as input
ones).
</li>
+ <li>
+ <strong>Refactored Object <-> String Conversion</strong>
+ This process has been factored out into a separate pluggable Strategy
class
+ (<code>ObjectStringConverter</code>). A pure <code>ConvertUtils</code>
implementation
+ has been created (<code>ConvertUtilsObjectStringConverter</code>). The
default implementation
+ (<code>DefaultsObjectStringConverter</code>) delegates most conversions
to <code>ConvertUtils</code>
+ but contains a special case that allows the default setting to round
trip java.util.Date's
+ without breaking compatibility.
+ </li>
</ul>
</subsection>
</section>
@@ -352,6 +361,11 @@
<code>ConvertUtils</code> from commons-beanutils is now called to
performt the object to
string conversions. It is possible that in some circumstances, this
change may effect the
output.
+ </li>
+ <li>
+ <strong><code>ConvertUtils</code> conversion now ignored (by
default) for java.util.Date</strong>
+ If you use a custom <code>ConvertUtils</code> java.util.Date
converter then see
+ <a href='guide/binding.html#Converting Dates (And Other
Objects)'>the guide</a>.
</li>
</ul>
</subsection>
1.2 +87 -6 jakarta-commons/betwixt/xdocs/guide/binding.xml
Index: binding.xml
===================================================================
RCS file: /home/cvs/jakarta-commons/betwixt/xdocs/guide/binding.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- binding.xml 14 Aug 2003 21:25:26 -0000 1.1
+++ binding.xml 16 Aug 2003 06:30:24 -0000 1.2
@@ -339,16 +339,97 @@
property is specified then the bean can be written and then read back.
</p>
</subsection>
+</section>
-<subsection name='Using ConvertUtils To Customize Conversion Of Primitives'>
- <p>
+ <section name='Converting Objects And Primitives To Strings (And Back Again)'>
+
+ <subsection name='Using ConvertUtils To Customize Conversion Of Primitives'>
+ <p>
<code>ConvertUtils</code> is part of <a
href='http://jakarta.apache.org/commons/beanutils.html'>commons-beanutils</a>
-and it can be used to flexibly convert strings to objects and back again. Betwixt
uses ConvertUtils to
+and it can be used to flexibly convert strings to objects and back again. By
default, Betwixt uses ConvertUtils to
perform these conversions and so standard <code>ConvertUtils</code> methods can be
called to customize these
conversions.
- </p>
-</subsection>
-
+ </p>
+ </subsection>
+ <subsection name='Converting Dates (And Other Objects)'>
+ <p>
+There are numerous situations when read beans from xml or writing beans to xml that
String to Object
+or Object to String conversions are required. Betwixt uses a <em>Strategy</em>
class to allow a convenient
+default which will work well for most basic users whilst allowing advanced users to
fully hook in and
+customize this process.
+ </p>
+ <p>
+The default strategy uses <code>ConvertUtils</code> from
+<a href='http://jakarta.apache.org/commons/beanutils.html'>commons-beanutils</a> to
perform these conversions.
+This is a powerful component that allows flexible customization of the conversion
process.
+ </p>
+ <p>
+There is one exception to this rule. If the class is a <code>java.util.Date</code>
- or a subclass of <code>java.util.Date</code> which is not a subclass of
<code>java.sql.Date</code>, <code>java.sql.Time</code> or
<code>java.sql.Timestamp</code> - then this is converted to and from a string
following this pattern:
+<code><pre>
+ EEE MMM dd HH:mm:ss zzz yyyy
+</pre></code>
+(using the SimpleDateFormat notation). Observent readers will realise that this is
the same pattern
+that is returned by <code>java.util.Date.toString</code> - and that's why this
pattern was chosen.
+It provides a good default for casual users.
+ </p>
+ <p>
+Advanced users will probably need a particular date format. The recommended way to
do this is through
+registering appropriate converters with ConvertUtils. The default conversion
strategy must also be
+replaced with an instance of
+<a
href='../apidocs/org/apache.commons/betwixt/strategy/ConvertUtilsObjectStringConverter.html'>
+ConvertUtilsObjectStringConverter</a>. This is set though a
<code>BindingConfiguration</code> property.
+ </p>
+ <p>
+For example, to delegate to <code>ConvertUtils</code> for <em>all</em> conversions
in a read:
+<code><pre>
+ BeanReader reader = new BeanReader();
+ reader.getBindingConfiguration(new ConvertUtilsObjectStringConverter());
+ reader.parse...
+</pre></code>
+and in a write:
+<code><pre>
+ BeanWriter writer = new BeanWriter();
+ writer.getBindingConfiguration(new ConvertUtilsObjectStringConverter());
+ writer.write...
+</pre></code>
+ </p>
+ </subsection>
+ <subsection name='Custom ObjectStringConverters (Advanced)'>
+ <p>
+<code>ConvertUtils</code> is flexible and powerful. It comes with a range of
<code>Converter</code>
+implementations which allow quick and easy customization. But, there are occasions
where this will
+not suit all the requirements of the user. Betwixt supports this need by allowing a
custom
+<code>ObjectStringConverter</code> to be plugged in.
+ </p>
+ <p>
+The strategy class
+<a
href='../apidocs/org/apache.commons/betwixt/strategy/ObjectStringConverter.html'>ObjectStringConverter</a>
+is simple: containing only two simple methods. For more information about creating
subclasses, see the javadocs.
+The implementation to be used is set through the <code>BindingConfiguration</code>
+<code>ObjectStringConverter</code> property.
+ </p>
+ <p>
+For example, to set a custom <code>ObjectStringConverter</code> for <em>all</em>
conversions in a read:
+<code><pre>
+ ObjectStringConverter converter = new MyObjectStringConverter();
+ BeanReader reader = new BeanReader();
+ reader.getBindingConfiguration(converter);
+ reader.parse...
+</pre></code>
+and in a write:
+<code><pre>
+ ObjectStringConverter converter = new MyObjectStringConverter();
+ BeanWriter writer = new BeanWriter();
+ writer.getBindingConfiguration(converter);
+ writer.write...
+</pre></code>
+ </p>
+ <p>
+Betwixt is distributed with a range of <code>ObjectStringConverter</code>'s in the
+<code>org.apache.commons.betwixt.strategy</code> package. Examining the source code
for these classes
+is a good please to start when creating your own implementation.
+ </p>
+ </subsection>
</section>
</body>
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
