License     Codehaus     OpenEJB     OpenJMS     OpenORB     Tyrex     

Old releases
  Release 1.3
  Release 1.3rc1
  Release 1.2

  Reference guide
  Maven 2 support
  Maven 2 archetypes
  DTD & Schemas
  Recent HTML changes
  News Archive
  RSS news feed
  Project Wiki

  Mailing Lists
  Continuous builds
  Prof. services

Related projects
  Spring ORM support
  Spring XML factories
  WS frameworks


XML Code Generator
  XML Code Generator

  First steps
  Using JDO
  JDO Config
  JDO Mapping
  JDO Examples
  Tips & Tricks
  Other Features
  JDO sample JAR

  Schema generator

Advanced JDO
  Trans. & Locks
  Long Trans.
  Nested Attrs.
  Pooling Examples
  Best practice

DDL Generator
  Using DDL Generator
  Ant task
  Type Mapping

  The Examples
  3rd Party Tools
  JDO Tests
  XML Tests

  User stories
  Status, Todo
  Project Name


Contributing to Castor

Documentation Author(s):
Werner Guttmann

Useful links
Guidelines For Code Contribution
Guidelines For Committers
Licensing Policy
Building Castor
    Project layout
    Directory Structures (globally)
    Directory Structure within a module
    Building code
        Using Maven 2
    Several Castor checkouts parallel in Eclipse
Castor and Eclipse


The Castor project is an Open Source project hosted at the Codehaus, and it is released under a very open license. This means there are many ways to contribute to the project by e.g. coding, documenting, answering questions on the mailing lists, proposing ideas, reporting bugs, suggesting bug-fixes, and so on.

To begin with, we suggest you to subscribe to the Castor mailing lists. We recommend that you listen for a while to hear how others make contibutions.

You can get your local working copy of the current code base (of any particular release) from the Castor SVN repository. Review the list of unassigned issues in Jira and choose a task -- or perhaps you have noticed something that needs patching. (Before you start changing any code, please create a Jira task for your changes if one does not already exist.) Make your changes, test those changes, generate a patch and attach this patch to the Jira issue. If you wish, discuss this patch on the dev mailing list.

Document writers are usually the rarest and most wanted people, so if you would like to help but you're not familiar with the innermost technical details, don't worry. Other committers will spend time with you and will assist you with their knowledge. We're a friendly bunch and we appreciate anyone who is willing to commit their most valuable resource -- time -- to help out..

Useful links

-How to run CTF test suite
-How to submit an XML-specific bug report
-How to prepare a patch

Guidelines For Code Contribution

All code contributions must be under the license and copyright of the project to which you contribute. By contributing code you agree that we can distribute the contribution under the terms of the license, that it can be distributed without any royalties, copyright, trademark, patent or other legal impediments. Open source means no discrimination against any group or individual that may wish to use the code.

When making a contribution you are granting us a world wide, royalty free, unlimited-in-time license to re-distribute the code under the Exolab and/or Apache license. In case you wonder, you remain the original author and copyright holder of the contribution, you just give other people a license to use it as well, including the creation of derivative works (as long as the derivative works comply with all license terms, of course). Thank you.

It's perfectly ok to put your name and e-mail address in the code.

When sending patches, unified diff files (3 lines before, 3 lines after) work best:

  svn diff <file>

against the up-to-date SVN version, or

  diff -u <file1> <file2>

It is very important that you send test cases along with your patch of a new feature or bug fix. A test case will help the committers assess the validity of the problem in question as well as your proposed solution. In general, a test case -- showing a feature being added or bug being fixed -- proves that the patch plays along nicely with other code and does not introduce any side effects.

Committers are encouraged to commit a patch only if (s)he fully understands the patch. A test case that assists the committer in full understanding -- as mandated per the above statement -- ensures that the committer understands what the patch does. As a result, the test case encourages a prompt review and check-in.

A test case is also the easiest and most efficient way to ensure your contribution will not be broken by a future patch. It becomes even more important if your project that makes use of Castor depends on a feature or bug fix that you're contributing.

The last requirement for contributing code is to create a Jira issue and to attach your patch (in from of a unified diff) to this issue. A Jira issue allows your request to be fully traceable, as well as describing and documenting your request.

Guidelines For Committers

Familiarize yourself. Take some time to understand the directory structure, build environment, interaction between components, coding and commenting style. While nothing out of the ordinary, not all projects are identical. Code maintenance is substantially easier when all code in a project uses a similar style.

Advertise before you start. It's pointless to have two people working on the same feature. Send an e-mail to the developer mailing list and announce the what and how of your intentions. If you don't get a reply within a day then you can assume the coast is clear.

Test before you commit. Before committing any changes run an svn update to make sure you have the latest code base. Run the test cases (ideally both XML and JDO) to make sure nothing is broken.

Commit all at once. If the change involves more than a single file, make sure you commit all the changes together. A partially committed SVN tree is not a pretty sight. No lunch breaks, meetings or sleep during commits!

Be ready to receive complaints. Hopefully everything works fine, but if changes break existing code, people will complain. Be ready to answer their e-mails and apply the proper fixes. No going on vacation five minutes after a commit!

Put your name so people know who to credit. (Also who to blame). Initials work just fine, your full name and e-mail address will already be on the main page. If you've added a new file, feel free to put your name and e-mail address as the author and put your name as the copyright owner. If you're fixing a file, put your initials on the comment. Remember that JavaDoc only allows an @author tag on a class and not on a method or field.

Observe release time. We're going to announce a new release at least five hours prior to making it (often 48 hours prior). That gives you sufficient time to commit your changes in time for the release, making sure that nothing breaks. If you can't make it, there's always the next release.

Document what you've done. In-code documentation, SVN commit messages, and the change log. Major changes should always be recorded in the changelog.

