<html><head><META http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Type Support</title><link href="default.css" rel="stylesheet"></head><body marginwidth="0" marginheight="0" leftmargin="0" bottommargin="0" topmargin="0" vlink="#6763a9" link="#6763a9" bgcolor="#ffffff"><a name="top"></a><table height="400" cellspacing="0" cellpadding="0" border="0"><tr><td bgcolor="#7270c2" align="left" valign="top" width="10"><img border="0" height="1" width="1" src="images/dotTrans.gif"></td><td bgcolor="#7270c2" align="left" valign="top" width="150"><img border="0" height="1" width="1" src="images/dotTrans.gif"></td><td align="left" valign="top" width="7"><img height="1" width="1" border="0" src="images/dotTrans.gif"></td><td align="left" valign="top" width="70"><img border="0" height="6" width="70" src="images/dotTrans.gif"></td><td align="left" valign="top" width="100%"><img border="0" height="6" width="100%" src="images/top_2.gif"></td></tr><tr><td align="left" valign="top" bgcolor="#7270c2" width="10"><img height="1" width="1" border="0" src="images/dotTrans.gif"></td><td align="left" valign="top" bgcolor="#7270c2" width="150"><img height="1" width="1" border="0" src="images/dotTrans.gif"></td><td align="left" valign="top" bgcolor="#ffffff" width="7"></td><td align="left" valign="top" width="70"><img border="0" height="1" width="1" src="images/dotTrans.gif"></td><td align="left" valign="middle" width="100%"><a href="license.html"><span class="menuTopOff">License</span></a> <a href="http://www.codehaus.org"><span class="menuTopOff">Codehaus</span></a> <a href="http://openejb.org"><span class="menuTopOff">OpenEJB</span></a> <a href="http://openjms.sf.net"><span class="menuTopOff">OpenJMS</span></a> <a href="http://openorb.sf.net"><span class="menuTopOn">OpenORB</span></a> <a href="http://tyrex.sf.net"><span class="menuTopOff">Tyrex</span></a> <br><img border="0" height="2" width="1" src="images/dotTrans.gif"></td></tr><tr><td align="left" valign="top" bgcolor="#7270c2" width="10"><img border="0" height="3" width="10" src="images/dotTrans.gif"></td><td align="right" valign="top" bgcolor="#7270c2" width="150"><img border="0" height="3" width="105" src="images/line_sm.gif"></td><td align="left" valign="top" bgcolor="#a9a5de" width="7"><img border="0" height="3" width="7" src="images/line_sm.gif"></td><td align="left" valign="top" width="70"><img border="0" height="3" width="70" src="images/line_light.gif"></td><td align="left" valign="top" width="100%"><img border="0" height="3" width="100%" src="images/line_light.gif"></td></tr><tr><td align="left" valign="top" bgcolor="#7270c2"><img border="0" height="10" width="10" src="images/dotTrans.gif"></td><td align="left" valign="top" bgcolor="#7270c2" width="150"><img border="0" height="2" width="1" src="images/dotTrans.gif"><br><table cellspacing="0" cellpadding="10" border="0"><tr><td><script src="http://www.ohloh.net/p/3635/widgets/project_users_logo.js" type="text/javascript"></script></td></tr></table><table cellspacing="0" cellpadding="0" border="0"><tr><td align="left" valign="top"><span class="subMenuOn">Old releases</span></td></tr><tr><td align="left" valign="top">
<a href="releases-old.html"><span class="subMenuOff">General</span></a></td></tr><tr><td align="left" valign="top">
<a href="http://www.castor.org/1.3/index.html"><span class="subMenuOff">Release 1.3</span></a></td></tr><tr><td align="left" valign="top">
<a href="http://www.castor.org/1.3rc1/index.html"><span class="subMenuOff">Release 1.3rc1</span></a></td></tr><tr><td align="left" valign="top">
<a href="http://www.castor.org/1.2/index.html"><span class="subMenuOff">Release 1.2</span></a></td></tr></table><br><table cellspacing="0" cellpadding="0" border="0"><tr><td align="left" valign="top"><span class="subMenuOn">Main</span></td></tr><tr><td align="left" valign="top">
<a href="index.html"><span class="subMenuOff">Home</span></a></td></tr><tr><td align="left" valign="top">
<a href="about.html"><span class="subMenuOff">About</span></a></td></tr><tr><td align="left" valign="top">
<a href="features.html"><span class="subMenuOff">Features</span></a></td></tr><tr><td align="left" valign="top">
<a href="download.html"><span class="subMenuOff">Download</span></a></td></tr><tr><td align="left" valign="top">
<a href="dependencies.html"><span class="subMenuOff">Dependencies</span></a></td></tr><tr><td align="left" valign="top">
<a href="reference-guide.html"><span class="subMenuOffHighlighted">Reference guide</span></a></td></tr><tr><td align="left" valign="top">
<a href="presentations.html"><span class="subMenuOff">Publications</span></a></td></tr><tr><td align="left" valign="top">
<a href="javadoc/overview-summary.html"><span class="subMenuOff">JavaDoc</span></a></td></tr><tr><td align="left" valign="top">
<a href="maven-integration.html"><span class="subMenuOff">Maven 2 support</span></a></td></tr><tr><td align="left" valign="top">
<a href="maven-archetypes.html"><span class="subMenuOff">Maven 2 archetypes</span></a></td></tr><tr><td align="left" valign="top">
<a href="schema.html"><span class="subMenuOff">DTD & Schemas</span></a></td></tr><tr><td align="left" valign="top">
<a href="changes.html"><span class="subMenuOff">Recent HTML changes</span></a></td></tr><tr><td align="left" valign="top">
<a href="news.html"><span class="subMenuOff">News Archive</span></a></td></tr><tr><td align="left" valign="top">
<a href="http://castor.codehaus.org/rss/castor-announce.xml"><span class="subMenuOff">RSS news feed</span></a></td></tr><tr><td align="left" valign="top">
<a href="http://docs.codehaus.org/display/CASTOR/"><span class="subMenuOffHighlighted">Project Wiki</span></a></td></tr></table><br><table cellspacing="0" cellpadding="0" border="0"><tr><td align="left" valign="top"><span class="subMenuOn">Development/Support</span></td></tr><tr><td align="left" valign="top">
<a href="lists.html"><span class="subMenuOff">Mailing Lists</span></a></td></tr><tr><td align="left" valign="top">
<a href="scm.html"><span class="subMenuOff">SVN/JIRA</span></a></td></tr><tr><td align="left" valign="top">
<a href="contributing.html"><span class="subMenuOff">Contributing</span></a></td></tr><tr><td align="left" valign="top">
<a href="support.html"><span class="subMenuOff">Support</span></a></td></tr><tr><td align="left" valign="top">
<a href="http://bamboo.ci.codehaus.org/browse/CASTOR"><span class="subMenuOff">Continuous builds</span></a></td></tr><tr><td align="left" valign="top">
<a href="professional-services.html"><span class="subMenuOffHighlighted">Prof. services</span></a></td></tr></table><br><table cellspacing="0" cellpadding="0" border="0"><tr><td align="left" valign="top"><span class="subMenuOn">Related projects</span></td></tr><tr><td align="left" valign="top">
<a href="spring-orm-integration.html"><span class="subMenuOff">Spring ORM support</span></a></td></tr><tr><td align="left" valign="top">
<a href="spring-xml-intro.html"><span class="subMenuOff">Spring XML factories</span></a></td></tr><tr><td align="left" valign="top">
<a href="ws-integration.html"><span class="subMenuOff">WS frameworks</span></a></td></tr></table><br><table cellspacing="0" cellpadding="0" border="0"><tr><td align="left" valign="top"><span class="subMenuOn">XML</span></td></tr><tr><td align="left" valign="top">
<a href="xml-link.html"><span class="subMenuOff">XML</span></a></td></tr></table><br><table cellspacing="0" cellpadding="0" border="0"><tr><td align="left" valign="top"><span class="subMenuOn">XML Code Generator</span></td></tr><tr><td align="left" valign="top">
<a href="srcgen-link.html"><span class="subMenuOff">XML Code Generator</span></a></td></tr></table><br><table cellspacing="0" cellpadding="0" border="0"><tr><td align="left" valign="top"><span class="subMenuOn">JDO</span></td></tr><tr><td align="left" valign="top">
<a href="jdo-introduction.html"><span class="subMenuOff">Introduction</span></a></td></tr><tr><td align="left" valign="top">
<a href="jdo-starter-tutorial.html"><span class="subMenuOff">First steps</span></a></td></tr><tr><td align="left" valign="top">
<a href="jdo.html"><span class="subMenuOff">Using JDO</span></a></td></tr><tr><td align="left" valign="top">
<a href="jdo-database-conf.html"><span class="subMenuOff">JDO Config</span></a></td></tr><tr><td align="left" valign="top">
<a href="types.html"><span class="subMenuOff">Types</span></a></td></tr><tr><td align="left" valign="top">
<a href="jdo-mapping.html"><span class="subMenuOff">JDO Mapping</span></a></td></tr><tr><td align="left" valign="top">
<a href="jdo-faq.html"><span class="subMenuOff">JDO FAQ</span></a></td></tr><tr><td align="left" valign="top">
<a href="jdo-examples.html"><span class="subMenuOff">JDO Examples</span></a></td></tr><tr><td align="left" valign="top">
<a href="jdo-howto.html"><span class="subMenuOffHighlighted">JDO HOW-TOs</span></a></td></tr><tr><td align="left" valign="top">
<a href="jdo-tips-tricks.html"><span class="subMenuOffHighlighted">Tips & Tricks</span></a></td></tr><tr><td align="left" valign="top">
<a href="jdo-other-features.html"><span class="subMenuOff">Other Features</span></a></td></tr><tr><td align="left" valign="top">
<a href="jdo-self-executable-examples.html"><span class="subMenuOff">JDO sample JAR</span></a></td></tr></table><br><table cellspacing="0" cellpadding="0" border="0"><tr><td align="left" valign="top"><span class="subMenuOn">Tools</span></td></tr><tr><td align="left" valign="top">
<a href="schemaGen-anttask.html"><span class="subMenuOff">Schema generator</span></a></td></tr></table><br><table cellspacing="0" cellpadding="0" border="0"><tr><td align="left" valign="top"><span class="subMenuOn">Advanced JDO</span></td></tr><tr><td align="left" valign="top">
<a href="jdo-caching-detail.html"><span class="subMenuOff">Caching</span></a></td></tr><tr><td align="left" valign="top">
<a href="oql.html"><span class="subMenuOff">OQL</span></a></td></tr><tr><td align="left" valign="top">
<a href="locking.html"><span class="subMenuOff">Trans. & Locks</span></a></td></tr><tr><td align="left" valign="top">
<a href="design-persist.html"><span class="subMenuOff">Design</span></a></td></tr><tr><td align="left" valign="top">
<a href="key-generator.html"><span class="subMenuOff">KeyGen</span></a></td></tr><tr><td align="left" valign="top">
<a href="long-transact.html"><span class="subMenuOff">Long Trans.</span></a></td></tr><tr><td align="left" valign="top">
<a href="nested-attr.html"><span class="subMenuOff">Nested Attrs.</span></a></td></tr><tr><td align="left" valign="top">
<a href="jdo-pooling.html"><span class="subMenuOff">Pooling Examples</span></a></td></tr><tr><td align="left" valign="top">
<a href="postgresql-blobs.html"><span class="subMenuOff">LOBs</span></a></td></tr><tr><td align="left" valign="top">
<a href="jdo-best-practice.html"><span class="subMenuOff">Best practice</span></a></td></tr></table><br><table cellspacing="0" cellpadding="0" border="0"><tr><td align="left" valign="top"><span class="subMenuOn">DDL Generator</span></td></tr><tr><td align="left" valign="top">
<a href="ddlgen.html"><span class="subMenuOff">Using DDL Generator</span></a></td></tr><tr><td align="left" valign="top">
<a href="ddlgen-properties.html"><span class="subMenuOff">Properties</span></a></td></tr><tr><td align="left" valign="top">
<a href="ddlgen-anttask.html"><span class="subMenuOff">Ant task</span></a></td></tr><tr><td align="left" valign="top">
<a href="ddlgen-mapping.html"><span class="subMenuOff">Type Mapping</span></a></td></tr></table><br><table cellspacing="0" cellpadding="0" border="0"><tr><td align="left" valign="top"><span class="subMenuOn">More</span></td></tr><tr><td align="left" valign="top">
<a href="examples.html"><span class="subMenuOff">The Examples</span></a></td></tr><tr><td align="left" valign="top">
<a href="extras.html"><span class="subMenuOff">3rd Party Tools</span></a></td></tr><tr><td align="left" valign="top">
<a href="test-framework.html"><span class="subMenuOff">JDO Tests</span></a></td></tr><tr><td align="left" valign="top">
<a href="ctf.html"><span class="subMenuOff">XML Tests</span></a></td></tr><tr><td align="left" valign="top">
<a href="conf-lib.html"><span class="subMenuOff">Configuration</span></a></td></tr><tr><td align="left" valign="top">
<a href=""><span class="subMenuOff"></span></a></td></tr><tr><td align="left" valign="top">
<a href="http://www.java.net/"><span class="subMenuOff"><img border="0" src="images/javanet_button_90.gif"></span></a></td></tr></table><br><table cellspacing="0" cellpadding="0" border="0"><tr><td align="left" valign="top"><span class="subMenuOn">About</span></td></tr><tr><td align="left" valign="top">
<a href="license.html"><span class="subMenuOff">License</span></a></td></tr><tr><td align="left" valign="top">
<a href="user-experience.html"><span class="subMenuOffHighlighted">User stories</span></a></td></tr><tr><td align="left" valign="top">
<a href="contributors.html"><span class="subMenuOff">Contributors</span></a></td></tr><tr><td align="left" valign="top">
<a href="marketplace.html"><span class="subMenuOff">Marketplace</span></a></td></tr><tr><td align="left" valign="top">
<a href="status.html"><span class="subMenuOff">Status, Todo</span></a></td></tr><tr><td align="left" valign="top">
<a href="release-notes.html"><span class="subMenuOff">Changelog</span></a></td></tr><tr><td align="left" valign="top">
<a href="library.html"><span class="subMenuOff">Library</span></a></td></tr><tr><td align="left" valign="top">
<a href="contacts.html"><span class="subMenuOff">Contact</span></a></td></tr><tr><td align="left" valign="top">
<a href="origins.html"><span class="subMenuOff">Project Name</span></a></td></tr></table><br></td><td align="left" valign="top" bgcolor="#a9a5de" width="7"> </td><td align="left" valign="top" width="70"> </td><td valign="top" width="100%" rowspan="4"><table width="100%" cellspacing="0" cellpadding="0" border="0" rows="2" cols="2"><tr><td align="left" valign="top"><br><img width="115" vspace="0" src="images/castor.gif" hspace="0" height="34" border="0"><br><img src="images/dotTrans.gif" hspace="0" height="10" border="0"></td><td align="right" valign="top" height="5" width="120"></td></tr></table><p></p><p></p><br><h2 align="center">Type Support</h2><HR size="1"><span class="bodyGrey"><b><a href="#Types">Types</a></b><br></span><span class="bodyGrey"><a href="#Castor-XML"> Castor XML</a><br></span><span class="bodyGrey"><a href="#Castor-JDO"> Castor JDO</a><br></span><span class="bodyGrey"><a href="#Castor-DAX"> Castor DAX</a><br></span><span class="bodyGrey"><b><a href="#The-Field-Mapping">The Field Mapping</a></b><br></span><span class="bodyGrey"><b><a href="#SQL-Dates-and-Default-Timezones">SQL Dates and Default Timezones</a></b><br></span><span class="bodyGrey"><b><a href="#SQL-Type-Conversion">SQL Type Conversion</a></b><br></span><span class="bodyGrey"><b><a href="#Parameterized-Type-Convertors">Parameterized Type Convertors</a></b><br></span><span class="bodyGrey"><b><a href="#BLOB-and-CLOB-Types">BLOB and CLOB Types</a></b><br></span><HR size="1"><br><a name="Types"><h2>Types</h2></a>
<p><span class="bodyGrey">
The Castor type mechanism assures proper conversion between Java types
and external types.
</span></p>
<a name="Castor-XML"><h3>Castor XML</h3></a>
<p><span class="bodyGrey">
Castor XML converts all Java fields into XML element and attribute
values.
</span></p>
<a name="Castor-JDO"><h3>Castor JDO</h3></a>
<p><span class="bodyGrey">
Castor JDO converts Java fields into SQL columns which are persisted
through the JDBC driver. Due to implementation details, the field
type expected by the JDBC driver is not always the field type defined
for the mapped object.
</span></p>
<p><span class="bodyGrey">
The most common occurrences of mistyping is when using fields of type
<tt>FLOAT</tt>, <tt>DOUBLE</tt>, <tt>NUMERIC</tt>, and
<tt>DECIMAL</tt>. SQL type <tt>FLOAT</tt> actually maps to Java type
<tt>java.lang.Double</tt>. SQL types <tt>NUMERIC</tt> and
<tt>DECIMAL</tt> map to Java type <tt>java.math.BigDecimal</tt>.
</span></p>
<p><span class="bodyGrey">
When such an inconsistency occurs, Castor JDO will throw an
<tt>IllegalArgumentException</tt> during object persistence with a
message indicating the two conflicting types.
</span></p>
<p><span class="bodyGrey">
In order to avoid runtime exceptions, we recommend explicitly
specifying types in the mapping file using the SQL typing convention.
See <a href="#SQL-Type-Conversion">SQL Type Conversion</a>.
</span></p>
<a name="Castor-DAX"><h3>Castor DAX</h3></a>
<p><span class="bodyGrey">
Castor DAX converts all Java fields into LDAP attribute values. LDAP
attribute values are always textual and are represented as the string
value of the field, e.g. "5" or "true".
</span></p>
<p><span class="bodyGrey">
LDAP attributes may also contain binary values. When storing byte
arrays or serialized Java objects, DAX will store them as byte arrays.
</span></p>
<a name="The-Field-Mapping"><h2>The Field Mapping</h2></a>
<p><span class="bodyGrey">
The field element includes an optional attribute called <i>type</i>
which can be used to specify the Java type of the field. This attribute
is optional since Castor can always derive the exact Java type from the
class definition.
</span></p>
<p><span class="bodyGrey">
We highly recommend that developers use the type field in their mapping
file as a means to provide static type checking. When loading a mapping
file, Castor will compare the actual Java type with the type specified
in the mapping and will complain about inconsistencies.
</span></p>
<p><span class="bodyGrey">
The field type can be specified either given the full class name (e.g.
<tt>java.lang.Integer</tt>) or using a short name. The following table
lists all the acceptable short names and the Java types they represent:
</span></p>
<table border="0" cellspacing="1" cellpadding="2" bgcolor="#7270c2">
<tr>
<td><span class="bodyGrey">
<table border="0" cellspacing="0" cellpadding="6" bgcolor="#ededed">
<tr bgcolor="#7270c2" style="color:#000000">
<th align="left">short name</th>
<th align="left">Primitive type?</th>
<th align="left">Java Class</th>
</tr>
<tr bgcolor="#DEDEDE"><td><span class="bodyGrey">big-decimal</span></td><td><span class="bodyGrey">N</span></td><td><span class="bodyGrey">java.math.BigDecimal</span></td></tr>
<tr><td><span class="bodyGrey">boolean</span></td><td><span class="bodyGrey">Y</span></td><td><span class="bodyGrey">java.lang.Boolean.TYPE</span></td></tr>
<tr bgcolor="#DEDEDE"><td><span class="bodyGrey">byte</span></td><td><span class="bodyGrey">Y</span></td><td><span class="bodyGrey">java.lang.Byte.TYPE</span></td></tr>
<tr><td><span class="bodyGrey">bytes</span></td><td><span class="bodyGrey">N</span></td><td><span class="bodyGrey">byte[]</span></td></tr>
<tr bgcolor="#DEDEDE"><td><span class="bodyGrey">char</span></td><td><span class="bodyGrey">Y</span></td><td><span class="bodyGrey">java.lang.Character.TYPE</span></td></tr>
<tr><td><span class="bodyGrey">chars</span></td><td><span class="bodyGrey">N</span></td><td><span class="bodyGrey">char[]</span></td></tr>
<tr bgcolor="#DEDEDE"><td><span class="bodyGrey">clob</span></td><td><span class="bodyGrey">N</span></td><td><span class="bodyGrey">java.sql.Clob</span></td></tr>
<tr><td><span class="bodyGrey">date</span></td><td><span class="bodyGrey">N</span></td><td><span class="bodyGrey">java.util.Date</span></td></tr>
<tr bgcolor="#DEDEDE"><td><span class="bodyGrey">double</span></td><td><span class="bodyGrey">Y</span></td><td><span class="bodyGrey">java.lang.Double.TYPE</span></td></tr>
<tr><td><span class="bodyGrey">float</span></td><td><span class="bodyGrey">Y</span></td><td><span class="bodyGrey">java.lang.Float.TYPE</span></td></tr>
<tr bgcolor="#DEDEDE"><td><span class="bodyGrey">integer</span></td><td><span class="bodyGrey">Y</span></td><td><span class="bodyGrey">java.lang.Integer.TYPE</span></td></tr>
<tr><td><span class="bodyGrey">locale</span></td><td><span class="bodyGrey">N</span></td><td><span class="bodyGrey">java.util.Locale</span></td></tr>
<tr bgcolor="#DEDEDE"><td><span class="bodyGrey">long</span></td><td><span class="bodyGrey">Y</span></td><td><span class="bodyGrey">java.lang.Long.TYPE</span></td></tr>
<tr><td><span class="bodyGrey">other</span></td><td><span class="bodyGrey">N</span></td><td><span class="bodyGrey">java.lang.Object</span></td></tr>
<tr bgcolor="#DEDEDE"><td><span class="bodyGrey">short</span></td><td><span class="bodyGrey">Y</span></td><td><span class="bodyGrey">java.lang.Short.TYPE</span></td></tr>
<tr><td><span class="bodyGrey">string</span></td><td><span class="bodyGrey">N</span></td><td><span class="bodyGrey">java.lang.String</span></td></tr>
<tr bgcolor="#DEDEDE"><td><span class="bodyGrey">strings</span></td><td><span class="bodyGrey">N</span></td><td><span class="bodyGrey">String[]</span></td></tr>
<tr><td><span class="bodyGrey">stream</span></td><td><span class="bodyGrey">N</span></td><td><span class="bodyGrey">java.io.InputStream</span></td></tr>
</table>
</span></td>
</tr>
</table>
<p><span class="bodyGrey">
In addition, support for the following Castor-internal field types
has been added:
</span></p>
<table border="0" cellspacing="1" cellpadding="2" bgcolor="#7270c2">
<tr>
<td><span class="bodyGrey">
<table border="0" cellspacing="0" cellpadding="6" bgcolor="#ededed">
<tr bgcolor="#7270c2" style="color:#000000">
<th align="left">short name</th>
<th align="left">Primitive type?</th>
<th align="left">Java Class</th>
</tr>
<tr bgcolor="#DEDEDE"><td><span class="bodyGrey">duration</span></td><td><span class="bodyGrey">N</span></td><td><span class="bodyGrey">org.exolab.castor.types.Duration</span></td></tr>
</table>
</span></td>
</tr>
</table>
<a name="SQL-Dates-and-Default-Timezones"><h2>SQL Dates and Default Timezones</h2></a>
<p><span class="bodyGrey">
Castor will use the JDBC <tt>ResultSet.getDate(int, Calendar)</tt> and
related methods which take a Calendar object to specify the timezone of
the data retrieved from the database when the timezone information is not
already specified in the data; this ensures that the "current"
timezone is applied.
</span></p>
<p><span class="bodyGrey">
The default time zone can be configured in the castor.properties file;
see the <a href="conf-lib.html">configuration section</a> for details
on how to configure Castor with information about your default time zone.
</span></p>
<p><span class="bodyGrey">
To change the timezone to a different timezone than the default, please
set a (different) value on the <tt>org.exolab.castor.jdo.defaultTimeZone</tt>
property:
</span></p>
<p></p><table bgcolor="#7270c2" cellpadding="1" cellspacing="1" border="0" width="100%"><tr><td><table bgcolor="#ededed" cellpadding="4" cellspacing="1" border="0" width="100%"><tr><td><span class="bodyBlack"><pre>
# Default time zone to apply to dates/times fetched from database fields,
# if not already part of the data. Specify same format as in
# java.util.TimeZone.getTimeZone, or an empty string to use the computer's
# local time zone.
org.exolab.castor.jdo.defaultTimeZone=
#org.exolab.castor.jdo.defaultTimeZone=GMT+8:00
</pre></span></td></tr></table></td></tr></table><p></p>
<a name="SQL-Type-Conversion"><h2>SQL Type Conversion</h2></a>
<p><span class="bodyGrey">
Castor JDO uses the JDBC <tt>getObject/setObject</tt> methods in order
to retrieve and set fields. These methods do not perform automatic type
conversion, often resulting in unexpected behavior. For example, when
using a NUMERIC field with direct JDBC access, application developers
tend to call <tt>getInteger()</tt> or <tt>getFloat()</tt>, but the
Java object returned from a call to <tt>getObject</tt> is often a
<tt>java.math.BigDecimal</tt>.
</span></p>
<p><span class="bodyGrey">
Castor JDO implements automatic type conversion between Java and SQL.
For this mechanism to work, the mapping file must specify the SQL type
being used for Castor to employ the proper convertor. If no SQL type
is specified, no conversion will occur, possibly resulting in an
<tt>IllegalArgumentException</tt> being thrown.
</span></p>
<p><span class="bodyGrey">
SQL types are specified with the <i>sql-type</i> attribute using either
the default Java type returned by the JDBC driver (e.g. <tt>java.lang.Integer</tt>
or the proper SQL type name (without precision). The following table lists
the supported SQL type names and the corresponding Java types:
</span></p>
<table border="0" cellspacing="1" cellpadding="2" bgcolor="#7270c2">
<tr>
<td><span class="bodyGrey">
<table border="0" cellspacing="0" cellpadding="6" bgcolor="#ededed">
<tr bgcolor="#7270c2" style="color:#000000">
<th align="left">SQL Type</th>
<th align="left">Java Type</th>
</tr>
<tr bgcolor="#DEDEDE"><td><span class="bodyGrey">bigint</span></td><td><span class="bodyGrey">java.lang.Long</span></td></tr>
<tr><td><span class="bodyGrey">binary</span></td><td><span class="bodyGrey">byte[]</span></td></tr>
<tr bgcolor="#DEDEDE"><td><span class="bodyGrey">bit</span></td><td><span class="bodyGrey">java.lang.Boolean</span></td></tr>
<tr><td><span class="bodyGrey">blob</span></td><td><span class="bodyGrey">java.io.InputStream</span></td></tr>
<tr bgcolor="#DEDEDE"><td><span class="bodyGrey">char</span></td><td><span class="bodyGrey">java.lang.String</span></td></tr>
<tr><td><span class="bodyGrey">clob</span></td><td><span class="bodyGrey">java.sql.Clob</span></td></tr>
<tr bgcolor="#DEDEDE"><td><span class="bodyGrey">decimal</span></td><td><span class="bodyGrey">java.math.BigDecimal</span></td></tr>
<tr><td><span class="bodyGrey">double</span></td><td><span class="bodyGrey">java.lang.Double</span></td></tr>
<tr bgcolor="#DEDEDE"><td><span class="bodyGrey">float</span></td><td><span class="bodyGrey">java.lang.Double</span></td></tr>
<tr><td><span class="bodyGrey">integer</span></td><td><span class="bodyGrey">java.lang.Integer</span></td></tr>
<tr bgcolor="#DEDEDE"><td><span class="bodyGrey">longvarbinary</span></td><td><span class="bodyGrey">byte[]</span></td></tr>
<tr><td><span class="bodyGrey">longvarchar</span></td><td><span class="bodyGrey">java.lang.String</span></td></tr>
<tr bgcolor="#DEDEDE"><td><span class="bodyGrey">numeric</span></td><td><span class="bodyGrey">java.math.BigDecimal</span></td></tr>
<tr><td><span class="bodyGrey">real</span></td><td><span class="bodyGrey">java.lang.Float</span></td></tr>
<tr bgcolor="#DEDEDE"><td><span class="bodyGrey">smallint</span></td><td><span class="bodyGrey">java.lang.Short</span></td></tr>
<tr><td><span class="bodyGrey">time</span></td><td><span class="bodyGrey">java.sql.Time</span></td></tr>
<tr bgcolor="#DEDEDE"><td><span class="bodyGrey">timestamp</span></td><td><span class="bodyGrey">java.sql.Timestamp</span></td></tr>
<tr><td><span class="bodyGrey">tinyint</span></td><td><span class="bodyGrey">java.lang.Byte</span></td></tr>
<tr bgcolor="#DEDEDE"><td><span class="bodyGrey">varbinary</span></td><td><span class="bodyGrey">byte[]</span></td></tr>
<tr><td><span class="bodyGrey">varchar</span></td><td><span class="bodyGrey">java.lang.String</span></td></tr>
<tr bgcolor="#DEDEDE"><td><span class="bodyGrey">other</span></td><td><span class="bodyGrey">java.lang.Object</span></td></tr>
<tr><td><span class="bodyGrey">javaobject</span></td><td><span class="bodyGrey">java.lang.Object</span></td></tr>
</table>
</span></td>
</tr>
</table>
<p><span class="bodyGrey">
The following example illustrates how to specify SQL type in field mapping:
</span></p>
<p></p><table bgcolor="#7270c2" cellpadding="1" cellspacing="1" border="0" width="100%"><tr><td><table bgcolor="#ededed" cellpadding="4" cellspacing="1" border="0" width="100%"><tr><td><span class="bodyBlack"><pre>
<field name="prodId" type"integer">
<sql name="prod_id" type="numeric"/>
</field></pre></span></td></tr></table></td></tr></table><p></p>
<p><span class="bodyGrey">
Please note that java.util.Date is not automatically converted into a
java.sql.Date object; while it is in theory possible to do so, there
are three different possible storage formats for date information:
as a java.sql.Date, java.sql.Time, and java.sql.Timestamp. Rather than
impose a possibly inappropriate data mapping on an entry, no automatic
transformation will take place.
</span></p>
<p><span class="bodyGrey">
JDBC drivers which do not, themselves, perform a mapping between
java.util.Date and the sql format specified on the database will throw
an error when java.util.Date is passed to them on the prepared
statement. Moreover, auto-conversion of java.util.Date is outside of
the JDBC specification; it is not a supported auto-convert format.
</span></p>
<p><span class="bodyGrey">
Users wishing to store date information into the database should ensure
that they set date, time, or timestamp as the sql type on the
<i>sql-type</i> attribute.
</span></p>
<a name="Parameterized-Type-Convertors"><h2>Parameterized Type Convertors</h2></a>
<p><span class="bodyGrey">
Some of the type convertors may have a string parameter, which changes
the conversion algorithm. The parameter is specified in square
brackets after the SQL type, for example:
</span></p>
<p></p><table bgcolor="#7270c2" cellpadding="1" cellspacing="1" border="0" width="100%"><tr><td><table bgcolor="#ededed" cellpadding="4" cellspacing="1" border="0" width="100%"><tr><td><span class="bodyBlack"><pre>
<field name="active" type="boolean">
<sql name="acc_active" type="char[01]"/>
</field></pre></span></td></tr></table></td></tr></table><p></p>
<p><span class="bodyGrey">
where "0" is the character value for <b>false</b> and "1" is
the character value for <b>true</b>.
</span></p>
<p><span class="bodyGrey">
In the above example the first of a bunch of parameterized type convertors
is used, "boolean --> char" convertor. The parameter must have length 2,
the first character is the value for <b>false</b>, the second character
is the value for <b>true</b>. The default value is "FT". The actual
SQL type should be char(1).
</span></p>
<p><span class="bodyGrey">
The second and third convertors are "boolean --> integer" and
"boolean --> numeric". Its parameter must be <b>+</b> for +1 or <b>-</b>
for -1 representing true. False is always converted to 0. For example:
</span></p>
<p></p><table bgcolor="#7270c2" cellpadding="1" cellspacing="1" border="0" width="100%"><tr><td><table bgcolor="#ededed" cellpadding="4" cellspacing="1" border="0" width="100%"><tr><td><span class="bodyBlack"><pre>
<field name="flagWithMinusOneForTrue" type="boolean">
<sql name="flag" type="integer[-]"/>
</field></pre></span></td></tr></table></td></tr></table><p></p>
<p><span class="bodyGrey">If the parameter is not specified, true is converted to +1.</span></p>
<p><span class="bodyGrey">
The fourth convertor is "date --> char". Its parameter must be a correct
pattern for SimpleDateFormat. For example:
</span></p>
<p></p><table bgcolor="#7270c2" cellpadding="1" cellspacing="1" border="0" width="100%"><tr><td><table bgcolor="#ededed" cellpadding="4" cellspacing="1" border="0" width="100%"><tr><td><span class="bodyBlack"><pre>
<field name="dateOfBirth" type="date">
<sql name="pers_dob" type="char[MMM d, yyyy]"/>
</field></pre></span></td></tr></table></td></tr></table><p></p>
<p><span class="bodyGrey">
If the parameter is not specified, the conversion is performed
using toString() method of the Date class.
</span></p>
<p><span class="bodyGrey">
The fifth and the sixth convertors are "date --> integer" and
"date --> numeric". Their parameters are also patterns having syntax
based on the SimpleDateFormat syntax, but repeated characters are
eliminated. The following table shows the substitution rules that are
used to obtain the SimpleDateFormat pattern from the parameter.
</span></p>
<table border="0" cellspacing="1" cellpadding="2" bgcolor="#7270c2">
<tr>
<td><span class="bodyGrey">
<table border="0" cellspacing="0" cellpadding="6" bgcolor="#ededed">
<tr bgcolor="#DEDEDE"><td><span class="bodyGrey">Y,y</span></td><td><span class="bodyGrey">yyyy</span></td><td><span class="bodyGrey">year</span></td></tr>
<tr><td><span class="bodyGrey">M</span></td><td><span class="bodyGrey">MM</span></td><td><span class="bodyGrey">month in year</span></td></tr>
<tr bgcolor="#DEDEDE"><td><span class="bodyGrey">D,d</span></td><td><span class="bodyGrey">dd</span></td><td><span class="bodyGrey">day in month</span></td></tr>
<tr><td><span class="bodyGrey">h,H</span></td><td><span class="bodyGrey">HH</span></td><td><span class="bodyGrey">hour in day (0~23)</span></td></tr>
<tr bgcolor="#DEDEDE"><td><span class="bodyGrey">m</span></td><td><span class="bodyGrey">mm</span></td><td><span class="bodyGrey">minute in hour</span></td></tr>
<tr><td><span class="bodyGrey">s</span></td><td><span class="bodyGrey">ss</span></td><td><span class="bodyGrey">second in minute</span></td></tr>
<tr bgcolor="#DEDEDE"><td><span class="bodyGrey">S</span></td><td><span class="bodyGrey">SSS</span></td><td><span class="bodyGrey">millisecond</span></td></tr>
</table>
</span></td>
</tr>
</table>
<p><span class="bodyGrey">
For example, "YMD" parameter is expanded to "yyyyMMdd" SimpleDateFormat
pattern, "YMDhmsS" parameter is expanded to "yyyyMMddHHmmssSSS"
SimpleDateFormat pattern. The length of the expanded parameter gives
the minimal number of decimal digits that the actual SQL type must
support. The default value of the parameter is "YMD".
</span></p>
<a name="BLOB-and-CLOB-Types"><h2>BLOB and CLOB Types</h2></a>
<p><span class="bodyGrey">
BLOB and CLOB stand for binary and character large objects (or in
Sybase, IMAGE and TEXT types, respectively). This means that most
likely you don't want to load the whole objects into memory, but
instead want to read and write them as streams. Usually these types are
not comparable via the <tt>WHERE</tt> clause of a SQL statement. That
is why you should disable dirty checking for such fields, e.g.
</span></p>
<p></p><table bgcolor="#7270c2" cellpadding="1" cellspacing="1" border="0" width="100%"><tr><td><table bgcolor="#ededed" cellpadding="4" cellspacing="1" border="0" width="100%"><tr><td><span class="bodyBlack"><pre>
<field name="text" type="string">
<sql name="text" type="clob" dirty="ignore" />
</field></pre></span></td></tr></table></td></tr></table><p></p>
<p><span class="bodyGrey">
In this example CLOB field will be read as a String. This may cause
OutOfMemoryError if the text is really large, but in many cases mapping
CLOB to String is acceptable. The advantage of mapping to String is
that we obtain a Serializable value that can be passed via RMI.
Similarly you can map BLOB and CLOB to <tt>byte[]</tt> and
<tt>char[]</tt> types, respectively:
</span></p>
<p></p><table bgcolor="#7270c2" cellpadding="1" cellspacing="1" border="0" width="100%"><tr><td><table bgcolor="#ededed" cellpadding="4" cellspacing="1" border="0" width="100%"><tr><td><span class="bodyBlack"><pre>
<field name="photo" type="bytes">
<sql name="photo" type="blob" dirty="ignore" />
</field>
<field name="resume" type="chars">
<sql name="resume" type="clob" dirty="ignore" />
</field></pre></span></td></tr></table></td></tr></table><p></p>
<p><span class="bodyGrey">
Now, assume that mapping to String is not acceptable. The natural Java
type mapping for the BLOB type is <tt>java.io.InputStream</tt>, and
this mapping is supported by Castor:
</span></p>
<p></p><table bgcolor="#7270c2" cellpadding="1" cellspacing="1" border="0" width="100%"><tr><td><table bgcolor="#ededed" cellpadding="4" cellspacing="1" border="0" width="100%"><tr><td><span class="bodyBlack"><pre>
<field name="cdImage" type="stream">
<sql name="cd_image" type="blob" dirty="ignore" />
</field></pre></span></td></tr></table></td></tr></table><p></p>
<p><span class="bodyGrey">
The natural Java type mapping for the CLOB type is
<tt>java.io.Reader</tt>, but this mapping is <b>not</b> supported by
Castor because <tt>java.io.Reader</tt> doesn't provide information
about the length of the stream and this information is necessary
for JDBC driver (at least for the Oracle driver) to write the value to
the database. This is why the CLOB type is mapped to
<tt>java.sql.Clob</tt>:
</span></p>
<p></p><table bgcolor="#7270c2" cellpadding="1" cellspacing="1" border="0" width="100%"><tr><td><table bgcolor="#ededed" cellpadding="4" cellspacing="1" border="0" width="100%"><tr><td><span class="bodyBlack"><pre>
<field name="novel" type="clob">
<sql name="novel" type="clob" dirty="ignore" />
</field></pre></span></td></tr></table></td></tr></table><p></p>
<p><span class="bodyGrey">
When you read data from the database, you can use the
<tt>getCharacterStream()</tt> method to obtain a
<tt>java.io.Reader</tt> from <tt>java.sql.Clob</tt>. When you write
data to the database, you can either use the helper class
<tt>org.exolab.castor.jdo.engine.ClobImpl</tt> to construct
<tt>java.sql.Clob</tt> from <tt>java.io.Reader</tt> and the length:
</span></p>
<p></p><table bgcolor="#7270c2" cellpadding="1" cellspacing="1" border="0" width="100%"><tr><td><table bgcolor="#ededed" cellpadding="4" cellspacing="1" border="0" width="100%"><tr><td><span class="bodyBlack"><pre>
object.setClob(new ClobImpl(new FileReader(file), file.length());</pre></span></td></tr></table></td></tr></table><p></p>
<p><span class="bodyGrey">
or implement the <tt>java.sql.Clob</tt> interface yourself.
</span></p>
<p><span class="bodyGrey">
But be aware of the followng restriction: if you map BLOB to
<tt>java.io.InputStream</tt> or CLOB to <tt>java.sql.Clob</tt>, then
you should turn caching off for the Java class containing
those values, e.g.:
</span></p>
<p></p><table bgcolor="#7270c2" cellpadding="1" cellspacing="1" border="0" width="100%"><tr><td><table bgcolor="#ededed" cellpadding="4" cellspacing="1" border="0" width="100%"><tr><td><span class="bodyBlack"><pre>
<class ...>
<cache-type type="none"/>
...
<field name="novel" type="clob">
<sql name="novel" type="clob" dirty="ignore" />
</field>
</class></pre></span></td></tr></table></td></tr></table><p></p>
<p><span class="bodyGrey">
Blob and Clob values cannot be cached, because they are alive only while
the ResultSet that produced them is open. In particular, this means
that you cannot use dirty checking for long transactions with such
classes.
</span></p>
</td></tr><tr height="5"><td align="left" valign="top" bgcolor="#7270c2" height="5" width="10"> </td><td valign="top" bgcolor="#7270c2" height="5" width="150"><img border="0" height="15" width="1" src="images/dotTrans.gif"><br><img align="right" border="0" height="3" width="105" src="images/line_sm.gif"></td><td align="left" valign="top" bgcolor="#a9a5de" height="5" width="7"> </td><td align="left" valign="top" height="5" width="70"> </td><td align="left" valign="top" height="5" width="120"> </td></tr><tr><td align="left" valign="top" bgcolor="#7270c2" height="5" width="10"> </td><td align="left" valign="top" bgcolor="#7270c2" width="150"></td><td align="left" valign="top" bgcolor="#a9a5de" width="7"><img border="0" height="25" width="1" src="images/dotTrans.gif"></td><td align="left" valign="top" width="70"><img border="0" height="25" width="1" src="images/dotTrans.gif"></td><td align="left" valign="top" width="120"> </td></tr><tr height="5"><td align="left" valign="bottom" bgcolor="#7270c2" height="100%" rowspan="2" width="10"><img border="0" height="125" width="10" src="images/stripes1.gif"></td><td align="left" valign="bottom" bgcolor="#7270c2" height="100%" rowspan="2" width="150"><img border="0" height="125" width="105" src="images/stripe105.gif"></td><td align="left" valign="top" bgcolor="#a9a5de" height="100%" rowspan="2" width="7"> </td><td align="left" valign="top" height="100%" width="70"> </td><td align="left" valign="top" height="100%" width="120"> </td></tr><tr height="5"><td align="left" valign="top" height="25" width="70"> </td><td align="left" valign="bottom" height="25" width="400"><br><br><img height="3" width="400" border="0" src="images/line_light.gif"><br><p></p><span class="bodyGrey"><small><notice>
Copyright © 1999-2005 <a href="http://www.exolab.org">ExoLab Group</a>, Intalio Inc.,
and Contributors. All rights reserved.
</notice><br> <br></small><small><notice>
Java, EJB, JDBC, JNDI, JTA, Sun, Sun Microsystems are trademarks or registered
trademarks of Sun Microsystems, Inc. in the United States and in other
countries. XML, XML Schema, XSLT and related standards are trademarks or registered
trademarks of MIT, INRIA, Keio or others, and a product of the World Wide Web
Consortium. All other product names mentioned herein are trademarks of their respective
owners.
</notice><br> <br></small></span><p></p>
</td><td align="left" valign="top" height="25" width="120"> </td></tr></table><script type="text/javascript">
var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl." : "http://www.");
document.write(unescape("%3Cscript src='" + gaJsHost + "google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E"));
</script><script type="text/javascript">
var pageTracker = _gat._getTracker("UA-3544187-1");
pageTracker._trackPageview();
</script></body></html>
