Requirements

Introduced Java 1.4 as a dependecy

This is a reminder that we have started to add some features that more or less depend on features made available with Java 1.4 (only), such as the JDBC 3.0 API enhancements. As such, we have made Java 1.4 a key requirement for the upcoming Castor 1.0 release.

Additions

Updated/Added to XML Documentation

Two new XML how-tos have been added to the XML HOW-TOs page, one on fetching XML dependencies (DTDs and schemas) from JAR files rather than network locations, and one on using identities and references in XML. The XML Mapping documentation was also updated so that the DTD public ID used in examples matches one in Castor's DTDResolver (this aids in fetching the DTD from the Castor JAR rather than the web address).

Added cache implementation for high volunm and high performance

The cache types fifo and lru are based on a set of articles in the O'Reilly Network by William Grosso, to implement a simplified and 1.3-compatible implementation of a Hashbelt algorithm.

Hashbelts are simple, in principle. Instead of walking all objects and finding out when they're supposed to expire, use a "conveyor belt" approach. At any particular point in time, objects going into the cache go into the front of the conveyor belt. After a certain amount of time or when the size limit of a container has been reached, move the conveyor belt - put a new, empty container at the front of the conveyor belt to catch new objects, and the one that drops off of the end of the conveyor belt is, by definition, ready for garbage collection.

As seen in his system, you can use a set of pluggable strategies to implement the actual hashbelt bits. A container strategy allows you to change out the implementation of the container itself - from simple hashtable-based implementations, up through more complex uses of soft referenced or hashset-based implementations, depending on what you need and what you want it to be used for. A pluggable "expire behavior" handler allows you to determine what action is taken on something which drops off of the bottom of the conveyor belt.

As of release 1.0 Castor knows of 11 cache types. To use this cache types, their factories need to be configured in castor.properties file. If you use a custom castor.properties file you need to add the new cache factories to be able to use the new cache types.

#
# Cache implementations
#
org.castor.cache.Factories=\
  org.castor.cache.simple.NoCacheFactory,\
  org.castor.cache.simple.TimeLimitedFactory,\
  org.castor.cache.simple.CountLimitedFactory,\
  org.castor.cache.simple.UnlimitedFactory,\
  org.castor.cache.distributed.FKCacheFactory,\
  org.castor.cache.distributed.JcsCacheFactory,\
  org.castor.cache.distributed.JCacheFactory,\
  org.castor.cache.distributed.CoherenceCacheFactory,\
  org.castor.cache.distributed.OsCacheFactory,\
  org.castor.cache.hashbelt.FIFOHashbeltFactory,\
  org.castor.cache.hashbelt.LRUHashbeltFactory
                

The DTD declaration to configure caching in Castor mapping is as follows:

<!ELEMENT cache-type  ( param* )>
<!ATTLIST cache-type
    type           ( none | count-limited | time-limited | unlimited |
                     coherence | fkcache | jcache | jcs | oscache |
                     fifo | lru ) "count-limited"
    debug          (true|false) "false"
    capacity       NMTOKEN  #IMPLIED>

<!ELEMENT param EMPTY>
<!ATTLIST param
          name   NMTOKEN  #REQUIRED
          value  NMTOKEN  #REQUIRED>

In difference to all other cache types the fifo and lru cache types offer various configuration options. Both of them have 6 parameters to configure their behaviour.

A fifo cache with default values explained above is specified by:

<cache-type type="fifo"/>

A lru cache with capacity=300 and ttl=300 is defined by:

<cache-type type="lru" capacity="300"/>

<cache-type type="lru"/>
    <param name="capacity" value="300"/>
    <param name="ttl" value="300"/>
</cache-type>

An example of a customized configuration of a fifo cache is:

<cache-type type="fifo"/>
    <param name="container" value="10"/>
    <param name="capacity" value="1000"/>
    <param name="ttl" value="600"/>
    <param name="monitor" value="5"/>
    <param name="container-class" value="org.castor.cache.hashbelt.container.WeakReferenceContainer"/>
    <param name="reaper-class" value="org.castor.cache.hashbelt.reaper.NullReaper"/>
</cache-type>

Code cleanup

We removed following classes and methods that had been deprecated for a while now.

Requirements

Introduced Java 1.4 as a dependecy

As we have started to add some features that more or less depend on features made available with Java 1.4 (only), such as the JDBC 3.0 API enhancements, we have made Java 1.4 a key requiremnt for the upcoming Castor 1.0 release.

This decision is a result of a discussion on the mailing lists a couple of months ago, where nobody was voicing any objections.

Additions

Added support for OSCache

By specifing

