Spring OXM improvments

Table of content:

The project

Mentor: Werner Guttman
Student: Jakub Narloch

The goal of this project will be to introduce such changes within the Spring OXM to allow full support for almost all Castor XML features.

Spring team collaboration

Spring Improvments

After finishing the Castor-3066 task two issues were created in Spring SPR JIRA (Applied):
https://jira.springsource.org/browse/SPR-8295
https://jira.springsource.org/browse/SPR-8296

Task Castor-3070 ended with creating task in SPR JIRA (Applied):
https://jira.springsource.org/browse/SPR-8309

For task Castor-3069 another issue has been created (Applied):
https://jira.springsource.org/browse/SPR-8341

The task Castor-3078 has been resolved with SPR issue (Rejected):
https://jira.springsource.org/browse/SPR-8423

Task CASTOR-3099 got his own Spring JIRA issue (Applied):
https://jira.springsource.org/browse/SPR-8453

Spring JIRA issue for Castor-3067:
https://jira.springsource.org/browse/SPR-8470

Spring EBR (Enterprise Boundle Repository)

Current Spring OXM version uses Castor 1.2, in other to implement all the features mentioned in the proposal the version need to be changed to 1.3.2

I had prepared the current Castor release (1.3.2) and created a Jira issue in other to contribute it into Spring ERB (Resolved - SpringOXM 3.1 will use Castor 1.3.2):
https://issuetracker.springsource.com/browse/EBR-747

The ideas

Extending CastorMarshaller with addtional properties [Castor-3066 and Castor-3067]

Description

The CastorMarshaller covers only part of the functionality that the Castor Marshaller/Unmarshaller provides.
So the main aim of this task will be to implement the missing properties/methods and expose them through CastorMarshaller.

The list of the properties: that will be implemented:

Simple properties

Summary of changes made for Castor-3066 task:

All the 'simple' properties had been implemented as part of this task

Complex properties

Proposal for MarshalListener and UnmarshalListener

In other to handle the (Un-)MarshalListener in Spring addtional interface is going to be needed. There are two possibilites here. First one, the listener could be introduced only for CastorMarshaller. Second, it can be defined for both Marshaller and Unmarshaller interfaces.

In first approche a custom CastorMarshallerListener interface is introduced to, whtich is then used by two addapter classes:

The second possibility is to add those listeners to org.springframework.oxm for all marshallers.

Spring OXM schema base configuration improvment [CASTOR-3070]

Description

The schema base configuration is a neet way for configuring marshaller in spring, unfortunetly the current version dosen't provide such support for Castor.
The task provides extend proper Spring OXM schema with additional element definition in other to provide a simmple way for configuring the Castor marshaller for most common cases.

Currently the Spring OXM XSD looks like this:

Which allows to configure marshaller in simpler manner.
Examples:

Proposition

The proposal for Castor is to create a element definition that will allow to define a marshaller as below:

XSD

The XSD for such xml definition can be defined as:

Implementation

The schema based configuration uses Spring Tool schema and a set of classes to resolve the namespace names and bean definitions.

In other to support the proposed changes a CastorMarshallerBeanDefinitionParser has been introduced, it main role is parsing the castor-marshaller defintion:

Additional methods for unmarshalling different sources [Castor-3069]

Castor exposes through it's Marsahller and Unmarshaller a set of methods for handling different 'sources', considering different types of parsers.

In version 1.3.2 Castor implemented fallowing methods:

• Marshalling methods:

• Unmarshalling methods:

All the marshalling methods are utilize by Spring so no changes are required, as for unmarshalling the two methods have been revritten to use Castor 'native' support.

Changes were made in unmarshalXmlEventReader and unmarshalXmlStreamReader:

Additionaly four methods that are present in Castor are not currently used, however implementing such support will be connected with modifing the AbstractMarshaller interface and in effect all other marsahllers.

Further enhancement for Spring OXM schema. [CASTOR-3078]

The idea is to extend previously defined element with additional attributes.
For example:

Provide integration tests [CASTOR-3099]

Since the additional properties has been implemented in CastorMarshaller, it would be really usefull to have integration test that make sure that changing the properties affect the result.

CastorMarshaller documentation [CASTOR-3068]

CastorMarshaller class is lacking in javadoc documentation. During this project I will document all the newly implemented changes.

The class documentation could also benefit if it would contain some examples how the marshaller can be configured in spring and how it should be used.

Spring reference [CASTOR-3071]

It would be usefull to document the introduced changes during this project and prepare a patch for the Spring reference that would briefly describe new functinality.

Setting the envrionment

Prerequisites

In other to enquire the source code and build Spring You will need:

1. SVN client (for example Tortoise SVN)
2. Java SDK 1.6
3. Ant 1.7
4. Maven
5. An IDE (I used Spring Tool Suite - but it could by any other IDE, like InteliJ Idea or plain-old Eclipse)

Checking out Spring sources

Although the project is limited only to Spring OXM module, the project itself relies on Spring Core, Beans and Context so You would require at least those 4 modules. Unfortunetly the graph of dependencies if even more complex so I checkout whole project instead.

You can find the head revision of the Spring framework here:
https://src.springframework.org/svn/spring-framework/

Building Spring Framework

After aquiring the sources You need to build the current release. The Spring build may look quite complex at the first sign since it uses Ant both with Ivy and Maven in the same time.

To build the framework:

• Navigate to: build-spring-framework directory

• Execute:
  > ANT_OPTS="-XX:MaxPermSize=1024m -Xmx1024m -Dtest.vm.args='-XX:MaxPermSize=512m -Xmx1024m'"
  (on Windows the command is bit different:
  > set ANT_OPTS=-XX:MaxPermSize=1024m -Xmx1024m -Dtest.vm.args=-XX:MaxPermSize=512m -Xmx1024m)

• Compile all the modules (and run the unit test) by simply executing:
  > ant
  The ivy will download all the dependencies so You won't need to resolve them by yourself. Althought there is a problem with that target, for unknown for me reasons some of the test in different modules failes.

• Instead You could try:
  > ant jar
  This will compile and package all the modules, skipping the tests. After the build You still need to install the current release in the local maven repository with:
  > ant install-maven

And that all You need to do.

Note: If You need more details You can find them in readme.txt file in build-spring-framework or on the Spring blog site http://blog.springsource.com/2009/03/03/building-spring-3/

Building Spring OXM

After completing steps described above You may move now to build Spring OXM module, since all the required dependencies has been installed in maven repository.

Compiling project and running the test is the same as in above case, running ant without specified target will execute the default target
> ant

If You need to run only the tests execute:
> ant test

For building the module You can execute:
> ant jar

Importing the project into Spring Tool Suite

Definig the IVY_CACHE path variable. The variable is used as to point to the root directory which contains all the dependencies.

1. Click on Preferences menu option
2. Type classpath to narrow the options list
3. Select Classpath Variables
4. Enter IVY_CACHE as name and full path to Ivy repository within the checkout directory: ${checkout dir}/ivy-cache/repository
5. Save the changes

Importing project into Spring Tool Suite is pretty easy:

1. Click File > Import
2. Choose General | Existing Projects into Workspace
3. Click Next
4. Point the directory where You have checkout the sources
5. Click Finish (You may optionally whant to limit the list of modules that will be imported)

Useful Resources

Spring Issue Tracker (JIRA)
Spring ERB Issue Tracker (JIRA)
Spring SVN

Project JIRA Issues