<html><head><META http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Contributing to Castor</title><link href="default.css" rel="stylesheet"></head><body marginwidth="0" marginheight="0" leftmargin="0" bottommargin="0" topmargin="0" vlink="#6763a9" link="#6763a9" bgcolor="#ffffff"><a name="top"></a><table height="400" cellspacing="0" cellpadding="0" border="0"><tr><td bgcolor="#7270c2" align="left" valign="top" width="10"><img border="0" height="1" width="1" src="images/dotTrans.gif"></td><td bgcolor="#7270c2" align="left" valign="top" width="150"><img border="0" height="1" width="1" src="images/dotTrans.gif"></td><td align="left" valign="top" width="7"><img height="1" width="1" border="0" src="images/dotTrans.gif"></td><td align="left" valign="top" width="70"><img border="0" height="6" width="70" src="images/dotTrans.gif"></td><td align="left" valign="top" width="100%"><img border="0" height="6" width="100%" src="images/top_2.gif"></td></tr><tr><td align="left" valign="top" bgcolor="#7270c2" width="10"><img height="1" width="1" border="0" src="images/dotTrans.gif"></td><td align="left" valign="top" bgcolor="#7270c2" width="150"><img height="1" width="1" border="0" src="images/dotTrans.gif"></td><td align="left" valign="top" bgcolor="#ffffff" width="7"></td><td align="left" valign="top" width="70"><img border="0" height="1" width="1" src="images/dotTrans.gif"></td><td align="left" valign="middle" width="100%"><a href="license.html"><span class="menuTopOff">License</span></a> <a href="http://www.codehaus.org"><span class="menuTopOff">Codehaus</span></a> <a href="http://openejb.org"><span class="menuTopOff">OpenEJB</span></a> <a href="http://openjms.sf.net"><span class="menuTopOff">OpenJMS</span></a> <a href="http://openorb.sf.net"><span class="menuTopOn">OpenORB</span></a> <a href="http://tyrex.sf.net"><span class="menuTopOff">Tyrex</span></a> <br><img border="0" height="2" width="1" src="images/dotTrans.gif"></td></tr><tr><td align="left" valign="top" bgcolor="#7270c2" width="10"><img border="0" height="3" width="10" src="images/dotTrans.gif"></td><td align="right" valign="top" bgcolor="#7270c2" width="150"><img border="0" height="3" width="105" src="images/line_sm.gif"></td><td align="left" valign="top" bgcolor="#a9a5de" width="7"><img border="0" height="3" width="7" src="images/line_sm.gif"></td><td align="left" valign="top" width="70"><img border="0" height="3" width="70" src="images/line_light.gif"></td><td align="left" valign="top" width="100%"><img border="0" height="3" width="100%" src="images/line_light.gif"></td></tr><tr><td align="left" valign="top" bgcolor="#7270c2"><img border="0" height="10" width="10" src="images/dotTrans.gif"></td><td align="left" valign="top" bgcolor="#7270c2" width="150"><img border="0" height="2" width="1" src="images/dotTrans.gif"><br><table cellspacing="0" cellpadding="10" border="0"><tr><td><script src="http://www.ohloh.net/p/3635/widgets/project_users_logo.js" type="text/javascript"></script></td></tr></table><table cellspacing="0" cellpadding="0" border="0"><tr><td align="left" valign="top"><span class="subMenuOn">Old releases</span></td></tr><tr><td align="left" valign="top">
<a href="releases-old.html"><span class="subMenuOff">General</span></a></td></tr><tr><td align="left" valign="top">
<a href="http://www.castor.org/1.3/index.html"><span class="subMenuOff">Release 1.3</span></a></td></tr><tr><td align="left" valign="top">
<a href="http://www.castor.org/1.3rc1/index.html"><span class="subMenuOff">Release 1.3rc1</span></a></td></tr><tr><td align="left" valign="top">
<a href="http://www.castor.org/1.2/index.html"><span class="subMenuOff">Release 1.2</span></a></td></tr></table><br><table cellspacing="0" cellpadding="0" border="0"><tr><td align="left" valign="top"><span class="subMenuOn">Main</span></td></tr><tr><td align="left" valign="top">
<a href="index.html"><span class="subMenuOff">Home</span></a></td></tr><tr><td align="left" valign="top">
<a href="about.html"><span class="subMenuOff">About</span></a></td></tr><tr><td align="left" valign="top">
<a href="features.html"><span class="subMenuOff">Features</span></a></td></tr><tr><td align="left" valign="top">
<a href="download.html"><span class="subMenuOff">Download</span></a></td></tr><tr><td align="left" valign="top">
<a href="dependencies.html"><span class="subMenuOff">Dependencies</span></a></td></tr><tr><td align="left" valign="top">
<a href="reference-guide.html"><span class="subMenuOffHighlighted">Reference guide</span></a></td></tr><tr><td align="left" valign="top">
<a href="presentations.html"><span class="subMenuOff">Publications</span></a></td></tr><tr><td align="left" valign="top">
<a href="javadoc/overview-summary.html"><span class="subMenuOff">JavaDoc</span></a></td></tr><tr><td align="left" valign="top">
<a href="maven-integration.html"><span class="subMenuOff">Maven 2 support</span></a></td></tr><tr><td align="left" valign="top">
<a href="maven-archetypes.html"><span class="subMenuOff">Maven 2 archetypes</span></a></td></tr><tr><td align="left" valign="top">
<a href="schema.html"><span class="subMenuOff">DTD & Schemas</span></a></td></tr><tr><td align="left" valign="top">
<a href="changes.html"><span class="subMenuOff">Recent HTML changes</span></a></td></tr><tr><td align="left" valign="top">
<a href="news.html"><span class="subMenuOff">News Archive</span></a></td></tr><tr><td align="left" valign="top">
<a href="http://castor.codehaus.org/rss/castor-announce.xml"><span class="subMenuOff">RSS news feed</span></a></td></tr><tr><td align="left" valign="top">
<a href="http://docs.codehaus.org/display/CASTOR/"><span class="subMenuOffHighlighted">Project Wiki</span></a></td></tr></table><br><table cellspacing="0" cellpadding="0" border="0"><tr><td align="left" valign="top"><span class="subMenuOn">Development/Support</span></td></tr><tr><td align="left" valign="top">
<a href="lists.html"><span class="subMenuOff">Mailing Lists</span></a></td></tr><tr><td align="left" valign="top">
<a href="scm.html"><span class="subMenuOff">SVN/JIRA</span></a></td></tr><tr><td align="left" valign="top">
<a href="contributing.html"><span class="subMenuOff">Contributing</span></a></td></tr><tr><td align="left" valign="top">
<a href="support.html"><span class="subMenuOff">Support</span></a></td></tr><tr><td align="left" valign="top">
<a href="http://bamboo.ci.codehaus.org/browse/CASTOR"><span class="subMenuOff">Continuous builds</span></a></td></tr><tr><td align="left" valign="top">
<a href="professional-services.html"><span class="subMenuOffHighlighted">Prof. services</span></a></td></tr></table><br><table cellspacing="0" cellpadding="0" border="0"><tr><td align="left" valign="top"><span class="subMenuOn">Related projects</span></td></tr><tr><td align="left" valign="top">
<a href="spring-orm-integration.html"><span class="subMenuOff">Spring ORM support</span></a></td></tr><tr><td align="left" valign="top">
<a href="spring-xml-intro.html"><span class="subMenuOff">Spring XML factories</span></a></td></tr><tr><td align="left" valign="top">
<a href="ws-integration.html"><span class="subMenuOff">WS frameworks</span></a></td></tr></table><br><table cellspacing="0" cellpadding="0" border="0"><tr><td align="left" valign="top"><span class="subMenuOn">XML</span></td></tr><tr><td align="left" valign="top">
<a href="xml-link.html"><span class="subMenuOff">XML</span></a></td></tr></table><br><table cellspacing="0" cellpadding="0" border="0"><tr><td align="left" valign="top"><span class="subMenuOn">XML Code Generator</span></td></tr><tr><td align="left" valign="top">
<a href="srcgen-link.html"><span class="subMenuOff">XML Code Generator</span></a></td></tr></table><br><table cellspacing="0" cellpadding="0" border="0"><tr><td align="left" valign="top"><span class="subMenuOn">JDO</span></td></tr><tr><td align="left" valign="top">
<a href="jdo-introduction.html"><span class="subMenuOff">Introduction</span></a></td></tr><tr><td align="left" valign="top">
<a href="jdo-starter-tutorial.html"><span class="subMenuOff">First steps</span></a></td></tr><tr><td align="left" valign="top">
<a href="jdo.html"><span class="subMenuOff">Using JDO</span></a></td></tr><tr><td align="left" valign="top">
<a href="jdo-database-conf.html"><span class="subMenuOff">JDO Config</span></a></td></tr><tr><td align="left" valign="top">
<a href="types.html"><span class="subMenuOff">Types</span></a></td></tr><tr><td align="left" valign="top">
<a href="jdo-mapping.html"><span class="subMenuOff">JDO Mapping</span></a></td></tr><tr><td align="left" valign="top">
<a href="jdo-faq.html"><span class="subMenuOff">JDO FAQ</span></a></td></tr><tr><td align="left" valign="top">
<a href="jdo-examples.html"><span class="subMenuOff">JDO Examples</span></a></td></tr><tr><td align="left" valign="top">
<a href="jdo-howto.html"><span class="subMenuOffHighlighted">JDO HOW-TOs</span></a></td></tr><tr><td align="left" valign="top">
<a href="jdo-tips-tricks.html"><span class="subMenuOffHighlighted">Tips & Tricks</span></a></td></tr><tr><td align="left" valign="top">
<a href="jdo-other-features.html"><span class="subMenuOff">Other Features</span></a></td></tr><tr><td align="left" valign="top">
<a href="jdo-self-executable-examples.html"><span class="subMenuOff">JDO sample JAR</span></a></td></tr></table><br><table cellspacing="0" cellpadding="0" border="0"><tr><td align="left" valign="top"><span class="subMenuOn">Tools</span></td></tr><tr><td align="left" valign="top">
<a href="schemaGen-anttask.html"><span class="subMenuOff">Schema generator</span></a></td></tr></table><br><table cellspacing="0" cellpadding="0" border="0"><tr><td align="left" valign="top"><span class="subMenuOn">Advanced JDO</span></td></tr><tr><td align="left" valign="top">
<a href="jdo-caching-detail.html"><span class="subMenuOff">Caching</span></a></td></tr><tr><td align="left" valign="top">
<a href="oql.html"><span class="subMenuOff">OQL</span></a></td></tr><tr><td align="left" valign="top">
<a href="locking.html"><span class="subMenuOff">Trans. & Locks</span></a></td></tr><tr><td align="left" valign="top">
<a href="design-persist.html"><span class="subMenuOff">Design</span></a></td></tr><tr><td align="left" valign="top">
<a href="key-generator.html"><span class="subMenuOff">KeyGen</span></a></td></tr><tr><td align="left" valign="top">
<a href="long-transact.html"><span class="subMenuOff">Long Trans.</span></a></td></tr><tr><td align="left" valign="top">
<a href="nested-attr.html"><span class="subMenuOff">Nested Attrs.</span></a></td></tr><tr><td align="left" valign="top">
<a href="jdo-pooling.html"><span class="subMenuOff">Pooling Examples</span></a></td></tr><tr><td align="left" valign="top">
<a href="postgresql-blobs.html"><span class="subMenuOff">LOBs</span></a></td></tr><tr><td align="left" valign="top">
<a href="jdo-best-practice.html"><span class="subMenuOff">Best practice</span></a></td></tr></table><br><table cellspacing="0" cellpadding="0" border="0"><tr><td align="left" valign="top"><span class="subMenuOn">DDL Generator</span></td></tr><tr><td align="left" valign="top">
<a href="ddlgen.html"><span class="subMenuOff">Using DDL Generator</span></a></td></tr><tr><td align="left" valign="top">
<a href="ddlgen-properties.html"><span class="subMenuOff">Properties</span></a></td></tr><tr><td align="left" valign="top">
<a href="ddlgen-anttask.html"><span class="subMenuOff">Ant task</span></a></td></tr><tr><td align="left" valign="top">
<a href="ddlgen-mapping.html"><span class="subMenuOff">Type Mapping</span></a></td></tr></table><br><table cellspacing="0" cellpadding="0" border="0"><tr><td align="left" valign="top"><span class="subMenuOn">More</span></td></tr><tr><td align="left" valign="top">
<a href="examples.html"><span class="subMenuOff">The Examples</span></a></td></tr><tr><td align="left" valign="top">
<a href="extras.html"><span class="subMenuOff">3rd Party Tools</span></a></td></tr><tr><td align="left" valign="top">
<a href="test-framework.html"><span class="subMenuOff">JDO Tests</span></a></td></tr><tr><td align="left" valign="top">
<a href="ctf.html"><span class="subMenuOff">XML Tests</span></a></td></tr><tr><td align="left" valign="top">
<a href="conf-lib.html"><span class="subMenuOff">Configuration</span></a></td></tr><tr><td align="left" valign="top">
<a href=""><span class="subMenuOff"></span></a></td></tr><tr><td align="left" valign="top">
<a href="http://www.java.net/"><span class="subMenuOff"><img border="0" src="images/javanet_button_90.gif"></span></a></td></tr></table><br><table cellspacing="0" cellpadding="0" border="0"><tr><td align="left" valign="top"><span class="subMenuOn">About</span></td></tr><tr><td align="left" valign="top">
<a href="license.html"><span class="subMenuOff">License</span></a></td></tr><tr><td align="left" valign="top">
<a href="user-experience.html"><span class="subMenuOffHighlighted">User stories</span></a></td></tr><tr><td align="left" valign="top">
<a href="contributors.html"><span class="subMenuOff">Contributors</span></a></td></tr><tr><td align="left" valign="top">
<a href="marketplace.html"><span class="subMenuOff">Marketplace</span></a></td></tr><tr><td align="left" valign="top">
<a href="status.html"><span class="subMenuOff">Status, Todo</span></a></td></tr><tr><td align="left" valign="top">
<a href="release-notes.html"><span class="subMenuOff">Changelog</span></a></td></tr><tr><td align="left" valign="top">
<a href="library.html"><span class="subMenuOff">Library</span></a></td></tr><tr><td align="left" valign="top">
<a href="contacts.html"><span class="subMenuOff">Contact</span></a></td></tr><tr><td align="left" valign="top">
<a href="origins.html"><span class="subMenuOff">Project Name</span></a></td></tr></table><br></td><td align="left" valign="top" bgcolor="#a9a5de" width="7"> </td><td align="left" valign="top" width="70"> </td><td valign="top" width="100%" rowspan="4"><table width="100%" cellspacing="0" cellpadding="0" border="0" rows="2" cols="2"><tr><td align="left" valign="top"><br><img width="115" vspace="0" src="images/castor.gif" hspace="0" height="34" border="0"><br><img src="images/dotTrans.gif" hspace="0" height="10" border="0"></td><td align="right" valign="top" height="5" width="120"></td></tr></table><p></p><p></p><br><h2 align="center">Contributing to Castor</h2><p align="center">
Documentation Author(s):<br>Werner Guttmann<br></p><HR size="1"><span class="bodyGrey"><b><a href="#Introduction">Introduction</a></b><br></span><span class="bodyGrey"><b><a href="#Useful-links">Useful links</a></b><br></span><span class="bodyGrey"><b><a href="#Guidelines-For-Code-Contribution">Guidelines For Code Contribution</a></b><br></span><span class="bodyGrey"><b><a href="#Guidelines-For-Committers">Guidelines For Committers</a></b><br></span><span class="bodyGrey"><b><a href="#Licensing-Policy">Licensing Policy</a></b><br></span><span class="bodyGrey"><b><a href="#Building-Castor">Building Castor</a></b><br></span><span class="bodyGrey"><a href="#Project-layout"> Project layout</a><br></span><span class="bodyGrey"><a href="#Directory-Structures-(globally)"> Directory Structures (globally)</a><br></span><span class="bodyGrey"><a href="#Directory-Structure-within-a-module"> Directory Structure within a module</a><br></span><span class="bodyGrey"><a href="#Building-code"> Building code</a><br></span><span class="bodyGrey">
<a href="#Using-Maven-2">Using Maven 2</a><br></span><span class="bodyGrey"><a href="#Several-Castor-checkouts-parallel-in-Eclipse"> Several Castor checkouts parallel in Eclipse</a><br></span><span class="bodyGrey"><b><a href="#Castor-and-Eclipse">Castor and Eclipse</a></b><br></span><HR size="1"><br><a name="Introduction"><h2>Introduction</h2></a>
<p><span class="bodyGrey">
The Castor project is an Open Source project hosted at the
<a href="http://www.codehaus.org">Codehaus</a>, 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.
</span></p>
<p><span class="bodyGrey">
To begin with, we suggest you to subscribe to the
<a href="lists.html">Castor mailing lists</a>. We recommend that you listen
for a while to hear how others make contibutions.
</span></p>
<p><span class="bodyGrey">
You can get your local working copy of the current code base (of any particular
release) from the <a href="scm.html">Castor SVN repository</a>. Review the list
of unassigned issues in <a href="http://jira.codehaus.org/browse/CASTOR">Jira</a>
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.
</span></p>
<p><span class="bodyGrey">
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..
</span></p>
<a name="Useful-links"><h2>Useful links</h2></a>
<table cellspacing="2" cellpadding="2" border="0"><tr><td height="5" colspan="2"></td></tr><span class="bodyGrey">
<tr><td width="10" valign="top" align="left">-</td><td valign="top" align="left"><span class="bodyGrey"><a href="how-to-run-xml-ctf-suite.html">How to run CTF test suite</a></span></td></tr>
<tr><td width="10" valign="top" align="left">-</td><td valign="top" align="left"><span class="bodyGrey"><a href="how-to-submit-an-xml-bug.html">How to submit an XML-specific bug report</a></span></td></tr>
<tr><td width="10" valign="top" align="left">-</td><td valign="top" align="left"><span class="bodyGrey"><a href="how-to-prepare-a-patch.html">How to prepare a patch</a></span></td></tr>
</span></table>
<a name="Guidelines-For-Code-Contribution"><h2>Guidelines For Code Contribution</h2></a>
<p><span class="bodyGrey">
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.
</span></p>
<p><span class="bodyGrey">
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.
</span></p>
<p><span class="bodyGrey">It's perfectly ok to put your name and e-mail address in the code.</span></p>
<p><span class="bodyGrey">
When sending patches, unified diff files (3 lines before, 3 lines after)
work best:
</span></p>
<p></p><table bgcolor="#7270c2" cellpadding="1" cellspacing="1" border="0" width="100%"><tr><td><table bgcolor="#ededed" cellpadding="4" cellspacing="1" border="0" width="100%"><tr><td><span class="bodyBlack"><pre>
svn diff <file></pre></span></td></tr></table></td></tr></table><p></p>
<p><span class="bodyGrey">against the up-to-date SVN version, or</span></p>
<p></p><table bgcolor="#7270c2" cellpadding="1" cellspacing="1" border="0" width="100%"><tr><td><table bgcolor="#ededed" cellpadding="4" cellspacing="1" border="0" width="100%"><tr><td><span class="bodyBlack"><pre>
diff -u <file1> <file2>
</pre></span></td></tr></table></td></tr></table><p></p>
<p><span class="bodyGrey">
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.
</span></p>
<p><span class="bodyGrey">
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.
</span></p>
<p><span class="bodyGrey">
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.
</span></p>
<p><span class="bodyGrey">
The last requirement for contributing code is to create a Jira
<a href="http://jira.codehaus.org/browse/CASTOR">issue</a> 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.
</span></p>
<a name="Guidelines-For-Committers"><h2>Guidelines For Committers</h2></a>
<p><span class="bodyGrey">
<i>Familiarize yourself.</i> 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.
</span></p>
<p><span class="bodyGrey">
<i>Advertise before you start.</i> 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.
</span></p>
<p><span class="bodyGrey">
<i>Test before you commit.</i> Before committing any changes run an
<tt>svn update</tt> to make sure you have the latest code base. Run the
test cases (ideally both XML and JDO) to make sure nothing is broken.
</span></p>
<p><span class="bodyGrey">
<i>Commit all at once.</i> 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!
</span></p>
<p><span class="bodyGrey">
<i>Be ready to receive complaints.</i> 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!
</span></p>
<p><span class="bodyGrey">
<i>Put your name so people know who to credit.</i> (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.
</span></p>
<p><span class="bodyGrey">
<i>Observe release time.</i> 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.
</span></p>
<p><span class="bodyGrey">
<i>Document what you've done.</i> In-code documentation, SVN commit messages,
and the change log. Major changes should always be recorded in the changelog.
</span></p>
<p><span class="bodyGrey">
<i>Use the document DTD.</i> 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.
</span></p>
<p><span class="bodyGrey">
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.
</span></p>
<a name="Licensing-Policy"><h2>Licensing Policy</h2></a>
<p><span class="bodyGrey">
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.
</span></p>
<p><span class="bodyGrey">
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.
</span></p>
<p><span class="bodyGrey">
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.
</span></p>
<p><span class="bodyGrey">
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.
</span></p>
<a name="Building-Castor"><h2>Building Castor</h2></a>
<p><span class="bodyGrey">
As of release 1.3, Castor supports <a href="http://maven.apache.org">Maven 2</a>
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.
</span></p>
<p><table bgcolor="#7270c2" cellpadding="3" cellspacing="1" border="0" width="100%"><tr><td><span class="noteHeader">Note</span></td></tr><tr><td><table bgcolor="#ededed" cellpadding="4" cellspacing="1" border="0" width="100%"><tr><td><span class="noteBody">
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.
</span></td></tr></table></td></tr></table></p>
<p><table bgcolor="#7270c2" cellpadding="3" cellspacing="1" border="0" width="100%"><tr><td><span class="noteHeader">Note</span></td></tr><tr><td><table bgcolor="#ededed" cellpadding="4" cellspacing="1" border="0" width="100%"><tr><td><span class="noteBody">
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.
</span></td></tr></table></td></tr></table></p>
<a name="Project-layout"><h3>Project layout</h3></a>
<p><span class="bodyGrey">
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.
</span></p>
<p><span class="bodyGrey">
Currently, the following main modules are available:
</span></p>
<table bgcolor="#7270c2" cellpadding="2" cellspacing="1" width="100%" border="0"><tr><td><table bgcolor="#ededed" cellpadding="8" cellspacing="1" width="100%" border="0"><caption></caption><tr class="cheader"><td class="cheader">Name</td><td class="cheader">Description</td><td class="cheader">Since</td></tr><tr bgcolor="#DDDDDD"><td><span class="bodyGrey">anttask</span></td><td><span class="bodyGrey">Ant task definitions for Castor tools</span></td><td><span class="bodyGrey">1.0.5</span></td></tr><tr bgcolor="#FFFFFF"><td><span class="bodyGrey">core</span></td><td><span class="bodyGrey">Castor core classes</span></td><td><span class="bodyGrey">1.2.1</span></td></tr><tr bgcolor="#DDDDDD"><td><span class="bodyGrey">cpa</span></td><td><span class="bodyGrey">Castor JDO - persistence framework</span></td><td><span class="bodyGrey">1.1</span></td></tr><tr bgcolor="#FFFFFF"><td><span class="bodyGrey">xml</span></td><td><span class="bodyGrey">XML data binding framework</span></td><td><span class="bodyGrey">1.2.1</span></td></tr><tr bgcolor="#DDDDDD"><td><span class="bodyGrey">codegen</span></td><td><span class="bodyGrey">XML code generator</span></td><td><span class="bodyGrey">1.1.1</span></td></tr><tr bgcolor="#FFFFFF"><td><span class="bodyGrey">schema</span></td><td><span class="bodyGrey">XML schema support (classes)</span></td><td><span class="bodyGrey">1.2</span></td></tr><tr bgcolor="#DDDDDD"><td><span class="bodyGrey">ddlgen</span></td><td><span class="bodyGrey">Castor JDO DDL generator</span></td><td><span class="bodyGrey">1.1</span></td></tr><tr bgcolor="#FFFFFF"><td><span class="bodyGrey">examples</span></td><td><span class="bodyGrey">Examples for all functional areas</span></td><td><span class="bodyGrey">1.0.5</span></td></tr></table></td></tr></table>
<p><span class="bodyGrey">
In addition, there's various modules available that represent
integration and performance test suites for the main modules:
</span></p>
<table bgcolor="#7270c2" cellpadding="2" cellspacing="1" width="100%" border="0"><tr><td><table bgcolor="#ededed" cellpadding="8" cellspacing="1" width="100%" border="0"><caption></caption><tr class="cheader"><td class="cheader">Name</td><td class="cheader">Description</td><td class="cheader">Since</td></tr><tr bgcolor="#DDDDDD">
<td><span class="bodyGrey">xmlctf</span></td>
<td><span class="bodyGrey">Integration test suite for Castor XML</span></td>
<td><span class="bodyGrey">1.2</span></td>
</tr><tr bgcolor="#FFFFFF">
<td><span class="bodyGrey">cpactf</span></td>
<td><span class="bodyGrey">Integration test suite for Castor JDO</span></td>
<td><span class="bodyGrey">1.2</span></td>
</tr><tr bgcolor="#DDDDDD">
<td><span class="bodyGrey">cpaptf</span></td>
<td><span class="bodyGrey">Performance test suite for Castor XML</span></td>
<td><span class="bodyGrey">1.2</span></td>
</tr><tr bgcolor="#FFFFFF">
<td><span class="bodyGrey">xmlctf-framework</span></td>
<td><span class="bodyGrey">Code framework for XMLCTF</span></td>
<td><span class="bodyGrey">1.2</span></td>
</tr><tr bgcolor="#DDDDDD">
<td><span class="bodyGrey">maven-plugins</span></td>
<td><span class="bodyGrey">Maven plugins supporting execution from XMLCTF within Maven</span></td>
<td><span class="bodyGrey">1.2</span></td>
</tr></table></td></tr></table>
<p><span class="bodyGrey">
Finally, there's a module to provide Maven 2 archetypes for
Castor:
</span></p>
<table bgcolor="#7270c2" cellpadding="2" cellspacing="1" width="100%" border="0"><tr><td><table bgcolor="#ededed" cellpadding="8" cellspacing="1" width="100%" border="0"><caption></caption><tr class="cheader"><td class="cheader">Name</td><td class="cheader">Description</td><td class="cheader">Since</td></tr><tr bgcolor="#DDDDDD">
<td><span class="bodyGrey">codegen-testcase-archetype</span></td>
<td><span class="bodyGrey">Maven archetype for XML code generator</span></td>
<td><span class="bodyGrey">1.2</span></td>
</tr><tr bgcolor="#FFFFFF">
<td><span class="bodyGrey">cpa-testcase-archetype</span></td>
<td><span class="bodyGrey">Maven archetype for XML code generator</span></td>
<td><span class="bodyGrey">1.2</span></td>
</tr></table></td></tr></table>
<p><span class="bodyGrey">
Last but not least, there's a module to provide the project documentation
for Castor:
</span></p>
<table bgcolor="#7270c2" cellpadding="2" cellspacing="1" width="100%" border="0"><tr><td><table bgcolor="#ededed" cellpadding="8" cellspacing="1" width="100%" border="0"><caption></caption><tr class="cheader"><td class="cheader">Name</td><td class="cheader">Description</td><td class="cheader">Since</td></tr><tr bgcolor="#DDDDDD">
<td><span class="bodyGrey">doc</span></td>
<td><span class="bodyGrey">Project documentation (reference guide)</span></td>
<td><span class="bodyGrey">1.3rc1</span></td>
</tr></table></td></tr></table>
<a name="Directory-Structures-(globally)"><h3>Directory Structures (globally)</h3></a>
<table bgcolor="#7270c2" cellpadding="2" cellspacing="1" width="100%" border="0"><tr><td><table bgcolor="#ededed" cellpadding="8" cellspacing="1" width="100%" border="0"><caption></caption><tr class="cheader"><td class="cheader">Directory</td><td class="cheader">Description of its content</td></tr><tr bgcolor="#DDDDDD"><td><span class="bodyGrey">bin</span></td><td><span class="bodyGrey">Script/batch files required for building Castor, running samples, CTF et alias</span></td></tr><tr bgcolor="#FFFFFF"><td><span class="bodyGrey">src/doc</span></td><td><span class="bodyGrey">Documentation (in XML form)</span></td></tr><tr bgcolor="#DDDDDD"><td><span class="bodyGrey">src/schema</span></td><td><span class="bodyGrey">DTD and XML schema for Castor mapping files</span></td></tr><tr bgcolor="#FFFFFF"><td><span class="bodyGrey">src/examples</span></td><td><span class="bodyGrey">Examples for the various packages</span></td></tr><tr bgcolor="#DDDDDD"><td><span class="bodyGrey">src/etc</span></td><td><span class="bodyGrey">Additional files that are not part of the code base</span></td></tr><tr bgcolor="#FFFFFF"><td><span class="bodyGrey">lib</span></td><td><span class="bodyGrey">JARs required to build Castor and distributable JARs</span></td></tr></table></td></tr></table>
<a name="Directory-Structure-within-a-module"><h3>Directory Structure within a module</h3></a>
<table bgcolor="#7270c2" cellpadding="2" cellspacing="1" width="100%" border="0"><tr><td><table bgcolor="#ededed" cellpadding="8" cellspacing="1" width="100%" border="0"><caption></caption><tr class="cheader"><td class="cheader">Directory</td><td class="cheader">Its content</td></tr><tr bgcolor="#DDDDDD"><td><span class="bodyGrey">src/main/[java/resources]</span></td><td><span class="bodyGrey">The source base for a given Castor module</span></td></tr><tr bgcolor="#FFFFFF"><td><span class="bodyGrey">src/test/[java/resources]</span></td><td><span class="bodyGrey">The JUNit tests for the given Castor module</span></td></tr></table></td></tr></table>
<a name="Building-code"><h3>Building code</h3></a>
<p><table bgcolor="#7270c2" cellpadding="3" cellspacing="1" border="0" width="100%"><tr><td><span class="noteHeader">Note</span></td></tr><tr><td><table bgcolor="#ededed" cellpadding="4" cellspacing="1" border="0" width="100%"><tr><td><span class="noteBody">
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.
</span></td></tr></table></td></tr></table></p>
<a name="Using-Maven-2"><h4>Using Maven 2</h4></a>
<p><span class="bodyGrey">
To build Castor using Maven - assuming that you have got Maven 2
locally installed - please issue ...
</span></p>
<p></p><table bgcolor="#7270c2" cellpadding="1" cellspacing="1" border="0" width="100%"><tr><td><table bgcolor="#ededed" cellpadding="4" cellspacing="1" border="0" width="100%"><tr><td><span class="bodyBlack"><pre>
> mvn compile</pre></span></td></tr></table></td></tr></table><p></p>
<p><span class="bodyGrey">
To run the complete set of JUnit tests, issue ...
</span></p>
<p></p><table bgcolor="#7270c2" cellpadding="1" cellspacing="1" border="0" width="100%"><tr><td><table bgcolor="#ededed" cellpadding="4" cellspacing="1" border="0" width="100%"><tr><td><span class="bodyBlack"><pre>
> mvn test</pre></span></td></tr></table></td></tr></table><p></p>
<p><span class="bodyGrey">
To build the project JARs locally, issue ...
</span></p>
<p></p><table bgcolor="#7270c2" cellpadding="1" cellspacing="1" border="0" width="100%"><tr><td><table bgcolor="#ededed" cellpadding="4" cellspacing="1" border="0" width="100%"><tr><td><span class="bodyBlack"><pre>
> mvn jar</pre></span></td></tr></table></td></tr></table><p></p>
<p><span class="bodyGrey">
To install the generated JARs into your <b>local</b> Maven
repository, issue ...
</span></p>
<p></p><table bgcolor="#7270c2" cellpadding="1" cellspacing="1" border="0" width="100%"><tr><td><table bgcolor="#ededed" cellpadding="4" cellspacing="1" border="0" width="100%"><tr><td><span class="bodyBlack"><pre>
> mvn install</pre></span></td></tr></table></td></tr></table><p></p>
<p><span class="bodyGrey">
To additionally run the (plenty) integration test suites
available with Castor during testing, please issue ...
</span></p>
<p></p><table bgcolor="#7270c2" cellpadding="1" cellspacing="1" border="0" width="100%"><tr><td><table bgcolor="#ededed" cellpadding="4" cellspacing="1" border="0" width="100%"><tr><td><span class="bodyBlack"><pre>
> mvn (clean) verify</pre></span></td></tr></table></td></tr></table><p></p>
<p><span class="bodyGrey">
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:
</span></p>
<p></p><table bgcolor="#7270c2" cellpadding="1" cellspacing="1" border="0" width="100%"><tr><td><table bgcolor="#ededed" cellpadding="4" cellspacing="1" border="0" width="100%"><tr><td><span class="bodyBlack"><pre>
> mvn clean verify -Dsurefire.print.summary=true
> mvn clean test -Dsurefire.print.summary=true</pre></span></td></tr></table></td></tr></table><p></p>
<a name="Several-Castor-checkouts-parallel-in-Eclipse"><h3>Several Castor checkouts parallel in Eclipse</h3></a>
<p><span class="bodyGrey">
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.
</span></p>
<p><span class="bodyGrey">
By definition, when executing <tt>mvn eclipse:eclipse</tt>
to generate the Eclipse project files (<tt>.project</tt> and
<tt>.classpath</tt>, 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.
</span></p>
<p><span class="bodyGrey">
In order to avoid this, please execute the <tt>eclipse:eclipse</tt>
goal as follows, passing an arbitrary string to the eclipse plugin
to append to the artifact name when deducing the project name.
</span></p>
<p></p><table bgcolor="#7270c2" cellpadding="1" cellspacing="1" border="0" width="100%"><tr><td><table bgcolor="#ededed" cellpadding="4" cellspacing="1" border="0" width="100%"><tr><td><span class="bodyBlack"><pre>
mvn -Declipse.projectNameTemplate=[artifactId]-2612</pre></span></td></tr></table></td></tr></table><p></p>
<p><span class="bodyGrey">
In above sample, a Jira issue number has been used to uniquely
identify the individual modules in Eclipse.
</span></p>
<a name="Castor-and-Eclipse"><h2>Castor and Eclipse</h2></a>
<p><span class="bodyGrey">
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.
</span></p>
<table cellspacing="2" cellpadding="2" border="0"><tr><td height="5" colspan="2"></td></tr><span class="bodyGrey">
<tr><td width="10" valign="top" align="left">-</td><td valign="top" align="left"><span class="bodyGrey"><span class="bodyBlack"><pre>mvn compile</pre></span></span></td></tr>
<tr><td width="10" valign="top" align="left">-</td><td valign="top" align="left"><span class="bodyGrey"><span class="bodyBlack"><pre>mvn eclipse:eclipse</pre></span></span></td></tr>
<tr><td width="10" valign="top" align="left">-</td><td valign="top" align="left"><span class="bodyGrey">Import all Castor modules into your Eclipse workspace.</span></td></tr>
</span></table>
</td></tr><tr height="5"><td align="left" valign="top" bgcolor="#7270c2" height="5" width="10"> </td><td valign="top" bgcolor="#7270c2" height="5" width="150"><img border="0" height="15" width="1" src="images/dotTrans.gif"><br><img align="right" border="0" height="3" width="105" src="images/line_sm.gif"></td><td align="left" valign="top" bgcolor="#a9a5de" height="5" width="7"> </td><td align="left" valign="top" height="5" width="70"> </td><td align="left" valign="top" height="5" width="120"> </td></tr><tr><td align="left" valign="top" bgcolor="#7270c2" height="5" width="10"> </td><td align="left" valign="top" bgcolor="#7270c2" width="150"></td><td align="left" valign="top" bgcolor="#a9a5de" width="7"><img border="0" height="25" width="1" src="images/dotTrans.gif"></td><td align="left" valign="top" width="70"><img border="0" height="25" width="1" src="images/dotTrans.gif"></td><td align="left" valign="top" width="120"> </td></tr><tr height="5"><td align="left" valign="bottom" bgcolor="#7270c2" height="100%" rowspan="2" width="10"><img border="0" height="125" width="10" src="images/stripes1.gif"></td><td align="left" valign="bottom" bgcolor="#7270c2" height="100%" rowspan="2" width="150"><img border="0" height="125" width="105" src="images/stripe105.gif"></td><td align="left" valign="top" bgcolor="#a9a5de" height="100%" rowspan="2" width="7"> </td><td align="left" valign="top" height="100%" width="70"> </td><td align="left" valign="top" height="100%" width="120"> </td></tr><tr height="5"><td align="left" valign="top" height="25" width="70"> </td><td align="left" valign="bottom" height="25" width="400"><br><br><img height="3" width="400" border="0" src="images/line_light.gif"><br><p></p><span class="bodyGrey"><small><notice>
Copyright © 1999-2005 <a href="http://www.exolab.org">ExoLab Group</a>, Intalio Inc.,
and Contributors. All rights reserved.
</notice><br> <br></small><small><notice>
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.
</notice><br> <br></small></span><p></p>
</td><td align="left" valign="top" height="25" width="120"> </td></tr></table><script type="text/javascript">
var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl." : "http://www.");
document.write(unescape("%3Cscript src='" + gaJsHost + "google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E"));
</script><script type="text/javascript">
var pageTracker = _gat._getTracker("UA-3544187-1");
pageTracker._trackPageview();
</script></body></html>