<cache-type type="oscache"/>

Added 'abstract/concrete' annotation to XMLDescriptor

With this addition, it is now possibel to query whether a particular XML element (represented by an XMLClassDesscriptor internally) is abstract or concrete, that is (in the context of source generation) a result of a <complexType> definition or an <element> declaration. This is particularly relevant for tool providers who need to integrate with Castor XML, and as a result of this addition can now use the new isElementDefinition() method to query an artifact's state.

New XML HOW-TOs added

Added XML HOW-TOs for mapping collections and maps.

Added new SAX2EventProducer interface

Added new org.exolab.castor.xml.SAX2EventProducer interface to allow passing SAX 2 events to Castor XML, deprecating the existing org.exolab.castor.xml.EventProducer interface at the same time. At the same time, a new unmarshal(SAX2EventProducer) method has been added to org.exolab.castor.xml.Unmarshaller, deprecating the existing unmarshal(EventProducer) method at the same time.

Added support for postgreSQL to identity key generator

Added support for the postgreSQL column type 'SERIAL' to the identity key generator. With this change, it's now possible to use the identity key generator with postgreSQL on columns with type 'SERIAL'. Castor internally will issue a call to

   SELECT currval('<table_name>_id_seq')
                

to automatically retrieve the value assigned due to 'SERIAL' column during the insert operation.

Added fully self-contained Castor JDO sample application

Added new ZIP archive to distribution that contains a fully self-contained Castor JDO sample applicationthat runs against an embedded Apache Derby database.

Simply download the the archive, unpack it, and in the target directory created, execute 'java -jar castor-1.0M2-examples.jar' to have the test executed. This will (magically) create a Derby database (on-the-fly) and use it to execute the Castor JDO code against it.

Added additional syntax for specifying identity columns

In addition to the current way of specifying the identity column(s) for a given class, it is now possible to declare a field to be part of the identity as shown below:

  <class name="ctf.jdo.tc1x.Parent">
    <description>Entite one</description>
    <map-to table="tc1x_entity1" xml="entity1" />
    <field name="id" type="integer" identity="true">
      <sql name="id" type="integer"/>
    </field>
    <field name="name" type="string">
      <sql name="name" type="char" />
    </field>
  </class>
                

Added collection type 'iterator' (java.util.Iterator) to Castor JDO

It is now possible to define a one-to-many relation with a collection type of 'iterator'. This allows the access of custom collection classes that are not supported through the standard collection types through Castor JDO.

   <field name="children" type="some.domain.custom.Class" collection="iterator">
      <sql ... />
   </field>
                

Added collection type 'enumerate' (java.util.Enumeration) to Castor JDO

It is now possible to define a one-to-many relation with a collection type of 'enumerate'.

   <field name="children" type="some.domain.custom.Class" collection="enumerate">
      <sql ... />
   </field>
                

Added WeblogicXMLSerializerFactory

To use the Xerces implementation delivered with Weblogic 7 and 8 you have to change castor.properties file to contain the following entry:

# Defines the (default) XML serializer factory to use by Castor,
# which must implement org.exolab.castor.xml.SerializerFactory;
# default is org.exolab.castor.xml.XercesXMLSerializerFactory
org.exolab.castor.xml.serializer.factory=org.exolab.castor.xml.wls8.WeblogicXercesXMLSerializerFactory
                

Additions

Support for java.util:list as collection type

Added support for java.util.List as collection type for Castor XML.

Support for Borland Pointbase

Support for Borland's Pointbase has been added. For initial information about configuration of Castor JDO for the use with Borland's Pointbase, please see src/tests/jdo/pointbse.xml.

Added isLocked (CLass, Object) method to Database interface

This new method allows to check, whether a particular object (as identified by the object identity and the object class) is currently locked with Castor JDO.

Added documentation about Castor JDO Persistence interface

Added a section about the various methods available on the Persistence interface to the HTML docs.

Allowed case insensitive lookups of enumerated type values

With 'case-insensitive' commandline option of source generator you are now able to instruct Castor to use case insensitive lookups for enumerated type values.

Changes

As a result of this refactoring, we had to change the way a XMLSerializer is created (instantiated). Rather than letting Castor know about the XMLSerializer to use, as in

# Defines the default XML serializer to be used by castor
# The serializer must implement org.apache.xml.serialize.Serializer
#
org.exolab.castor.serializer=org.apache.xml.serialize.XMLSerializer
                

the user is now required to specify an XMLSerialzer factory as follows:

