svn commit: r1513324 - /commons/sandbox/convert/trunk/src/site/xdoc/index.xml

[adrianc]

Author: adrianc
Date: Tue Aug 13 02:17:11 2013
New Revision: 1513324

URL: http://svn.apache.org/r1513324
Log:
Added a Getting Started section to the web site main page.

Modified:
    commons/sandbox/convert/trunk/src/site/xdoc/index.xml

Modified: commons/sandbox/convert/trunk/src/site/xdoc/index.xml
URL: 
http://svn.apache.org/viewvc/commons/sandbox/convert/trunk/src/site/xdoc/index.xml?rev=1513324&r1=1513323&r2=1513324&view=diff
==============================================================================
--- commons/sandbox/convert/trunk/src/site/xdoc/index.xml (original)
+++ commons/sandbox/convert/trunk/src/site/xdoc/index.xml Tue Aug 13 02:17:11 
2013
@@ -59,6 +59,43 @@ or any application that needs to convert
 </subsection>
 </section>
 
+<section name="Getting Started">
+<p>
+Most Java applications will require data type conversion, and typically those 
conversions are hard-coded in
+the application on an as-needed basis. As an application grows, so do the 
number of hard-coded conversions. In time,
+you end up with duplicate code or duplicate conversions that behave 
differently depending on where they appear in code.
+Things get worse in enterprise-class applications where data is being 
exchanged between dissimilar systems
+and data type conversion gets really complicated.
+</p>
+<p>
+A better approach would be to start off with a conversion library like 
<b>Commons Convert</b> that will
+accommodate the handful of conversions required by a small application, as 
well as the complicated,
+difficult-to-foresee conversions required by an enterprise-class application. 
The easiest and most scalable
+way to set up conversions is to create a facade or adapter:<br/><br/>
+<code>
+public static Object convertTo(Object sourceObject, Class&lt;?&gt; 
targetClass) throws ClassNotFoundException, ConversionException {<br/>
+&nbsp;&nbsp;&nbsp;&nbsp;Converter&lt;Object, Object&gt; converter = 
Converters.getConverter(sourceObject.getClass(), targetClass);<br/>
+&nbsp;&nbsp;&nbsp;&nbsp;return converter.convert(sourceObject);<br/>
+}
+</code><br/><br/>
+The application delegates all conversions to the static method.
+</p>
+<p>
+Some conversions require a locale and/or time zone. The facade can be improved 
to accommodate
+localized conversions:<br/><br/>
+<code>
+public static Object convertTo(Object sourceObject, Class&lt;?&gt; 
targetClass, Locale locale, TimeZone timezone) throws ClassNotFoundException, 
ConversionException {<br/>
+&nbsp;&nbsp;&nbsp;&nbsp;Converter&lt;Object, Object&gt; converter = 
Converters.getConverter(sourceObject.getClass(), targetClass);<br/>
+&nbsp;&nbsp;&nbsp;&nbsp;if (converter instanceof LocalizedConverter) {<br/>
+&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;LocalizedConverter&lt;Object, 
Object&gt; localizedConverter = (LocalizedConverter) converter;<br/>
+&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;return 
localizedConverter.convert(sourceObject, locale, timeZone);<br/>
+&nbsp;&nbsp;&nbsp;&nbsp;} else {<br/>
+&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;return 
converter.convert(sourceObject);<br/>
+&nbsp;&nbsp;&nbsp;&nbsp;}<br/>
+}
+</code>
+</p>
+</section>
 
 <section name="Documentation">
 <p>
@@ -69,7 +106,6 @@ or any application that needs to convert
 </p>
 </section>
 
-
 <section name="Releases">
 <p>
 None. This is a <i>sandbox</i> component.