Please look at the Jira release notes for details about all (XML-related) issues addressed in this release.
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.
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:
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.
Added support for Atomikos transaction manager
You can configure Castor to use Atomikos transaction manager as follows:
Added support for named native queries at the class level
It is now possible to specify named native (SQL) queries at the class level:
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.
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 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:
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:
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:
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:
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.
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
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:
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.
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:
and subsequently refer to this custom (configurable) field handler by its name as shown in the following field mapping:
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:
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.
New JavaNaming is an exchangeable service instantiated trough XMLContext and accessed in a non-static way.
New XMLClassDescriptorResolver internally works with strategy and command pattern to have the possibility to enhance class resolving for future implementations (e.g. JAXB support).
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:
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:
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:
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.
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.
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.
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.
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:
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 new functionality to XMLClassDescriptorResolver to pre-load class descriptors for a package. Please find details about this new feature at the best practises for Castor XML.
XML serialization with JDK 5.0
As Sun has included Apache's Xerces with Java 5.0 by default, we have added support for using the Xerces instance as shipped with the JRE/JDK for serialization. As such, for Java 5.0 users, this removes the requirement to download Xerces separately.
To enable this new feature, please change the following property in your local castor.properties file (thus redefining the default value) as shown below:
Castor under JDK 6
As of this release, Castor now builds under JDK 6.0. Castor XML has been tested under JDK 6.0. However, Castor JDO has not really been tested under JDK 6.0. Note that you may need to use a JDBC 4.0 compatible connector with this new JDK.
If you are using the Castor code generator to generate code from schemas that use xsd:import, whether or not code was generated from the imported schemas was controlled by a combination of switches. Now it is controlled only by the "-generateImportedSchemas" option of SourceGeneratorMain, the Ant task option of the same name, or if you are calling codegen programmatically, the method sgen.setGenerateImportedSchemas(true);.
The XML CTF has been moved to its own area. It has been moved from ./src/tests/ into ./xmlctf/. All scripts to run the CTF have been updated for this change.
At the Google Summer of Code program for 2006, the student Le Duc Bao worked for Castor. With support of his mentor Ralf Joachim, he implemented a generator for DDL scripts from scratch.
Castor DDL Generator creates a SQL script to drop/create tables, unique keys, sequences and so on, from a Castor JDO mapping file.
This will generate the SQL script mapping.sql in the same directory mapping.xml is located.
The code generator now supports multiple pattern facets properly.
Binary JARs restructured
As part of this release, we have started to move several areas of functionality to separate deployment units, resulting into additional JARs available for download:
In addition, as outlined above, the new DDL generator has been made available as a separate deployment unit as well, resulting into ...
Please note that the Castor XML (and JDO) JARs do not include these components anymore. In other words, if you want to use both Castor XML (for (un-)marshaling) and the XML code generator for code generation from an XML schema, you will have to download both JARs. For details, please have a look at the download instructions.
Code generation for <xs:int> and <xs:integer>
As such, the XML code generator has been changed (again) to generate the following Java types for elements/attributes typed with <xs:int> and <xs:integer>:
Code generation for <xs:int> and <xs:integer>
As part of the work for fixing bug 1421, it has been recognized that the code generated pre-patch did not comply with the set of rules defined in the XML schema specification.
As such, the XML code generator has been changed to generate the following Java types for elements/attributes typed with <xs:int> and <xs:integer>:
The only difference between the artifacts generated is that a different Java type is used with a different (and appropriate to the specification) value range. Thus, the value range that will be accepted by the generated Java instance variables has changed.
XML test suite execution
The CTF currently requires the Sun JDK (or SDK) to execute, although it may be possible to execute with GNU gcj or with JRockit. The CTF will not work if you are using only a JRE. This is because the CTF uses the Sun Java compiler API to compile code as needed for Source Generator and Marshaling Framework tests. The CTF code is written to allow easy extension for additional compiler frameworks, so if you use a compiler or runtime that is not supported, you should be able to easily add support for a new framework. If you want to do this, contact Castor committors for assistance and direction and they'll set you on the right course.
Two new features have been added to the CTF that allow users to add Java-version-specific tests. The first new feature applies to an entire test, that is, the full suite of tests described by a single TestDescriptor.xml file. If you add the following tag to a TestDescriptor.xml:
then the entire suite of tests described by that test descriptor will be skipped if the version of Java executing the test suite is not at least the minimum version specified.
For the second new feature, if you add the following tag to an individual Unit Test in a TestDescriptor.xml:
then for that individual unit test, all code will be compiled with the javac parameter -source 1.2, using the version specified.
For both of these parameters, you are expected to supply a value that is allowed by the javac -source command-line option, although if you specify an integer between 5 and 9 (inclusive), that value will automatically be converted to the correct value.
In the source generator, all facets are now implemented for all of the XML Schema date/time types with one exception: validation for the "fixed" facet of xsd:dateTime is not implemented. This is because Castor marshals dateTime as a java.util.Date, which does not contain time zone information. A later release of Castor may marshal xsd:dateTime into a java.util.Calendar instead of java.util.Date.
An additional unit test type has been added to the MarshallingTest and SourceGeneratorTest test types that allows invoking user-supplied arbitrary code that will either return a boolean "false" or an Exception if the user-test fails or it will throw an exception if the user-test fails. For a sample of this new unit test type, see the tests in the directory
The Source Generator now creates class descriptors in a subdirectory
Previously, the class descriptors (used during marshaling and unmarshaling to provide constraints, validation assistance, etc.) were generated into the same directory (same package) as the classes they describe. Starting with this release, the class descriptors are generated into a subpackage named "descriptors" one directory lower than the package where the classes being described are generated. Doing so prevents the class descriptors from cluttering up the directory where the code the developer cares about will be generated.
An additional benefit of this change occurs if you generate source into a directory that already contains other source code. In this instance, it can be difficult for ANT to determine whether or not you need to regenerate the generated source code, that is, whether the XSD file is newer or older than the generated source. Under the usual circumstance where the descriptors subpackage contains only generated code, you can use the ANT <uptodate> task to compare the timestamp of the XSD file against the timestamps of the descriptors, and thus reliably know whether or not you have to regenerate source code.
For marshaling and unmarshaling, the class descriptors will be located via the ".castor.cdr" files located in the directories (packages) where the classes are generated. If these files are deleted or are not kept (we highly recommend including these files in your JAR file) then the class descriptor resolver will first look for the class descriptors in the same package where the classes to be described are. If they are not found there, then the class descriptor resolver will look in a subpackage "descriptors." This maintains backwards compatibility with code generated under older Castor releases.
Code generation -- Specifying member visibility in binding file
It is now -- at the <member> level -- possible to specify a Java member's visibility (different from the default value "private") similar to ...
Valid values for the visibility attribute are protected, private and public, as per the definition in binding.xsd.
Support for additional collection types in binding file
Added support for specifying additional collection types in a binding file, similar to ...
The following types have been added: 'collection', 'set' and 'sortedset'.
Extended support for validation of IDs during unmarshaling
The default IDResolverImpl class has been changed so that a validation exception will be thrown if an empty or duplicate ID value is encountered.
Added support for <enumBinding>s
The XML code generator has been enhanced so that it is possible to provide a binding for the following enumeration ...
Add support for validating <xsd:ID> during marshaling.
Castor XML now supports validation of <xsd:ID>s during marshaling, preventing the following scenarios from being marshaled successfully (throwing a ValidationException instead):
XML code generation - Signature type for 'j2' collections
The Castor code generator now uses 'java.util.List' as type when generating code for a Java member (as well as the type used for the corresponding getter and setter methods) rather than the old 'java.util.ArrayList'.
Backported Castor to be compliant with Java 1.3 again. Therefore the dependecy on Java 1.4 introduced with 1.0 release has been removed.
To not lose features like JDBC 3.0 introduced with the 1.0 release of Castor, we decided to use reflection or dynamic proxies in some places. This allows one to use these features with Java 1.4 while still being able to use Castor with Java 1.3.
Database appender for log4j through CastorJDO
We have added a database appender for log4j through CastorJDO to our
codebase in the
To use the appender within your application you need to create tables
to hold the log information at your database. An example script to create
these tables as well as examples of mapping.xml and jdo-config.xml can
also be found in
Before you use the logger for the first time you need to initialize CastorJDO.
Thereafter you can use your logger as usual. Log4j will use CastorAppender to write the log information to the database.
One additional thing you need to take care of: As CastorAppender does some caching to reduce database operations, you have to tell it to write all cached information to database before you close your application.
We also provided a way to extend the information logged to database. For an example extension take a look at LogReferenceExtension and TestCastorAppender classes as well as the example mapping file.
Special getter methods for XML mapping
As part of a field mapping, it is now possible to specify two special methods that will be treated in a non-standard way. If the 'get-method' specified on a field mapping starts with either 'enum' or 'iterate', it will be treated in a way that the collection (container) is only exposed through this 'enumeration'/'iteration' method.
Added new property org.exolab.castor.sax.features-to-disable
To disabled selected features on the XML parser used internally by Castor XML, please use the new property org.exolab.castor.sax.features-to-disable as shown below
# Comma separated list of SAX 2 features that should be disabled # for the default parser. #org.exolab.castor.sax.features-to-disable
Added new CTF test case type to test source generation only, especially useful for regression tests of exceptions thrown during source generation
For a sample and for the place to add future test cases for the Master Test Suite, see the directory tree src/tetsts/xml/MasterTestSuite/sourcegenerator/generationOnly, although regression tests should be added to the regression suite
Support for Progress
Support for Progress has been added. For initial information about configuration of Castor JDO for the use with Progress, please see src/tests/jdo/progress.xml.
New unmarshal() methods for Unmarshaller
In addition to the already existing methods, two new unmarshal() methods have been added to Unmarshaller, namely ...
Fixed problems - Overview
Source generator now supports Java 5.0
The Castor source generator now supports the generation of Java 5.0
compliant classes. The generated code - with the new feature
enabled - will make use of the following Java 5.0-specific
To enable this feature (off by default), please uncomment the following property in your custom castorbuilder.properties file:
New property in castor.properties
Added new property to castor.properties to disable use of package-based '.castor.xml' files during class resolution selectively, which is enabled by default.
To disable this feature, please uncomment the following property in your custom castor.properties file:
Internal handling of idenities
In the past Castor differentiated between single and multiple field identities of persistent objects. For single field identities Castor hold the identitiy object itself while the objects of a multiple field identity where wrapped by an instance of Complex class. This caused various if-then-else constructs to differentiat the 2 representations of identities.
With the refactoring identities are now always wrapped by an instance of Identity class being it a single or a multiple fields one. This resulted in much cleaner code at various areas and in addition we could improve type checking by declaring lots of properties and parameters to be of Identity class instead of simply Object.
While we could manage to be backward compatible for all methods that
gets an identity passed (e.g.
You have to be aware that you need to adapt your code to get things
working as before if you use
Creation of MappingLoaders
As of release 1.0.2 the MappingLoader implementations need to be configured in castor.properties file. While this also allows to specify external MappingLoader implementations to be used by Castor, it now is also required to specify the 2 internal implementations in this file.
# # MappingLoader implementations # org.castor.mapping.Loaders=\ org.exolab.castor.jdo.engine.JDOMappingLoader,\ org.exolab.castor.xml.XMLMappingLoader
You have to be aware that you need add the new configuration property to you custom castor.properties file.
On April 14. 2006 we have migrated Castor source repository from CVS to SVN. At the moment we still provide read only access to CVS but this does not reflect commits to SVN after the migration. The read only access to CVS is intended for you to create patches of your current work and move it over to SVN. Be aware that we will switch off CVS soon.
For details about SVN access please have a look at: SVN/JIRA.
Added support for ehCache
at class mapping you can now use ehCache with Castor JDO. As of ehcache 1.2, ehcache can be used as a distributed cache.
Added support for Gigaspaces
at class mapping you can now use Gigaspaces with Castor JDO, supporting all possible use scenarios of Gigaspaces (local cache, remote cache, local master cache, distributed cache, partitions) in a flexible way.
ANSI-SQL-92 compliance for MS SQLServer
Refactored the SQLServer-specific classes to support ANSI-SQL-92 compliant syntax in addition to the existing code base.
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.
For all the releases prior to 1.0, the release notes can be found at here.