Changes

Java enum handling

To persist an Java enum it needs to be converted to a string. To do so Castor previously called toString() method of the enum. This worked out well until the toString() method got overwritten by a user to provide localized messages to be displayed for the enum values. In such a case the localized message got written to the database which caused failures when entity was loaded from database again. By calling name() method to convert the enum value to an string this will not happen any more.

Removed deprecated artefacts of CPA module

The following Interfaces, Classes, Methods and Properties that had been deprecated at previous Castor releases have been removed.

Changes

Moved connection proxies into new org.castor.cpa.persistence.sql.connection package

The entry in to enable connection proxies in properties file should now be:

# True if proxy classes should be used for JDBC connections and prepared statements.
# Defaults to true.
#
org.castor.cpa.persistence.sql.connection.proxies=false

Castor XML and the use of regular expressions

If regular expressions are being used with Castor XML, Castor XML now throws a IllegalStateException when no regular expression engine id specified in a custom castor.properties file (using the org.exolab.castor.regexp property). Please check with the reference guide to see what regular expression engines are supported.

Additions

Added support for Atomikos transaction manager

You can configure Castor to use Atomikos transaction manager as follows:

<transaction-demarcation mode="global">
   <transaction-manager name="atomikos" />
</transaction-demarcation>

Added support for named native queries at the class level

It is now possible to specify named native (SQL) queries at the class level:

<class name="org.castor.cpa.test.test1503.Entity" identity="id">
    <description>Named native query entity</description>
    <map-to table="test1503_entity"/>
    <field name="id" type="integer">
        <sql name="id" type="integer"/>
    </field>
    <field name="name" type="string">
        <sql name="name" type="char"/>
    </field>
    <named-native-query name="nativeSelectEntity">
        <query>SELECT * FROM test1503_entity</query>
    </named-native-query>
</class>

Changes

Support for Ant as build tool dropped

For various reasons, support for Ant as build tool has been dropped altogether. Please switch to use Maven 2, with the relevant project-specific details available at here.

Please note that the code base still includes Ant build files. Please do not use them! Ant files in the trunk are in the process of being removed, though this will take us some time.

*Configuration have been replaced by *Properties

The classes CoreConfiguration, XMLConfiguration and CPAConfiguration have been replaced by CoreProperties, XMLProperties and CPAProperties respectively. For backward compatibility we have kept the *Configuration classes and declared them deprecated. As we intend to remove *Configuration classes with next Castor release we encourage you to change your code to use *Properties instead.

Additions

New system property for specifying location of custom Castor XML properties

A new option has been added to specify the location of a custom Castor properties file by the means of a system property. This alters the sequence with which Castor XML searches for a custom properties as weil.

To specify the location of a Castor XML property file by using a system property, please use ....

> java -Dorg.castor.user.properties.location=/home/user/user.properties
                

Changes

Java 5.0 compliance