# Defines the (default) XML serializer factory to use by Castor,
# which must implement org.exolab.castor.xml.SerializerFactory;
# default is org.exolab.castor.xml.XercesXMLSerializerFactory
org.exolab.castor.xml.serializer.factory=org.exolab.castor.xml.XercesXMLSerializerFactory
                

As of this release, we only support the XercesXMLSerializerFactory as shown above, but provide users with three new interfaces (namely Serializer,OutputFormat and XMLSerializerFactory) that need to be implemented to support any other's XML parser custom serialization mechanism.

Refactored cache into new org.castor.cache package

Take care to adjust your custom castor.properties file to reflect the changed packages of CacheFactories.

#
# Cache implementations
#
org.castor.cache.Factories=\
  org.castor.cache.simple.NoCacheFactory,\
  org.castor.cache.simple.TimeLimitedFactory,\
  org.castor.cache.simple.CountLimitedFactory,\
  org.castor.cache.simple.UnlimitedFactory,\
  org.castor.cache.distributed.FKCacheFactory,\
  org.castor.cache.distributed.JcsCacheFactory,\
  org.castor.cache.distributed.JCacheFactory,\
  org.castor.cache.distributed.CoherenceCacheFactory
                

Note: By also moving CacheFactoryRegistry to org.castor.cache package the property has been renamed from 1.0M1 a second time.

Changed syntax of cache definition in mapping

The DTD declaration is as follows:

<!ELEMENT cache-type  ( param* )>
<!ATTLIST cache-type
    type           ( none | count-limited | time-limited | unlimited |
                     coherence | fkcache | jcache | jcs ) "count-limited"
    debug          (true|false) "false"
    capacity       NMTOKEN  #IMPLIED>

<!ELEMENT param EMPTY>
<!ATTLIST param
          name   NMTOKEN  #REQUIRED
          value  NMTOKEN  #REQUIRED>

The new syntax is still backward compatible to the old one but allows to enable debugging of cache access for a specific class as well as passing individual configuration parameters to each cache instance. Only count-limited and time-limited of the current cache types support parameters. Parameter names are case sensitive and are silently ignored if they are unknown to a cache type.

It need to be noted that there are 3 parameter names that are reserved for internal use. If you specify a parameter with one of the names: type, name or debug their value will silently be overwritten with another one used internally.

A count-limited least-recently-used cache (LRU) for 500 objects can be specified by:

<cache-type type="count-limited" capacity="500"/>

<cache-type type="count-limited"/>
    <param name="capacity" value="500"/>
</cache-type>

A time-limited first-in-first-out cache (FIFO) that expires objects after 15 minutes can be specified by:

<cache-type type="time-limited" capacity="900"/>

<cache-type type="time-limited"/>
    <param name="ttl" value="900"/>
</cache-type>

The debug attribute can be used to enable debugging for objects of a single class only, as described below.

Added debugging of cache access

If you like to get debug messages for every access to cache independend of the caches type or the class of the object that is accessed you only need to set logging level of org.castor.cache to debug. As this may lead to lots of debug messages, you are not interested in, there are 2 options to reduce the number of the messages.

If you are interested in all accesses to a specific cache type you set the logging level of this implementation to debug.

To get debug messages of accesses to objects of a specific class there are 2 things you need to do. To be able to get debug messages at all you need to set logging level of org.castor.cache.Cache to debug first. Then you only need to set the debug attribute of the class you are interested in to true in the mapping.

Note: By allowing to pass individual configuration properties from mapping to cache we again changed the way debugging is enabled. The property in castor.properties file from relaese 1.0M1 is no longer supported.

New features

Support for collections of type 'SortedSet' (incl. use of Comparator)

Support has been added for the new collection type 'sortedset'. This allows users of Castor (XML and JDO) to use collections of type java.util.SortedSet to allow for automatic ordering of the collection upon e.g. insertion of the data.

User can either specify a java.util.Comparator instance using the comparator attribute on the field mapping, or make the entities stored within the SortedSet implement java.util.Comparable.

Changes

Moved JDO configuration from org.exolab.castor to org.castor package

With this refactoring JDOConfFactory has also been moved from org.exolab.castor.jdo.util to org.castor.jdo.util package. In addition we allowed to specify a name attribute on the jdo-conf tag that will be used in future to distinguish between different configurations.

Refactored cache into new org.castor.cache package

Take care to adjust your custom castor.properties file to reflect the changed packages of CacheFactories.

#
# Cache implementations
#
org.castor.jdo.cacheFactories=\
  org.castor.cache.simple.NoCacheFactory,\
  org.castor.cache.simple.TimeLimitedFactory,\
  org.castor.cache.simple.CountLimitedFactory,\
  org.castor.cache.simple.UnlimitedFactory,\
  org.castor.cache.distributed.FKCacheFactory,\
  org.castor.cache.distributed.JcsCacheFactory,\
  org.castor.cache.distributed.JCacheFactory,\
  org.castor.cache.distributed.CoherenceCacheFactory
                

