![]() | ![]() | ![]() | ![]() | ![]() | ![]() | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
![]() | ![]() | ![]() | ![]() | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
![]() | ![]() | ![]() | ![]() | ![]() | ![]() | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
![]() | ![]()
|
Type SupportTypes Castor XML Castor JDO Castor DAX The Field Mapping SQL Dates and Default Timezones SQL Type Conversion Parameterized Type Convertors BLOB and CLOB Types TypesThe Castor type mechanism assures proper conversion between Java types and external types. Castor XMLCastor XML converts all Java fields into XML element and attribute values. Castor JDOCastor 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. The most common occurrences of mistyping is when using fields of type FLOAT, DOUBLE, NUMERIC and DECIMAL. SQL type FLOAT actually maps to Java type Double. SQL type NUMERIC and DECIMAL map to Java type BigDecimal. When such an inconsistency occurs, Castor JDO will throw an IllegalArgumentException during object persistence with a message indicating the two conflicting type. In order to avoid runtime exceptions we recommend explicitly specifying types in the mapping file using the SQL typing convention, see SQL Type Conversion Castor DAXCastor DAX converts all Java fields into LDAP attribute values. LDAP attribute values are always textual and represented as the string value of the field, e.g. "5" or "true". LDAP attributes may also contain binary values. When storing byte arrays or serialized Java objects, DAX will store them as byte arrays. The Field MappingThe field element includes an optional attribute called type 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. 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 complain about inconsistencies. The field type can be specified either given the full class name (e.g. java.lang.Integer) or using a short name. The following table lists all the acceptable short names and the Java types they represent:
In addition, support for the following Castor-internal field types has been added:
SQL Dates and Default TimezonesCastor will use the JDBC ResultSet.getDate(int, Calendar) 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. The default time zone can be configured in the castor.properties file; see the configuration section for details on how to configure Castor with information about your default time zone. To change the timezone to a different timezone than the default, please set a (different) value on the org.exolab.castor.jdo.defaultTimeZone property:
SQL Type ConversionCastor JDO uses the JDBC getObject/setObject 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 getInteger() or getFloat(), but the Java object returned from a call to getObject is often a java.math.BigDecimal. 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 IllegalArgumentException being thrown. SQL types are specified with the sql-type attribute using either the default Java type returned by the JDBC driver (e.g. java.lang.Integer or the proper SQL type name (without precision). The following table lists the supported SQL type names and the corresponding Java types:
The following example illustrates how to specify SQL type in field mapping:
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. 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. Users wishing to store date information into the database should ensure that they set date, time, or timestamp as the sql type on the sql-type attribute. Parameterized Type ConvertorsSome 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:
In the above example the first of six parameterized type convertors is used, "boolean->char" convertor. The parameter must have length 2, the first character is the value for false, the second character is the value for true. The default value is "FT". The actual SQL type should be char(1). The second and third convertors are "boolean->integer" and "boolean->numeric". Its parameter must be + for +1 or - for -1 representing true. False is always converted to 0. For example:
If the parameter is not specified, true is converted to +1. The forth convertor is "date->char". Its parameter must be a correct pattern for SimpleDateFormat. For example:
If the parameter is not specified, the conversion is performed using toString() method of the Date class. 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.
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". BLOB and CLOB TypesBLOB and CLOB stand for binary and character large objects (in Sybase IMAGE and TEXT types,
respectively), which means that most likely you don't want to load the whole objects into memory,
but to read/write them as streams.
Usually these types are not comparable via WHERE clause of SQL statement, that is why you should
disable dirty checking for such fields, e.g.
Now assume that this way is not acceptable.
The natual mapping for BLOB type is java.io.InputStream, and it is supported by Castor:
But be aware of the followng restriction: if you map BLOB to java.io.InputStream or
CLOB to java.sql.Clob, you should set turn caching off for the Java class containing
those values, e.g.:
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
![]() ![]() | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
![]() | ![]() | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
![]() | ![]() | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
![]() |