As of this release, Castor requires a Java 5.0 (and above) JVM at run-time. In addition, the XML code generator now emits Java 5.0-complaint code as well (which can be changed back to Java 1.4 compliance by setting the org.exolab.castor.builder.javaVersion property.

Re-introduced backwards compatibility for code generated from <xs:integer>

Added new org.exolab.castor.xml.lenient.integer.validation property to allow configuration of leniency for validation for Java properties generated from <xs:integer> types during code generation. This will allow successful validation for Java members that have been generated with Castor versions of 1.0.5 and older.

Long transactions that do not depend on cache

For long transactions (detached objects) to work it was required that the entity has been kept in cache from being loaded until its update. If the entity was expired from cache before the update an ObjectModifiedException had been thrown. While this is no problem if all entities of an application can be kept in cache all the time, it is one for large scale applications with millions of entities.

With release 1.3 we have changed the handling of timestamps. While it is still possible to rely on cache only it is now also possible to persist the timestamp together with the other properties of the entity. Doing so will ensure that the timestamp do not change even if the entity got expired from cache from being loaded until it get updated. If this happens the entity gets reloaded during update which also loads the previous timestamp. Having said that it still is possible that an ObjectModifiedException is thrown when another user has changed the same entity in the meantime.

See an example entity and its mapping below:

public class Entity implements TimeStampable {
    private Integer _id;
    private String _name;
    private long _timeStamp;
    
    public Integer getId() { return _id; }
    public void setId(final Integer id) { _id = id; }
    
    public String getName() { return _name; }
    public void setName(final String name) { _name = name; }
    
    public long getTimeStamp() { return _timeStamp; }
    public void setTimeStamp(final long timeStamp) {
        _timeStamp = timeStamp;
    }
    
    public long jdoGetTimeStamp() { return _timeStamp; }
    public void jdoSetTimeStamp(final long timestamp) {
        _timeStamp = timestamp;
    }
}

<class name="Entity">
    <cache-type type="time-limited" capacity="300"/>
    <map-to table="entity"/>
    <field name="id" type="integer" identity="true">
        <sql name="id" type="integer"/>
    </field>
    <field name="name" type="string">
        <sql name="name" type="char"/>
    </field>
    <field name="timeStamp" type="long">
        <sql name="timestamp" type="numeric" />
    </field>
</class>

Moved SQL drivers into new org.castor.cpa.persistence.sql.driver package

As we had to change the package of the drivers in castor.properties anyway, we also renamed the property that configures the classnames of the available drivers from org.exolab.castor.jdo.engines to org.castor.cpa.persistence.sql.driver.factories.

The entry in properties file should now be:

# List of persistence factories for the supported database servers:
#
org.castor.cpa.persistence.sql.driver.factories=\
  org.castor.cpa.persistence.sql.driver.OracleFactory,\
  org.castor.cpa.persistence.sql.driver.PostgreSQLFactory,\
  org.castor.cpa.persistence.sql.driver.SybaseFactory,\
  org.castor.cpa.persistence.sql.driver.SQLServerFactory,\
  org.castor.cpa.persistence.sql.driver.DB2Factory,\
  org.castor.cpa.persistence.sql.driver.InformixFactory,\
  org.castor.cpa.persistence.sql.driver.HsqlFactory,\
  org.castor.cpa.persistence.sql.driver.InstantDBFactory,\
  org.castor.cpa.persistence.sql.driver.InterbaseFactory,\
  org.castor.cpa.persistence.sql.driver.MySQLFactory,\
  org.castor.cpa.persistence.sql.driver.SapDbFactory,\
  org.castor.cpa.persistence.sql.driver.GenericFactory,\
  org.castor.cpa.persistence.sql.driver.DerbyFactory,\
  org.castor.cpa.persistence.sql.driver.PointbaseFactory,\
  org.castor.cpa.persistence.sql.driver.ProgressFactory

Moved SQL keygenerators into new org.castor.cpa.persistence.sql.keygen package

As we had to change the package of the drivers in castor.properties anyway, we also renamed the property that configures the classnames of the available drivers from org.exolab.castor.jdo.keyGeneratorFactories to org.castor.cpa.persistence.sql.keygen.factories.

The entry in properties file should now be:

# List of key generator factories:
#
org.castor.cpa.persistence.sql.keygen.factories=\
  org.castor.cpa.persistence.sql.keygen.MaxKeyGeneratorFactory,\
  org.castor.cpa.persistence.sql.keygen.HighLowKeyGeneratorFactory,\
  org.castor.cpa.persistence.sql.keygen.IdentityKeyGeneratorFactory,\
  org.castor.cpa.persistence.sql.keygen.SequenceKeyGeneratorFactory,\
  org.castor.cpa.persistence.sql.keygen.UUIDKeyGeneratorFactory

Additions

Code generator now supports use of Velocity as template engine

Castor now supports the use of Velocity-based code templates for code generation. For the time being, Castor will support two modes for code generation, i.e. the new Velocity-based and an old legacy mode. Default will be the legacy mode; this will be changed with a later release of Castor.

In order to use the new Velocity-based code generation, please override the following code generator property in a custom castorbuilder.properties as shown:

org.exolab.castor.builder.jclassPrinterTypes=\
   org.exolab.castor.builder.printing.TemplateJClassPrinter,\
   org.exolab.castor.builder.printing.WriterJClassPrinter

Users are encouraged the use the new Velocity-based mode and to provide us with (valuable) feedback.

Execution of CTF test suite in Maven

Added support for executing CTF test suite as part of a standard Maven build. To execute the CTF test suite from Maven, simply issue a mvn test in the xmlctf module, and the test suite will be run in addition to the standard unit tests.

Once the remainder of the code in the parent module has been moved to its own xml module, it will be possible to have the execution of the test suite as part of the release process, which will only succeed if all tests (including those from the CTF suite) pass successfully.

Added special processing of proxied classes

Objects that were lazy loaded from a persistence layer often are wrapped by dynamic proxies. This usually happens by extending the original class. In this case a call to getClass() does not return the original call but the proxy instead. As the class respectively its name is used to lookup class mapping or ClassDescriptor of any class to marshal, Castor fail to find the right one. The result is that the object gets introspected and the XML document produced does not look as expected. Even if you do not use ClassDescriptors generated by Castor's code generator or a mapping file as you want objects to get introspected, the resulting XML document is crap. The problem here is, that introspection not only finds the properties of your object but also those of the proxy which also get marshalled.

The solution to all of this problems is a new property in castor.properties file. It allows you to specify a list of interfaces that such proxied objects implement. If your object implements one of these interfaces Castor will not use the class itself but its superclass at introspection or to find class mappings and ClassDescriptors.

# Property specifying whether or not to search for an proxy interface at marshalling.
# If property is not empty the objects to be marshalled will be searched if they
# implement one of the given interface names. If the interface is implemented the
# superclass will be marshalled instead of the class itself.
#
org.exolab.castor.xml.proxyInterfaces=\
  net.sf.cglib.proxy.Factory, \
  org.hibernate.proxy.HibernateProxy

Be aware that no proxy interfaces are defined by default as the interface search slightly decreases marshalling performance.

Added support for (programmatic) access to XML schema documentation information

The Castor XML code generator - if configured as shown below - now generates additional methods to allow programmatic access to <xs:documentation> elements for top-level type/element definitions as follows:

    public java.lang.String getXmlSchemaDocumentation(final java.lang.String source);
    public java.util.Map getXmlSchemaDocumentations();

In order to have these additional methods generated as shown above, please override the following code generator property in a custom castorbuilder.properties as shown:

# Property specifying whether extra members/methods for extracting XML schema
# documentation should be made available; defaults to false
org.exolab.castor.builder.extraDocumentationMethods=true

Added support for complex Java 5 enums for simple type enumerations

In previous versions, Castor only supported (un)marshalling of "simple" Java 5 enums, meaning enums where all facet values are valid java identifiers. In these cases, every enum constant name can be mapped directly to the xml value.

So if there is at least ONE facet that cannot be mapped directly to a valid java identifier, we need to extend the enum pattern. The actual value of the enumeration facet is stored in a private String property, the name of the enum constant is translated into a valid identifier.

<xs:simpleType name="CompositeType">
  <xs:restriction base="xs:string">
    <xs:enumeration value="5"/>
    <xs:enumeration value="10"/>
  </xs:restriction>
</xs:simpleType>

public enum CompositeType {
    VALUE_5("5"),
    VALUE_10("10");

    private final java.lang.String value;

    private CompositeType(final java.lang.String value) {
        this.value = value;
    }

    public static CompositeType fromValue(final java.lang.String value) {
        for (CompositeType c: CompositeType.values()) {
            if (c.value.equals(value)) {
                return c;
            }
        }
        throw new IllegalArgumentException(value);
    }

    public java.lang.String value() {
        return this.value;
    }

    public java.lang.String toString() {
        return this.value;
    }
}

<root>
  <CompositeType>5</CompositeType>
</root>

    

See the description in the Source Generator Properties section for details.

Added support for configurable field handlers

Although it was already possible to create custom XML field handers, it was not possible to configure them. It is now possible to define your custom ConfigurableFieldHander and add any number of parameters to it, in the mapping file as follows:

<mapping>

   <field-handler name="myHandler" class="org.some.package.CustomFieldHandlerImpl">
      <param name="date-format" value="yyyyMMddHHmmss"/>
   </field-handler>

   <class .... />

   <class .../>

</mapping>

and subsequently refer to this custom (configurable) field handler by its name as shown in the following field mapping:

<class name="Root">
   <field name="date" type="string" handler="myHandler"/>
</class>

A typical example is the need to process multiple date formats in one xml file. This can now be done elegantly by configuring multiple instances of a configurable date field handler, each with a different date format.

Please check the new HOW-TO on using custom (configurable) field handlers with Castor.

Added support for custom JDO type convertors

You are now able to specify the type convertors for Castor JDO through a castor.properties file. Usually you will need two type convertors: one that converts from your custom type to a type supported by the database and another one for the opposite conversion. Both type convertor have to implement the org.castor.cpa.persistence.convertor.TypeConvertor interface. To ease the implemention task you can also extend one of our abstract implementations:

When adding your type convertors to the list of internal ones you have to take care not to drop any of them. An excerpt of that definition looks as follows:

# Type convertors
#
org.castor.cpa.persistence.TypeConvertors=\
  org.castor.cpa.persistence.convertor.BigDecimalToBoolean,\
  org.castor.cpa.persistence.convertor.BigDecimalToByte,\
    :
    :
    :
  org.castor.cpa.persistence.convertor.StringToSqlClob,\
  org.castor.cpa.persistence.convertor.StringToSqlTimestamp

Changes

Refactored Castor configuration

We have added a new class hierarchy to handle independent configurations for every module of Castor. Having said that, this should not change anything for any Castor user, as you still specify properties in a single castor.properties file for all modules.

Refactored JavaNaming

New JavaNaming is an exchangeable service instantiated trough XMLContext and accessed in a non-static way.

Refactored XMLClassDescriptorResolver

New XMLClassDescriptorResolver internally works with strategy and command pattern to have the possibility to enhance class resolving for future implementations (e.g. JAXB support).

Refactored XMLContext

New XMLContext is the information centerpiece and point to start for Castor XML stuff. It provides:

We had to remove static usage to make Castor more loosely linked than before.

Fixed support for 'strict elements'

When instructing Castor XML during unmarshalling to handle elements 'strict', this worked only in the presence of a mapping file. When the element/class in question was analyzed using Castor's introspector, setting this mode didn't produce the correct results. As part of a patch, this problem has now been fixed so that the behavior is the same irrespective of whether a mapping (file) is provided for a class or not.

For those of you relying on the old behavior, a new property has been introduced to allow leniency and to switch back to pre-patch behavior:

# Property specifying whether element strictness for introspected
# classes/elements should be lenient (aka allowed); defaults to false
org.exolab.castor.xml.lenient.introspected.element.strictness=false
                

Castor XML and JAXP - used per default

We have made some modifications to the way Castor XML obtains XML parser instances. As per this releae, Castor XML will - per default - use JAXP and its SAXParser(Factory) to obtain an instance of a SAX parser.

For this to work, we had to comment out the org.exolab.castor.parser property from the default castor.properties as shipped with Castor XML. As of this release, the property definition in the default castor.properties file reads:

# Defines a non-default XML parser to be used by Castor. By default,
# Castor will use JAXP internally to obtain an XML parser.
# The parser must implement org.xml.sax.Parser. (???)
#
# Should be used in the following situations:
# a) A different XML parser vendor should be used.
# b) With Java 5.0, an external XML parser should be used.
#
#org.exolab.castor.parser=org.apache.xerces.parsers.SAXParser

With this change, Castor XML will now use JAXP to create XML parsers, a mechanism that works works equally with Java 1.4 and Java 5.0, and thus does not require changes to the org.exolab.castor.parser property anymore as with older releases of Castor. In other words, with Java 5.0 Castor XML will now make use of the XML parser packaged with the JVM.

You should still consider setting this property manually in the following cases:

1. You are on Java 5.0, and you want to use a different XML parser (vendor) than the one shipped with the JVM.
2. You are on Java 5.0, and you want to use a different version of the XML parser shipped with the JVM.

Note: If you happen to have a custom castor.properties file packaged with your application, please consider removing the org.exolab.castor.parser property from this file to switch to the new default mechanism.

Static unmarshal methods on generated classes with Java 5.0 and above

For classes generated to be used with Java 5.0 (and above) that are part of a type hierarchy, the static unmarshal methods will now return the exact sub-type (i.e. the class where the method is defined), and not the parent type. This should improve type strictness and help in avoiding unnecessary casts.

Changes

This release is a minor release only and essentially fixes a regression issue of 1.1.2 that basically prevents specific user groups from using 1.1.2. Please see below issue list for details.

Additions

Added support for (un-)marshalling Java 5 enums

Castor XML now supports Java 5 enums in all cases where either a mapping file is used or it is relied upon default introspection.

Changes

Binary JARs restructured

As part of this release, we have again moved several areas of functionality to separate deployment units, resulting into additional JARs available for download:

Please note that the Castor JAR does not include this component anymore. In other words, if you want to use Castor JDO as a persistence framework, you will have to download both the Castor XML and Castor JDO JARs, as Castor JDO internally uses Castor XML. For details, please have a look at the download instructions.

Additions

Added support for substitution groups

Support for substitution groups has been added. This new feature is marked as experimental simply to indicate that we'd appreciate as much feedback and testing as possible.

Added 'automatic class name conflict resolution' mode

The XML code generator now support a new 'automatic class name conflict resolution' mode that will minimize - if not completely prevent - class name conflicts during code generation.

To enable this mode, please set the following property in your custom castorbuilder.properties file as shown below:

# Specifies whether automatic class name conflict resolution
# should be used or not; defaults to false.
#
org.exolab.castor.builder.automaticConflictResolution=true

This new mode will avoid class name conflicts by prepending XPATH fragments or type suffices to the 'normal' class name as generated otherwise.

Validation of <xs:sequence> order

Added support for validation of correct order of elements of <xsd:sequence> typed complex types during unmarshaling. A ValidationException will be thrown if the expected order cannot be matched.

Added support for <xs:hexBinary>

Added support for the XML schema type <xs:hexBinary> during XML code generation.

Added new <contentMember> element to binding filesupport for the hexBinary data type

This new element (child of a <componentBinding>) allows one to specify a custom member name for the content member as generated for a mixed mode complex type definition.

Added support for the hexBinary data type

The XML (Un-)Marshaller now supports the data type hexBinary.

Improved interface of XMLClassDescriptorResolver

The public interface of XMLClassDescriptorResolver has been improved and streamlined, adding various new methods for pre-loading class descriptors. Please check here for details.

Added Unmarshaller.setObject(Object)

To specify an existing root object to be used during unmarshalling, setObject(Object) has been added, alternatively to the Unmarshaller(Object) constructor.