Added debugging of cache access

By setting the property org.castor.jdo.cacheDebug to true you are able to get debug messages for every cache access in the configured log.

#
# True if proxy class should be used to debug access to cache
# (default: false).
#
#org.castor.jdo.cacheDebug=false
                

Moved transaction manager from org.exolab.castor to org.castor package

Take care to adjust your custom castor.properties file to reflect the changed packages of TransactionManagerFactories.

#
# TransactionManagerFactory implementations
#
org.castor.transactionmanager.Factories=\
  org.castor.transactionmanager.WebSphereTransactionManagerFactory,\
  org.castor.transactionmanager.WebSphere5TransactionManagerFactory,\
  org.castor.transactionmanager.WebSphere51TransactionManagerFactory,\
  org.castor.transactionmanager.LocalTransactionManagerFactory,\
  org.castor.transactionmanager.JNDIENCTransactionManagerFactory,\
  org.castor.transactionmanager.JOTMTransactionManagerFactory
                

In addition a new property has been introduced that allows to configure if the transaction manager shell be acquired instantly when he is registered or lazy when it is needed for the first time.

#
# Shell the TransactionManager be initialized at registration or lazily when
# requested for the first time? Defaults to false.
#
org.castor.transactionmanager.InitializeAtRegistration=false
                

New features

Added support for JOTM as transaction manager

Added support for JOTM as transaction co-ordinator. As a result, the following transaction managers are supported.

Improved Database.getIdentity(Object)

The new implementation of the Database.getIdentity(Object) does not rely on the object being loaded in the same transaction anymore. It is even not required to have an active transaction. The identity will now be determined by calling the getters of the fields defined as identities in the mapping. If a mapping for the objects class could not be found a ClassNotPersistenceCapableException will be thrown. Null is only returned if the objects identity is null.

Note:Care should be take if you previously used the null return of Database.getIdentity(Object) to determine if the object has been loaded in the current transaction before.

Added helper method to close database

Added org.castor.jdo.util.JDOUtils.closeDatabase() method to close an open database instance without throwing exceptions. Any active transaction will be silently rolled back.

Bugs

Improved 'caching' of Castor DTDs/XML Schemas

Added code to DTDResolver so that any URL/URIs against http://castor.org/... will be resolved against (local) files from within the Castor JAR(s).

Problem obtaining underlying JDBC connections

Fixed a problem with obtaining the underlying JDBC connection used by Castor internally when there was no valud transaction. The code has been changed so that a PersistenceException will be thrown to indicate the lack of a valid transaction.

Download & installation instructions

This is the final 0.9.9 release, a feature release for Castor JDO and XML.

Please note that we are providing the usual suspects (binaries, docs and sources) for this release at the Codehaus.

We are currently planning for a Castor 1.0 release in about 8+ weeks, which we mainly see as a bug fix release and a one-time opportunity to get the HTML documentation into a better shape .. ;-).

Please note that we have - in addition to the features added and bugs fixed as documented with 0.9.9M1 and 0.9.9M2 - started to makes substantial changes to the project documentation as follows:

-	Addition of the first Castor JDO HOW-TO pages
-	Addition of an initial (hence draft) Castor JDO best practice document
-	Addition of a Castor JDO feature page

As mentioned above, these pages are work in progress and shall be expanded for the upcoming 1.0 release.

Download & installation instructions

Please note that we are providing the usual suspects (binaries, docs and sources) for this release at the Codehaus. We recommend, though, to download the complete package, as the HTML docs at the main Castor site has not been updated, and to build the documentation yourself.

Preparations for the final release have started. Since the last release candidate, the following problem areas have been addressed.

Download & installation instructions

Please note that we are providing the usual suspects (binaries, docs and sources) for this release at the Codehaus. We recommend, though, to download the complete package, as the HTML docs at the main Castor site has not been updated, and to build the documentation yourself.

Changes

Support for polymorphism

Support for polymorphism has been completely rewritten, allowing you to load objects that are part of an extend relationship by their base types, with Castor JDO returning the actual (leaf) classes.

With the following class hierarchy ...

it will be possible to execute OQL queries as follows:

SELECT product FROM Product product
                

and Castor JDO will return the actual Laptop and Server instances. For a complete set of code examples, please review src/tests/ctf/jdo/tc9x/TestPolymorphism.java.

Updated MANIFEST files

