Skip to end of metadata
Go to start of metadata

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:

CastorMarshallerListener.java
CastorMarshaller inner classes

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

MarshallerListener.java
UnmarshallerListener.java

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:

spring-oxm-3.1.xsd

Which allows to configure marshaller in simpler manner.
Examples:

JAXB
JiBX
XmlBeans

Proposition

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

Castor

XSD

The XSD for such xml definition can be defined as:

Castor-Marshaller XSD

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:

CastorMarshallerBeanDefinitionParser.java

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:

CastorMarshaller.java

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:

Castor-Marshaller additional attributes

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

Loading
T Key Summary Assignee Reporter P Status Resolution Created Updated Due
Improvement CASTOR-3066 Extend the CastorMarshaller with additional properties (part 1). Jakub Narloch Jakub Narloch Major Resolved Fixed May 02, 2011 May 05, 2011
Improvement CASTOR-3067 Extend the CastorMarshaller with additional properties (part 2). Jakub Narloch Jakub Narloch Major Resolved Fixed May 02, 2011 Jun 20, 2011
Improvement CASTOR-3068 CastorMarshaller documentation. Jakub Narloch Jakub Narloch Major Resolved Won't Fix May 02, 2011 Apr 22, 2012
Improvement CASTOR-3069 Propose and implement additional overloaded method for unmarshalling different "sources" for CastorMarshaller. Jakub Narloch Jakub Narloch Major Resolved Fixed May 02, 2011 May 21, 2011
Improvement CASTOR-3070 Spring OXM schema base configuration improvment. Jakub Narloch Jakub Narloch Major Resolved Fixed May 02, 2011 May 22, 2011
Improvement CASTOR-3071 Propose changes for Spring Refernce covering the changes made in Spring OXM related with Castor. Jakub Narloch Jakub Narloch Major Resolved Fixed May 02, 2011 Apr 17, 2012
Task CASTOR-3072 Create and maintain documentation about changes made in Spring OXM. Jakub Narloch Jakub Narloch Major Resolved Fixed May 02, 2011 Aug 18, 2011
Improvement CASTOR-3078 Further Spring OXM schema base configuration enhancement. Jakub Narloch Jakub Narloch Major Resolved Fixed May 09, 2011 Jun 08, 2011
Improvement CASTOR-3099 Provide integration tests for CastorMarshaller. Jakub Narloch Jakub Narloch Major Resolved Fixed May 30, 2011 Jun 14, 2011
Bug CASTOR-3114 Error occurs when unmarshalling xml with additional elements. Jakub Narloch Jakub Narloch Major Resolved Fixed Jun 20, 2011 Jun 27, 2011
Improvement CASTOR-3126 Documentation - Running CTF through mvn pluggin Werner Guttmann Jakub Narloch Major Resolved Fixed Jun 27, 2011 Jun 30, 2011
Improvement CASTOR-3127 Additional tests for xml framework Werner Guttmann Jakub Narloch Major Resolved Fixed Jun 27, 2011 Jun 27, 2011
Improvement CASTOR-3133 XML Marshaller and Unmarshaller tests Werner Guttmann Jakub Narloch Major Resolved Fixed Jun 29, 2011 Jun 30, 2011
Improvement CASTOR-3134 Refactored code redundancies in (Un-)Marshaller classes. Werner Guttmann Jakub Narloch Major Resolved Fixed Jun 29, 2011 Jun 30, 2011
Bug CASTOR-3135 Exception occurs during unmarshaling, when both idresolver is present and validation is set to true. Werner Guttmann Jakub Narloch Major Open Unresolved Jun 29, 2011 May 05, 2012
Improvement CASTOR-3138 Common Assert utility class. Werner Guttmann Jakub Narloch Major Resolved Fixed Jul 03, 2011 Jul 04, 2011
Bug CASTOR-3139 The XmlClassDescriptor isn't updated when modifing the org.exolab.castor.xml.naming property. Jakub Narloch Jakub Narloch Major Open Unresolved Jul 05, 2011 May 16, 2012
Improvement CASTOR-3143 Split CastorMarshaller into two seperate classes. Jakub Narloch Jakub Narloch Major Resolved Won't Fix Jul 08, 2011 Aug 19, 2011
Improvement CASTOR-3144 Rename the properties of CastorMarshaller to make them more accurate. Jakub Narloch Jakub Narloch Major Resolved Won't Fix Jul 08, 2011 Aug 18, 2011
Task CASTOR-3147 Create a SpringWS example that will use Castor as a marshaller. Jakub Narloch Jakub Narloch Major Resolved Fixed Jul 14, 2011 Aug 18, 2011
Showing 20 out of 28 issues Refresh


  • No labels