Use the document DTD. When adding new documentation use the document DTD. Specify the proper document URL, properties, body and sections. Everything inside the body/header/section is XHTML. That means well formed HTML. If it's not, you won't be able to build the docs.

We don't have a particular style for documentation, and we do appreciate a sense of humor, sarcasm and literary expression. Just don't overdue it, and please, no cliche.

Licensing Policy

We have a simple policy regarding distributable code (referring, for example, to third-party JAR files that are to be included as part of the Castor source distribution). Distributable code must either be open source and compatible in license, or an API that is freely distributable.

BSD-like and MPL-like licenses are compatible and can be mixed in the same code base. Liberal licenses and public domain are also fine.

APIs need not be open source, but they must be freely distributable. As a policy we like to stick with standard APIs and never modify them to break compatibility with the API, so the license has little affect. We do favor public domains APIs like SAX over tightly controlled APIs, and hopefully we can all do something about that.

Pay special attention to pre-release availability and trademark issues before including code with Castor. Several committees and companies require proper trademark acknowledgement in documentation. Some packages or APIs are available for distribution only once they have been formally released. For example, this policy applies to all APIs coming from Sun.

Building Castor

As of release 1.3, Castor supports Maven 2 only as build management system. Please refer to the following sections as well to get an idea about the project layout, the individual modules and the structure within a module.

Any Maven release higher than 2.0.6 is fine for anybody wishing to build Castor and either run tests or generate JARs locally. Anybody wishing to deploy build artifacts to a Maven repository will have to use maven 2.0.9 or higher.

Support for Ant as build tool has been dropped completely. Please note, though, that the code base still includes Ant build files. Please do not use them! Those Ant files are in the process of being removed, which will take us some time.

Project layout

Castor is a project that is structured into (independent) modules. Those of you familiar with Maven 2 will come to realize that this layout follows a standard Maven multi-module project structure.

Currently, the following main modules are available:

anttaskAnt task definitions for Castor tools1.0.5
coreCastor core classes1.2.1
cpaCastor JDO - persistence framework1.1
xmlXML data binding framework1.2.1
codegenXML code generator1.1.1
schemaXML schema support (classes)1.2
ddlgenCastor JDO DDL generator1.1
examplesExamples for all functional areas1.0.5

In addition, there's various modules available that represent integration and performance test suites for the main modules:

xmlctf Integration test suite for Castor XML 1.2
cpactf Integration test suite for Castor JDO 1.2
cpaptf Performance test suite for Castor XML 1.2
xmlctf-framework Code framework for XMLCTF 1.2
maven-plugins Maven plugins supporting execution from XMLCTF within Maven 1.2

Finally, there's a module to provide Maven 2 archetypes for Castor:

codegen-testcase-archetype Maven archetype for XML code generator 1.2
cpa-testcase-archetype Maven archetype for XML code generator 1.2

Last but not least, there's a module to provide the project documentation for Castor:

doc Project documentation (reference guide) 1.3rc1

Directory Structures (globally)

DirectoryDescription of its content
binScript/batch files required for building Castor, running samples, CTF et alias
src/docDocumentation (in XML form)
src/schemaDTD and XML schema for Castor mapping files
src/examplesExamples for the various packages
src/etcAdditional files that are not part of the code base
libJARs required to build Castor and distributable JARs

Directory Structure within a module

DirectoryIts content
src/main/[java/resources]The source base for a given Castor module
src/test/[java/resources]The JUNit tests for the given Castor module

Building code

Please note that the code base still includes Ant build files. Please do not use them! Those remaining Ant files in the trunk are in the process of being removed, which will take us some more time.

Using Maven 2

To build Castor using Maven - assuming that you have got Maven 2 locally installed - please issue ...

> mvn compile

To run the complete set of JUnit tests, issue ...

> mvn test

To build the project JARs locally, issue ...

> mvn jar

To install the generated JARs into your local Maven repository, issue ...

> mvn install

To additionally run the (plenty) integration test suites available with Castor during testing, please issue ...

> mvn (clean) verify

By default, JUnit summary test output is excluded from both unit and integration tests. To have this output (re)enabled, please use the following Maven goals:

> mvn clean verify -Dsurefire.print.summary=true
> mvn clean test -Dsurefire.print.summary=true

Several Castor checkouts parallel in Eclipse

In case you need to check out Castor more than once - as you may be working on several Jira issues at the same time - you'll come across a subtle problem related to how multi-module Maven projects are being integrated with Eclipse.

By definition, when executing mvn eclipse:eclipse to generate the Eclipse project files (.project and .classpath, amongst others) for all the modules, Maven will use the artifact names of the module as Eclipse project name - which is fine as long as you are working with one checkout only at a time. When wanting to use several checkouts in parallel, this will cause name collisions.

In order to avoid this, please execute the eclipse:eclipse goal as follows, passing an arbitrary string to the eclipse plugin to append to the artifact name when deducing the project name.

mvn -Declipse.projectNameTemplate=[artifactId]-2612

In above sample, a Jira issue number has been used to uniquely identify the individual modules in Eclipse.

Castor and Eclipse

In order to develop Castor sources with Eclipse, you will have to perform the following steps so that you are fully enabled to code with Eclipse.

mvn compile
mvn eclipse:eclipse
-Import all Castor modules into your Eclipse workspace.

Copyright © 1999-2005 ExoLab Group, Intalio Inc., and Contributors. All rights reserved.
Java, EJB, JDBC, JNDI, JTA, Sun, Sun Microsystems are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States and in other countries. XML, XML Schema, XSLT and related standards are trademarks or registered trademarks of MIT, INRIA, Keio or others, and a product of the World Wide Web Consortium. All other product names mentioned herein are trademarks of their respective owners.