Both castor-0.x.y.jar and castor-0.x.y-xml.jar now carry an updated and up-to-date MANIFEST file.

New features

Support for Derby

Support for Apache Derby (starting with release 10.1.1.0) has been added. For initial information about configuration of Castor JDO for the use with Apache Derby, please see src/tests/jdo/derby.xml.

Known issues:

-	No support for LIMIT clause
-	No support for identity key generator (temporarily)
-	No support for SELECT .. FOR UPDATE statements.

Added support for distributed caches

As of this release, four new cache types have been added:

1. Tangosol Coherence (coherence)
2. JCache (jcache)
3. FKCache (fkcache)
4. JCS (jcs)

As some of these cache implementations allow you to use it in a distributed mode, this allows Castor JDO to be used in a clustered (multi-JVM) environment. In such an environment, Castor JDO wil make use of the underlying cache provider to replicate/distribute the cache content between the various JDOManager instances.

Support for transient attribute for <sql> mappings

Support for the transient attribute has been added to the <sql> element has been added. This allows you to define a field mapping as follows:

<field name="prop1" type="string">
   <sql name="prop_1" transient="true" />
   <bind-xml name="property1" />
</field>
                

allowing you to include a field for XML un-/marshalling, but exclude it from persistence.

Support for typesafe enumerations

Enumerations are a common method for ensuring data integrity, both in software and in relational databases. As a platform for linking the two, we added support for persisting class fields whose type is a Java typesafe enumeration to Castor JDO.

To use this new feature your typesafe enumeration should follow the enum pattern commonly used and provide a static valueOf(String) method. An enum of different kinds of computer equipment may look like:

public class KindEnum {
    private static final Map KINDS = new HashMap();

    public static final KindEnum MOUSE = new KindEnum("Mouse");
    public static final KindEnum KEYBOARD = new KindEnum("Keyboard");
    public static final KindEnum COMPUTER = new KindEnum("Computer");
    public static final KindEnum PRINTER = new KindEnum("Printer");
    public static final KindEnum MONITOR = new KindEnum("Monitor");

    private final String _kind;

    private KindEnum(final String kind) {
        _kind = kind;
        KINDS.put(kind, this);
    }

    public static KindEnum valueOf(final String kind) {
        return (KindEnum) KINDS.get(kind);
    }

    public String toString() { return _kind; }
}
                

At your Product class you may want to have a property that tells you what kind of computer equipment a product is of.

public class Product {
    private int         _id;
    private String      _name;
    private KindEnum    _kind;

    public Product() { }

    public int getId() { return _id; }
    public void setId(int id) { _id = id; }

    public String getName() { return _name; }
    public void setName(String name) { _name = name; }

    public KindEnum getKind() { return _kind; }
    public void setKind(KindEnum kind) { _kind = kind; }
}
                

Your mapping for the Product class should be:

<class name="Product" identity="id">
  <description>Product with kind enum</description>
  <map-to table="enum_prod"/>
  <field name="id" type="integer">
    <sql name="id" type="integer"/>
  </field>
  <field name="name" type="string">
    <sql name="name" type="char"/>
  </field>
  <field name="kind" type="KindEnum">
    <sql name="kind" type="char"/>
  </field>
</class>
                

To add this new feature we added an additional check when searching for field types. Like before Castor first searches for know types and thereafter for a mapping for the class you specified as type. If both of them do not match it now checks if the class specified as type is available at classpath and has a static valueOf(String) method. Only if all of this conditions are met it will be viewed as a valid mapping.

Parametrized boolean->char type converter

Pre patch we always returned a boolean value even if the database contained a value which does not conform to the rules defined. This behaviour caused that we could load records with wrong values without problems but got a ObjectModifiedException when we tried to update these values as our update statment includes checking of all old values in the where clause of SQL statement.

With the patch this behavier changes to strict checking if the loaded char/string value matches one of the boolean characters defined by conversion rule. If the value does not match a ClassCastException explaing the fail reason will be thrown.

Performance improvements

Several code areas of Castor JDO have been severly refactored or rewritten from scratch, leading to some significantly improved runtime performance. This includes amongst others a reduced execution time when dealing with a large number of entities loaded as part of a single transaction, etc.

Download & installation instructions

This is the final 0.9.7. release, mainly a maintenance release. We are currently planning the next release which will be Castor 0.9.9, a feature release.

Changes

Moved key generators to jdo.keygen package

Whilst this change is non-intrusive per se, please note that you might have to change a local castor.properties file if you happened to re-specify key generators in there.

Fixed problem with multiple <database> configurations

Support for multiple database configurations has been re-enabled.