| Title: Extended Types |
| |
| |
| |
| <P>JDBC specification defines a set of "standard" database column types (defined in java.sql.Types class) and a very specific mapping of these types to Java Object Types, such as java.lang.String, java.math.BigDecimal, etc. Sometimes there is a need to use a custom Java type not known to JDBC driver. CayenneModeler allows to configure an arbitrary Java class as an <A href="http://objectstyle.org/cayenne/api/cayenne/org/objectstyle/cayenne/map/ObjAttribute.html" class="external-link" rel="nofollow">ObjAttribute</A> type by simply entering a fully-qualified name such class in the type column of an ObjAttribute. However there is more to it than just that. Cayenne needs to know how to instantiate this type from a database "primitive" value, and conversly, how to transform an object of the custom type to a JDBC-compatible object.</P> |
| |
| <H3><A name="ExtendedTypes-SupportingNonStandardTypes"></A>Supporting Non-Standard Types</H3> |
| |
| <P><A href="http://objectstyle.org/cayenne/api/cayenne/org/objectstyle/cayenne/access/types/ExtendedType.html" class="external-link" rel="nofollow">ExtendedType</A> interface serves to integrate a custom attribute type to Cayenne. An implementation must provide <TT>ExtendedType.getClassName()</TT> method that returns a fully qualified Java class name for the supported custom type, and a number of methods that convert data between JDBC and custom type. Installing an ExtendedType currently has to be done in the code, some time during Cayenne startup (modeler support will be added in the future). The following code sample demonstrates this procedure:</P> |
| <DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent"> |
| <PRE class="code-java"><SPAN class="code-comment">// create custom ExtendedType instance |
| </SPAN>ExtendedType customType = <SPAN class="code-keyword">new</SPAN> MyCustomType(); |
| |
| <SPAN class="code-comment">// Find DataNode |
| </SPAN>DataDomain domain = Configuration.getSharedConfiguration().getDomain(); |
| DataNode node = domain.getNode(<SPAN class="code-quote">"node_name_from_the_project"</SPAN>); |
| |
| <SPAN class="code-comment">// install ExtendedType |
| </SPAN>node.getAdapter().getExtendedTypes().registerType(customType); |
| </PRE> |
| </DIV></DIV> |
| |
| <H3><A name="ExtendedTypes-DbAdaptersandExtendedTypes"></A>DbAdapters and Extended Types</H3> |
| |
| <P>As shown in the example above, ExtendedTypes are stored by <A href="http://objectstyle.org/cayenne/api/cayenne/org/objectstyle/cayenne/dba/DbAdapter.html" class="external-link" rel="nofollow">DbAdapter</A>. In fact DbAdapters often install their own extended types to address incompatibilities, incompletness and differences between JDBC drivers in handling "standard" JDBC types. For instance some drivers support reading large character columns (CLOB) as java.sql.Clob, but some other - as "character stream", etc. Adapters provided with Cayenne override <TT>configureExtendedTypes()</TT> method to install their own types, possibly substituting Cayenne defaults. Custom DbAdapters can use the same technique.</P> |
