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