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.