This HOW-TO provide users with instructions on hot to configure Castor JDO so that Apache Jakarta's DBCP package is used as a connection pool.
Anyone who wants to use DBCP as connection pool mechanism with Castor JDO.
Below are defined the steps to configure Castor JDO to use DBCP's BasicDataSource for connection pooling.
To use a DBCP BasicDataSource with Castor JDO, please provide the following <data-source> entry in the jdo-conf.xml file.
Above example makes use of the mySQL JDBC driver to establish a connection pool to a mySQL instance named 'test' running on the same machine as Castor itself. The pool initially holds 10 connections, but is configured to allow a maximum of 40 active connections at the same time.
At the time of this writing Castor JDO has 3 kinds of test suites:
This document provides general information about running Castor JDO's test suite (CTF).
Anyone who wants to run the CTF test suite. This document outlines the basic steps to get people unfamiliar with this area started.
Anybody wishing to run the CTF test suite should have access to the source code of Castor. This can be obtained in one of the following ways:
At the moment we are in the middle of replacing the old CTF with a new one. While the old CTF still is our reference for refactorings of Castor does the new CTF contain some tests which could not be added to the old one due to its limitations. On the other hand are not all tests ported to the new CTF yet.
In the next sections we describe how to setup the environment to execute both CTF versions. While both versions of CTF are designed to be executed against every supported database engine, we will describe things with regard to mysql. Having said that there are only scripts for mysql at the new CTF at the moment. At a later step of the CTF refactoring we will add scripts for other databases as well. In addition we intend to allow its execution with an embedded derby database out of the box, but this have not been implemented yet.
For those who might be wondering about the numbering of tests, the numbers of the old tests are just random. The numbers of the new tests are the jira issue numbers.
To execute tests against mysql database you probably need access to a mysql server. To create a database for CTF, you have to execute the following commands on mysql consol.
If the server is not installed on your local maschine (the one you execute the tests on) you have to replace "localhost" with the IP of the maschine the tests get executed on. The script to execute can be found in "cpactf/src/old/ddl/" directory. For mysql it's "mysql.sql". If you like to use a different name for the database or use other user credential you can adjust them at "cpactf/src/old/resources/jdo/mysql.xml".
As we do not include JDBC drivers for every database with Castor you also have to add the driver you like to use to your classpath to execute the tests. The easiest way is to copy the driver to "lib/" directory as all jar's contained therein are added automatically. Another option is to modify "bin/test.sh" or "bin/test.bat" script depended on your operating system.
For mysql we still use "mysql-connector-java-3.1.13-bin", also for mysql server of version 5. This version has proven to be stable. While other versions of mysql connector may also work, some of them have bugs from our experience.
As already explained you will find JDO configurations for every supported database in "cpactf/src/old/resources/jdo". The JDO configurations are named mysql.xml, oracle.xml etc. In the same directory you will also find main mapping file "mapping.xml" that includes all other mappings which are located in the "cpactf/src/old/resources/ctf/jdo/..." directories. There is one more important file for the old tests "cpactf/src/old/resources/tests.xml", it is the main config file which defines which test should be executed against which database engine. As mentioned previously not every test works with every database engine as some missing some features or castor does not support everything of every engine.
From a command line (e.g a shell), please execute the following commands to run the whole test suite against mysql (where <castor-root> points to the directory where you installed the Castor sources:
To execute just one of the many tests of the complete test suite, please change this to:
NOTE: You have to execute "build clean" and "build tests" again if you have changed anything within eclipse (e.g. a configuration file or a class).
Now, let's see how we can run these old CPACTF tests through eclipse.
As some features are not supported by all database engines (e.g. sequence keygenerator) or a test have not been verified against a database, only a subset of the following tests will be executed if you run CTF.
To execute tests against mysql database you probably need access to a mysql server. To create a database for CTF, you have to execute the following commands on mysql consol.
If the server is not installed on your local maschine (the one you execute the tests on) you have to replace "localhost" with the IP of the maschine the tests get executed on. For mysql execute every "mysql.sql" script found in subdirectories of "cpactf/src/test/ddl/" directory. If you like to use a different name for the database or use other user credential you can adjust them at "cpactf/src/test/resources/cpactf-conf.xml".
As we do not include JDBC drivers for every database with Castor you also have to add the driver you like to use to your classpath to execute the tests. The easiest way is to copy the driver to "lib/" directory as all jar's contained therein are added automatically. Another option is to modify "bin/test.sh" or "bin/test.bat" script depended on your operating system.
For mysql we still use "mysql-connector-java-3.1.13-bin", also for mysql server of version 5. This version has proven to be stable. While other versions of mysql connector may also work, some of them have bugs from our experience.
Execution of the new test suite from within eclipse against mysql is very simple.
In in the configuration file "cpactf-conf.xml" mysql is configuerd as default database. To execute tests against another database engine or to force execution of tests that have been excluded you can pass VM parameter to the test framework. VM Arguments can also be specified in eclipse.
The following VM parameters are supported by CTF.
For those who face the following problem in eclipse while executing the tests
It is a problem with memory configured for eclipse. It can be changed in eclipse.ini file which can be found in installation directory of Eclipse. By default it is -Xmx256m, just increase it and problem go away.
Anyone who wants to persist object that refer to a typesafe enumeration.
This document addresses the basics and shows an example how to map an object that has a typesafe enumeration property.
Enumerations are a common method for ensuring data integrity, both in software and in relational databases. As a platform for linking the two, we added support for persisting class fields whose type is a Java typesafe enumeration to Castor JDO.
To use this new feature your typesafe enumeration should follow the enum pattern commonly used and provide a static valueOf(String) method. An enum of different kinds of computer equipment may look like:
At your Product class you may want to have a property that tells you what kind of computer equipment a product is of.
Your mapping for the Product class should be:
J2EE applications depend on the J2EE container (hosting Servlet, EJB, etc) to configure a database connection (as well as other resource managers) and use JNDI to look it up. This model allows the application deployer to configure the database properties from a central place, and gives the J2EE container the ability to manage distributed transactions across multiple data sources.
This HOW-TO shows how to seamlessly use Castor JDO in such a managed environment, and how to make Castor participate in a distributed transaction.
Anyone who wants to use Castor JDO with(in) distributed J2EE transactions.
The following sections highlight the steps necessary to use Castor JDO seamlessly in such a (managed) environment, and how to make Castor participate in a distributed transaction.
The following code fragment shows how to use JNDI to lookup a database and how to use a JTA UserTransaction instance to manage the J2EE (aka distributed) transaction:
If the transaction is managed by the container, a common case with EJB beans and in particular entity beans, there is no need to begin/commit the transaction explicitly. Instead the application server takes care of enlisting the database used by Castor JDO to insert domain entities into a database in the ongoing transaction and commiting/rolling back at the relevant time.
The following code snippet relies on the container to manage the transaction.
As transaction enregistration is dealt with at the J2EE container, it is not necessary anymore to obtain a UserTransaction and start/commit the transaction manually.
Instead of constructing required resources directly, a typical J2EE
application uses the JNDI API to look up resources from centrally managed
place such as a naming and directory service. In such an environment,
Castor JDO takes on the role of a managed resource as well. It follows
that, instead of constructing a
We thus recommend enlisting the JDOManager object under the java:comp/env/jdo namespace, compatible with the convention for listing JDBC resources.
At the time of this writing Castor JDO has 3 kinds of test suites:
This document provides general information about running Castor JDO's performance tests.
To execute performance tests against mysql database you probably need access to a mysql server. To create a database for PTF, you have to execute the following commands on mysql consol.
If the server is not installed on your local maschine (the one you execute the tests on) you have to replace "localhost" with the IP of the maschine the tests get executed on. The script to execute is "cpaptf/src/test/ddl/mysql.sql".
As we do not include JDBC drivers for every database with Castor you also have to add the driver you like to use to your classpath to execute the tests. The easiest way is to copy the driver to "lib/" directory as all jar's contained therein are added automatically.
For mysql we still use "mysql-connector-java-3.1.13-bin", also for mysql server of version 5. This version has proven to be stable. While other versions of mysql connector may also work, some of them have bugs from our experience.
Execution of the performance test suite from within eclipse is very simple.
By defeult the test uses 2000 service objects that get created, loaded with various configurations and deleted afterwords. Obviously this will take quite some time. Please be patient for normal termination of the tests as you will need to clean test tables by hand otherwise. To execute tests with a different number of objects you can adjust "FACTOR" constant in "TestCreate.java". For example, if you set "Factor" to 1.0 the tests will be executed with 10000 service objects. When using more test objects be aware that you may need to increase heap size of the virtual maschine for the test to finish.
By default you won't see any output of results on the consol as logging level of log4j is set to "warn" by default. But if you change log level of "org.castor.cpaptf" package to "info" you will see detailed execution times for every test on the consol. Be aware that there are quite some log4j.xml configurations in the whole Castor project at the moment of which the one first one on classpath will be used.
If you like to review some older test results you will find them under "cpaptf/src/site/resources/results/" but they depend heavy on the machine you are running the tests on.
When working with long transactions, you can cascade the db.update() operation, so that, for example, updating the root of a large object graph causes all connected entites to update as well (provided cascading update is enabled on the particular relationships, of course).
To enable cascading update on a relationship you simply set the cascading attribute of the <sql> field describing the relation to "update" (or "all"):
In case of bidirectional relationships, be aware that it matters on which end you enable cascading update. It is also possible to enable it on both ends.
Let's say we have the objects Author and Book and they are in a one-to-one relationship, with every Book having exactly one Author. The database looks like this:
| Author | ||||
|---|---|---|---|---|
|
| Book | ||||||
|---|---|---|---|---|---|---|
|
Now let's change the book's title. Note that we never directly load the book and that the change happens outside of any transaction:
Afterwards, the database looks like this:
| Author | ||||
|---|---|---|---|---|
|
| Book | ||||||
|---|---|---|---|---|---|---|
|
To-many relationships are currently not supported (except many-to-one).
As it is now, enabling cascading update will cause db.update() to also create any entities that have not yet been persisted. (In other words: setting cascading to "update" has the same effect as setting it to "update create", but only when invoking db.update().)
In the context of a relational data-binding tool such as Castor JDO, caches enhance application performance by reducing the number of read operations against the persistence storage, by storing and reusing the last read or committed values of the object.
Castor provides a set of pre-built cache providers, offering a variety of different cache algorithms. Nevertheless, special needs might require the application developer to implement a custom cache algorithm.
Castor facilitates such need by making available a standardized process of how to integrate a custom cache provider.
Anyone who wants to develop his own custom cache provider and integrate it with Castor JDO.
The main component of Castor's cache system is the interface
Below are defined the steps to build a custom cache provider and register it with Castor JDO.
Castor (as of release 0.9.6) allows for addition of user-defined cache provider implementations.
By default, performance caches are registered with Castor JDO through it's main configuratoin file castor.properties. This file includes a section as follows:
To add your own performance cache provider, please append the fully-qualified class name to this list as shown here:
You will have to provide implementations of the interfaces
For this, please add an implementation
of
To assist users in this task, a
Please create an implementation of
To assist users in this task, a
Anyone who wants to execute an OQL statement and limit the result size.
The example given describes the addition of LIMIT/OFFEST clauses to an existing OQL statement.
You should have a valid class mapping for two Java classes Product and ProductGroup, similar to the following one:
The following fragment shows the Java class declaration for the ProductGroup class:
Here is how to proceed.
The following code fragment shows an OQL query to select the all ProductGroup instances.
The following code fragment shows the same OQL query as above, to this time the LIMIT keyword is added to select the first 10 ProductGroup instances only.
Below is the same OQL query again, restricting the number of ProductGroup instances returned to 10, though this time it is specified that the ProductGroup instances 101 to 110 should be returned.
The following RDBMS fully/partially support LIMIT/OFFSET clauses.
|
1) Caster has full support for LIMIT/OFFSET clauses for Oracle Releases 8.1.6 and later.
2) For the LIMIT/OFFSET clauses to work properly the OQL query is required to include an ORDER BY clause.
Are you just interested in how Castor source looks like, want to report a bug or enhancement request or like to contribute to the project? The first step we suggest you to do is to setup a Castor project with eclipse IDE. As we use eclipse to work at Castor, there is everything in place to work with eclipse. While you are free to use other IDE's, you will need to configure things yourself with them.
If you have trouble with Subclipse behind a proxy server: In Windows development environment, open the file: C:\Documents and Settings\MyUserId\Application Data\Subversion\servers in text editor. Near the bottom of that file is a [global] section with http-proxy-host and http-proxy-port (user and password also) settings. Uncommented those lines, modified them for your proxy server and go back to the SVN Repository view in Eclipse. This should solve the problem.
A "patch" is the set of differences between two versions of the same file. Patches are used to send someone the exact changes that you have made to your version of a program or a document. They can then apply that patch to their version to merge the changes and bring their version up-to-date with your version.
As our example we use the contribution of a simple documentation patch for the Castor project. The principles apply to any project and to any type of file, e.g. *.xml, *.java, *.xsd, etc.
Anyone who wants to contribute to a project. This document addresses the basics, so as to get new people started.
Our example describes the use of command-line tools for a UNIX system. Other tools can be used, as long as they produce a "unified diff".
Contributers should have:
Here is how to proceed.
A "Patch" is the set of differences between two versions of the same file. A patch comprises one or more "diff" files. These diffs are produced by the program of the same name: diff.
Here is an example of a single diff for one of the Castor How-to pages, where we are suggesting a minor text change. Do not get frightened. These are just human-readable instructions to the "patch" program.
That is a "unified diff" ... there a some lines of context on each side of the changes. This patch is basically saying "Change the text on line 208".
Let us now go though the process of preparing that patch. Go ahead and edit your local copy of the document at $CASTOR_HOME/src/doc/jdo-howto.xml.
Ensure that it is valid XML using your favourite XML editor or an external validating parser. Please do not leave it up to the poor committer to fix broken XML.
Run the 'build doc' target to be sure that links are not broken and that the new document is presented as you intend it to be.
If you are using the HEAD of SVN then ensure that your working copy is up-to-date. Of course, if you are using a previous public release version of Castor, then it is already up-to-date.
Prepare the diff file. SVN will contact the remote repository, ensure that your working copy is up-to-date, then compare your local copy with the master repository.
Prepare a brief explanation of what your patch does. Get this ready in a text file before you go to Jira. See further hints about this in the "Description" section of the How-to Jira.
What revision of SVN did you patch against? Was it HEAD branch? Was it a nightly build? Was it a public release?
To contribute your patch to a specific project, use Jira - The Codehaus Issue Database. The procedure is explained in How to Contribute a Patch via Jira.
A patchfile can contain the differences to various individual documents. For example, the following command does that ...
However, be careful not to go overboard with this technique. When producing multiple diffs in one patchfile, try to limit it to one particular topic, i.e when fixing the same broken external link in various pages, then it would be fine to produce a single diff. Consider the committer - they will find it hard to apply your patch if it also attempts to fix other things.
Ideally you will prepare your patches against a SVN repository. There are other ways to do this. They do create more work for the committers, however it may be the only way that you can do it. We would certainly rather receive your patch however it comes. As a matter of fact, we would politely ask you first to send us a unified patch.
You could get the source document via the web interface to SVN. Here are the steps ...
With release 0.9.9, several cache providers have been added that are distributed caches per se or can be configured to operate in such a mode. This effectively allows Castor JDO to be used in a clustered J2EE (multi-JVM) environment, where Castor JDO runs on each of the cluster instances, and where cache state is automatically snychronized between these instances.
In such an environment, Castor JDO will make use of the underlying cache provider to replicate/distribute the content of a specific cache between the various JDOManager instances. Through the distribution mechanism of the cache provider, a client of a Castor JDO instance on one JVM will see any updates made to domain objects performed against any other JVM/JDO instance.
Anyone who wants to use Castor JDO in a J2EE cluster.
The example given describes the use of the Coherence cache provider to enable distributed caching.
You should have a valid class mapping for a Java class, similar to the following one:
Here is how to proceed.
Add a <cache-type> element as shown below, specifying the cache provider to use in the 'type' attribute.
This instructs Castor JDO to use the 'coherence' cache provider for objects of type com.xyz.MyOtherObject. It is the cache provider that is responsible to distribute any changes to the cache state to all other Castor JDO instances within the same cluster.
Add the Coherence JARs to the class path of your e.g. web application by putting the JARs into the WEB-INF/lib folder of your web application.
Castor JDO uses the Jakarta Common's Logging package for output information relevant to the execution of a specific JDO operations to a log file. The information output historically included the SQL statements used by Castor to execute the various persistence operations such as loading or updating domain entities. Unfortunately, the SQL statements logged did not include any information about the parameters being bound to the prepared statements immediately before execution, and hence made it very hard for users of Castor JDO to analyze these in teh case of an issue/problem
To improve this situation, proxy classes for the java.sql.Connection and java.sql.PreparedStatement interfaces have been added, to allow for complete and better JDBC statements to be output to the log files. As this might impose a performance penalty at run-time, we have allowed for this to be turned off completely through the standard Castor property file.
A new property has been added to the Castor property file (castor.properties) to allow configuration of this feature.
Anyone who wants to use the new JDBC proxy classes with Castor JDO selectively, i.e. enabling and disabling their use.
The example given describes how to turn the use of the proxy classes on/off.
You should have a valid castor.properties file as part of your application.
Here is how to proceed.
To enable the use of the JDBC proxy classes described above, please add the following section to your castor.properties file.
This instructs Castor JDO to use the JDBC proxy classes and to output full information about the SQL statements used at run-time. When disabled, no logging of SQL statements will occur al all.
At the time of this writing Castor JDO has 3 kinds of test suites:
This document provides general information about running Castor JDO's database independend unit tests.
To execute tests in eclipse, go and right click on "cpa/src/test/java" source folder and select "Run As -> JUnit Test".
Anyone who wants to enable caching for classes already mapped with Castor JDO.
This document addresses the basics to get people familiar with the basic concepts and discusses some implementation details.
The example given describes the addition of a <cache-type> element to an existing class mapping.
You should have a valid class mapping for a Java class, similar to the following one:
Here is how to proceed.
Add a <cache-type> element as shown below, specifying the cache provider to use in the 'type' attribute.
This, for example, defines the 'time-limited' cache provider to be used for the com.xyz.MyOtherObject. This cache provider applies internally a time-limited least-recently-used algorithm for com.xyz.MyObject instances
.Up to Castor 1.3.1, users of Castor JDO have been able to automatically store/update or delete objects across relations by issueing ...
before going starting a transaction. This feature was useful, indeed, but on a second look its limitation (global definition across all entities) became obvious, especially on big projects. You might want to have cascading operations activated selectively (activated for one object, but not for another). Or even more tricky, you might like to automatically track changes across one relation from a starting object, but but not across another relation from the very same object.
As of Castor 1.3.2, a new cascading attribute has been introduced to the <sql> tag of the JDO mapping file.
This and all other cascading documents address people familiar with the basic concepts of mapping domain entities to database tables and defining relations between objects (on database level as well as on object level). But in particular, this document applies to the following user groups:
Everyone who wants to cascade operations across (any type of) object relation(s).
Everyone who now uses Database.setAutoStore(boolean) to have persistence operations cascaded across relations.
Especially the second user group should change their approach towards using cascading operations, and switch to using the new cascading attribute. As of Castor 1.3.2, the current Database.setAutoStore(boolean) methods will be deprecated, and in the long run, this operations will be removed from the JDO interfaces.
You should have a valid mapping file, containing at least two objects, being in relation with each other. For the remainder of this document, we'll be using the following example mapping file as a starting point.
In order to activate cascading for create operations for the author relation defined in the mapping file above, you have to add the following attribute to the field mapping of the author property:
Remember that the code above adding a cascading attribute with a value of create is only an example. You can define any combination of cascading attributes, delimiting those values by spaces, as shown in the following example:
In order to achieve an optimal granulation of activating and de-activating functionality, there are 5 possible values, out of which 3 can be activated separately or in any combination.
In general, what you have to keep in mind is that some cascading types do not only affect the the (coincidentally) identically named database operation, but also other persistence operations. For more details please read the following references carefully.
If no cascading attribute is defined, its default value will be none.
Cascading creation allows you to transfer some of the responsibilities of creating objects to Castor JDO. To be more precise: if you enable cascading creation on a relation between two classes, all objects on one end of that relation that have not yet been created will be created when the other end gets persisted. This saves you from manually creating every single object, which is especially useful when dealing with large object graphs that have 1:M (one to many) relations or many objects in a single relationship.
To enable cascading creation on a relation, you simply set the cascading attribute of the <sql> field describing the relation to "create" (or "all"):
In other words, the field mapping for the Java property book ...
becomes
In case of bidirectional relations, it does matters on which end you enable cascading creation. It is also possible to enable it on both ends.
The most intuitive case is when you explicitly call db.create() on an object that has cascading creation enabled on one or more of his relations. If the objects in those relationships have not yet been created, they will be as part of the create() execution.
Here is a simple example, where the objects Author and Book are in a one-to-one relation (i.e. every Book has exactly one Author):
Once the commit operation has successfully completed, both the Author and the Book instance will have been persisted to your data store. To highlight this, lets's have a look at the corresponding database tables before and after the execution of above code fragment.
Before
| Author | ||||
|---|---|---|---|---|
|
||||
| Book | ||||||
|---|---|---|---|---|---|---|
|
||||||
After
| Author | ||||
|---|---|---|---|---|
|
| Book | ||||||
|---|---|---|---|---|---|---|
|
Cascading creation also works implicitly: any objects that are on the receiving end of a cascaded relation will be created upon transaction commit, provided they do not exist yet and that the object on the primary end of that relation does. In other words: if you modify a relation property of a loaded object, any new objects that now need to be created will be created.
To demonstrate, let's continue the example from the previous section. We, again, have a Book and an Author, in a one-to-one relation, both already persisted. If we now change the book's author to someone new, any object that is not yet in the database will be persisted automatically. Just call db.commit() after setting the new author, and the new author will be persisted as well.
In terms of unit test assertions, the current state of the author and book instances can be expressed as follows:
As above, let's have a look at the corresponding database tables for the entities Author and Book:
Before
| Author | ||||
|---|---|---|---|---|
|
| Book | ||||||
|---|---|---|---|---|---|---|
|
After
| Author | ||||||
|---|---|---|---|---|---|---|
|
| Book | ||||||
|---|---|---|---|---|---|---|
|
Please note that we now have two authors stored, and that the book with an id value of '1' now has a foreign key relationship to the author with the id value '2'.
The real benefit of using cascading for object creation shows when dealing with 1:M relations, usually expressed through Java collections in your entity classes.
For the remainder of this secction, we will use the Java classes Department and Employee, which have a 1:M relationship (in other words, every department has one or more employees). On the Java side, this is expressed as the Department having a collection of Employee objects in form of a Java collection. In the database, this will obviously be the other way around, with the emp table referencing the dept table. Every example in this section will use the same database state as a starting point, as shown here:
| dept | ||||
|---|---|---|---|---|
|
| emp | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
Example 1: Adding objects
After
| dept | ||||
|---|---|---|---|---|
|
| emp | |||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
Example 2: Removing objects
After
| dept | ||||
|---|---|---|---|---|
|
| emp | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
Note: this of course only works if you allow the employee's foreign key dept_id to be NULL or, alternatively, also delete the Employee when you remove the relationship (either by manually calling db.remove() or TODO)
Example 3: Adding & removing objects
Database after:
| dept | ||||
|---|---|---|---|---|
|
| emp | |||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
The note to example 2 also applies here.
Anyone who wants to execute ...
The example given describes ...
You should have ...
Here is how to proceed.
...
...
Most of the traffic on the Castor Users mailing list is about people asking for help on various features of Castor (whether JDO or XML). Whilst there is nothing wrong about asking questions and looking for help if you are stuck, it seems that there is room to improve the structure of this 'conversation'.
If you have a look at some of these threads (e.g. at the searchable mailing list archive), it's quite easy to see that most of the time ...
An initial question is posted.
An initial reply is posted with some follow-up questions, e.g. request for code fragments, mapping files, etc.
One or more code fragments, mapping files, etc. are being posted.
etc.
This document will establish guidelines with regards to step 3) above.
This document provides step-by-step instructions on how to submit a problem report (when being asked to do so). It does so by walking you through a fictive problem and its resulting bug report, and providing instructions based upon this scenario.
Per definition, any problem report submitted (in other words, most likely attached to a bug report at http://jira.codehaus.org/browse/CASTOR) by the means of a patch has to include the following artefacts:
Note: Whilst we can and will not impose these guidelines in their strictest sense, I think that the use of technologies such as JUnit will simplify problem resolution and as a result lead to shorter turn-around times. Which is ultimately where you, the user, gains..
To facilitate creation of a fully featured patch as discussed above, we have provided you with an already existing bug template at 'src/bugs/jdo/template'.
Note:Please note that this directory is distributed only as part of the source archive(s).
This directory holds all artefacts mentioned above, as is structured as follows:
To create you own bug report, please copy 'template' to e.g. bug1820, assuming that 1820 is the number assigned to your BugZilla problem report). Subsequently, please amend the files provided to match your own requirements. After you have consolidated your changes, the original directory structure in src/bugs could look as follows:
Once you have successfully executed your JUnit test case, please add this test to the master test suite available in src/bugs/AllTests.java as follows. To add a test to this suite, please duplicate the line
suite.addTestSuite(template.TestTemplate.class);
and replace the term 'jdo.template.TestTemplate.class' with 'jdo.bug1820.TestCase'.
This will allow us to run all tests related to all open bugs in one go by executing just this test suite.
As explained in cvs.html, we ask you to submit your code changes in the form of a unified patch by attaching it to the relevant bug report.
To create a unified patch for submission, you can either use the command line SVN client (which you find instructions to download for at http://subversion.tigris.org/ or any IDE that offers support or SVN (such as Eclipse with Subclipse plugin)
In any case, please note that we are trying to standardize on the use of unified patches only, and that you should always update your code (against the SVN repository) before creating the patch. If you have never used SVN before, there will be ways to convince us to accept e.g. a Zip file includig your changes.
Whilst we cannot assume that every Castor (JDO) user is an expert in the use of JUnit, we do believe that they are quite easy to get acquainted with. As a starting point, please find below some references:
If you enable cascading deletion on a relationship, deleting the object on one end of the relationship (i.e. calling db.remove() on the object) will also delete the object on the other end.
To enable cascading deletion on a relationship you simply set the cascading attribute of the <sql> field describing the relation to "delete" (or "all"):
In case of bidirectional relationships, be aware that it matters on which end you enable cascading deletion. It is also possible to enable it on both ends.
Let's say we have the objects Author and Book and they are in a one-to-one relationship, with every Book having exactly one Author. The database looks like this:
| Author | ||||
|---|---|---|---|---|
|
| Book | ||||||
|---|---|---|---|---|---|---|
|
Now, since we specified the relationship to cascade deletion, if we remove the book, the author gets removed too (after all, an author without a book isn't really an author).
Afterwards, the database predictably looks like this:
| Author | ||||
|---|---|---|---|---|
|
||||
| Book | ||||||
|---|---|---|---|---|---|---|
|
||||||
Cascading the deletion of objects in to-many relationships works in exactly the same way.
Note: You need to explicitly invoke db.remove() to delete an object. Simply setting a relational property to NULL or removing an item from a collection will not remove the corresponding entity from the database, even with cascading deletion enabled.
Any user who needs to unmarshal/marshal XML that has data represented as text as well as attributes/elements.
Consider you have XML with a structure defined as follows:
Notice the structure the element age, which has both text as well as XML markup as its content. A mapping for above XML would be as follows:
Please note the different node types of the members of the abc.Age class, especially where the Java member ageValue is mapped to a node of type text.
Castor XML has a JUnit test suite that is used to perform various functional and regression tests, to give developers/committers some reassurance when changing the codebase.
Anyone who wants to run the CTF test suite. This document outlines the basic steps to get people unfamiliar with this area started.
Our example describes the use of command-line tools for a UNIX system.
Anybody wishing to run the CTF test suite should have access to the source code of Castor. This can be obtained in one of the following ways:
Note:The CTF currently requires the Sun JDK (or SDK) to execute, although it may be possible to execute fine with GNU gcj or with JRockit. The CTF will not work if you are using only a JRE. This is because the CTF uses the Sun Java compiler API to compile code as needed for Source Generator and Marshaling Framework tests. The CTF code is written to allow easy extension for additional compiler frameworks, so if you use a compiler or runtime that is not supported, you should be able to easily add support for a new framework. If you want to do this, contact Castor committors for assistance and direction and they'll set you on the right course.
Once you have obtained the Castor sources in one of the ways highlighted above, here is how to proceed. In general, more information about how to execute the CTF test suite can be found here.
From a command line (e.g a shell), please execute the following commands to run the Castor XML master test suite (default suite).
To execute just a subset of the master test suite, please change this to:
Anyone who wants to map a collection of elements.
This document helps people to get familiar with the basic concepts of mapping and shows an example.
None.
Assume you have two classes Order and OrderItem, where an order holds a list of order items.
As shown above, the Order instance has a field 'OrderItems' to hold a list of OrderItem instances.
Here's the mapping file to instruct Castor XML about the relation of those two classes, Order and OrderItem respectively:
Using the Castor XML marshaller with the mapping file shown above, the XML generated by Castor XML might look as follows:
How to work with wrapper elements around collections.
This document helps people to get familiar with the basic concepts and shows an example.
None.
When you have a class that holds a collection of objects of the same type, and you want to wrap the XML produced for the collection members with an additional XML artefact, then read on.
For example, assume you have the following Java class Foo:
and you want to have Castor generate XML which looks like:
where the structure of the output is defined by the following XML schema:
then you would use a mapping like where the location attribute on the field mapping for children defines the wrapper XML artifact to be used:
Anyone who wants to write a configurable field hander.
If you want to have a custom FieldHandler that works in a fixed manner, you should consider subclassing GeneralizedFieldHandler , or implementing FieldHandler.
However if you want your FieldHandler to operate more flexibly, based on configuration, ConfigurableFieldHandler may be what you're looking for.
Basically, two approaches exist for implementing a configurable field handler.
The most straightforward one is simply to implement the ConfigurableFieldHandler interface. This interface extends the FieldHandler interface.
The other approach is to subclass any of the convenience FieldHandler implementations. These are AbstractFieldHandler and GeneralizedFieldHandler. Both classes already implement the ConfigurableFieldHandler interface, so you don't have to implement it yourself explicitly. However the implementation of the single ConfigurableFieldHandler method (setConfiguration) is an empty method. So you'd have to override this method yourself in order to do something useful with the configuration.
The two approaches differ only marginally. If the convenience classes provide useful functionality for you, you'd probably be better off using them. Otherwise simply implementing the ConfigurableFieldHandler interface is a good choice.
For this exercise, we choose to implement the ConfigurableFieldHandler, and decide to convert dates, using a configurable date pattern:
For a ConfigurableFieldHandler, we have to override the method setConfiguration of the superclass AbstractFieldHandler. AbstractFieldHandler implements this method on behalf of the ConfigurableFieldHandler interface, but does not do anything.
All we have to do now is define the ConfigurableFieldHandler in the mapping file (using a <field-handler> element), configure it, and use it in some xml field.
This mapping file defines a custom configurable field handler instance named "myHandler", of the type we've just implemented, and configures it with some fancy date pattern. A regular class mapping defines a field called "date", and specifies that conversion to and from this field will be performed by the "myHandler" instance.
It would be perfectly legal to use "myHandler" for other fields as well, and also to define other field-handler instances of the class FieldHandlerImpl (or any other class).
To complete the example, here's the "Root" class that is used in the example mapping file:
And here a sample XML document:
With these classes, xml mapping file and xml sample file, you should be able to marshall and unmarshall the date field.
Anyone who wants to map an inner class with Castor XML for XML data binding.
This document helps people to get familiar with the basic concepts of mapping and shows an example.
A general understanding about XML data binding and its usage.
Assume you have the following classes Outer and Inner:
Please note that the i nner class needs to be declared public and static.
Here's the mapping file for Castor XML, showing the class mapping for the OrderItem class:
Using the Castor XML Unmarshaller with the mapping file shown above, the code to unmarshal the following XML ...
... into a variable of type test.Outer is as follows:
Anyone who wants to map a Map/Hashtable of elements.
This document helps people to get familiar with the basic concepts of mapping and shows an example.
None.
Assume you have two classes Items and Item, where an Items instance holds a Map/Hashtable of Item instances.
As shown above, the Items instance has a field 'itemList' to hold a Map of Item instances.
Here's the mapping file to instruct Castor XML about the relation of those two classes, Items and Item respectively:
Please note the use of the org.exolab.castor.mapping.MapItem definition within the <bind-xml> element in above mapping to map the elements contained in the Map/Hashtable.
Using the Castor XML marshaller with the mapping file shown above, the XML generated by Castor XML might look as follows:
It is equally possible to nest Collections/Arrays within Maps, incl. Maps within Maps. The following Java class has a member 'map' of type java.util.Map.
The following code shows how this Map instance is filled with String arrays before marshalling.
Based upon the following mapping file, ...
the following XML will be generated during marshalling.
Anyone who wants to map a list of elements at the document root.
This document helps people to get familiar with the basic concepts of mapping and shows an example.
None.
Assume you have a java.util.List (java.util.ArrayList) and an OrderItem classes, where the List instance simply holds a list of order items.
Here's the mapping file for Castor XML, showing the class mapping for the OrderItem class:
Using the Castor XML Unmarshaller with the mapping file shown above, the code to unmarshal the XML shown below ...
... into a variable of type java.util.ArrayList is shown subsequently:
Using the Castor XML Marshaller with the mapping file shown above, the code to marshal a List of OrderItem instances to XML is shown below.
Anyone who wants to wrap a collection with a wrapper element.
This document helps people to get familiar with the basic concepts and shows an example.
None.
When you have a field which is a list collection, and you want for each element of the list collection to be encapsulated in a containing element, then set container="false" in the field element for the list collection. By setting this attribute Castor recognizes that you want an element wrapping the members of the list.
By default Castor treats collections as "containers". Containers to Castor are simple objects whose only purpose is to hold other objects. Containers are not considered "first-class" objects and therefore have no direct XML representation. By setting container="false", you are telling Castor that the collection is not be treated as a container, but rather a first class object which should have an XML-representation.
For example, if you have the following two classes:
and you want to have Castor generate XML which looks like:
then you would use a mapping like:
Most of the traffic on the Castor Users mailing list is about people asking for help on various features of Castor (whether JDO or XML). Whilst there is nothing wrong about asking questions and looking for help if you are stuck, it seems that there is room to improve the structure of this 'conversation'.
If you have a look at some of these threads (e.g. at the searchable mailing list archive), it's quite easy to see that most of the time ...
An initial question is posted.
An initial reply is posted with some follow-up questions, e.g. request for code fragments, mapping files, etc.
One or more code fragments, mapping files, etc. are being posted.
etc.
This document will establish guidelines with regards to step 3) above.
This document provides step-by-step instructions on how to submit a problem report (when being asked to do so). It does so by walking you through a fictive problem and its resulting bug report, and providing instructions based upon this scenario.
Per definition, any problem report submitted (in other words, most likely attached to a bug report at http://jira.codehaus.org/browse/CASTOR) by the means of a patch should include one of the following artefacts:
Note: Whilst we can and will not impose these guidelines in their strictest sense, I think that the use of the aforementioned artefacts will simplify problem resolution and as a result lead to shorter turn-around times. Which is ultimately where you, the user, gains.
To facilitate creation of a fully featured patch as discussed above, we have provided you with an already existing bug template at 'src/bugs/xml/template'.
Note:Please note that this directory is distributed only as part of the source archive(s).
This directory holds some of the artefacts mentioned above, and is structured as follows:
To create you own bug report, please copy 'template' to e.g. bug1368, assuming that 1368 is the number assigned to your Jira issue). Subsequently, please amend the files provided to match your own requirements. After you have consolidated your changes, the original directory structure in src/bugs could look as follows:
To facilitate creation of a fully featured but report/patch for the XML code generator, we have provided you with an already existing bug template at 'codegen/src/test/java' and 'codegen/src/test/resources'.
Note:Please note that these directories are distributed only as part of the source archive(s).
These directory holds some of the artefacts mentioned above, and is structured as follows (all paths shown relative to codegen/src/test):
To create you own bug report, please copy 'xml.srcgen.template' in both locations to e.g. xml.bug1368, assuming that 1368 is the number assigned to your Jira issue). Subsequently, please amend the files provided to match your own requirements. After you have consolidated your changes, the original directory structure in codegen/src/test could look as follows:
As a last step, we ask you submit your code changes in the form of a unified patch by attaching it to the relevant Jira issue. Please simply follow the instructions provided here.
Whilst we cannot assume that every Castor (XML) user is an expert in the use of JUnit, we do believe that they are quite easy to get acquainted with. As a starting point, please find below some references:
Anyone who wants to enable XML validation with Castor XML.
This document helps people to get familiar with the basic concepts and discusses some implementation details.
The example given describes the steps required to enble XML validation with Castor XML.
None.
The code given are based on examples from the XML Schema Part 0: Primer Second Edition from w3.org.
The XML Schema instance (po1.xsd) used here looks as follows:
Surprisingly, the schema isn't complete, so the example XML document invalid-po1.xml is actually invalid.
I then corrected the errors (removed the attributes that they didn't bother to define in their schema) and created valid-po1.xml
Now, to bring Castor into the mix, I created two Java classes, PurchaseOrder and Address.
And created a mapping file from the xml to the Java classes.
Note that the mapping file refers to mapping.xsd, which can be found in the Castor JAR file, as the schema for the Castor namespace. I'm also using relative paths for all the schemas, so the xml files and the schemas must all reside in current working directory (the directory from which you call java).
Now for Castor to do validation, the correct castor.properties file must be in the current working directory.
The indent property is just to make the output XML easy to read, and because I'm using Xerces, the apache.org properties come into the mix. Other XML parsers will probably have different flags that need to be set.
Finally, I created a driver class to run Castor:
With Castor, Xerces, and Commons-Logging in the classpath, one can run this ValidationDriver and pass in an xml filename (valid-po1.xml or invalid-po1.xml). The invalid file will print out an exception stack trace that is due to a Xerces validation error. The valid xml should produce the roundtrip xml (that's xml->Java->xml), and the comment from the purchase order from the Java object (after it has gone xml->Java->xml->Java). Note that the xml is being validated against the schema each time it is going from xml->Java (though with this example there is no validation going from Java->xml). The extra round trips might seem excesive, but they helped me work out some kinks in my mapping file when I had to do this the first time.
Anyone who does not want to expose their collection fields.
Enumerations or iterators can be used to list all elements of a container without providing means of modifications (well, Iterators provide a remove method, but its up to the implementation if this method really does anything). Castor can use enumerations or iterators instead of a getter method to marshal a collection.
By using add methods collections can also be unmarshalled without a setter method.
Consider the following container object:
To provide better data encapsulation, only the addString() and iterateStrings() methods are made available publically, and as a result, the collection strings is not exposed via getters or setters.
The mapping file for above ObjectWithCollection - with the intention to instruct Castor to use the method iterateString() - looks as follows:
Please note that for this mechanism to work, the method returning an java.util.Iterator for your collection member has to start with the prefix iterate.
The same mechanism works for methods returning java.util.Enumeration as well. In this case, the method prefix needs to be enum, and the method specified needss to return java.util.Enumeration.
Anyone who is using Castor XML for marshalling, and wants to implement a custom XML Serializer specific to the parser used.
This document addresses the basics to get people familiar with the main concepts and discusses some implementation details.
The example given implements the XML Serializer interface specific to WebLogic's XML parser (which happens to be an extension to Apache Xerces).
You should have downloaded the Castor sources and expanded them into a custom folder of yours.
Here is how to proceed.
To implement your custom XML serialization mechanism, you'll have to provide implementations of the following interfaces:
A possible implementation for Weblogic's (enhanced) Xerces implementation could look as follows.
In order to be able to use these custom implementations, you will have to provide a new
custom
The former can be achieved by providing a new implementation of the
The latter can be achieved by pointing the org.exolab.castor.xml.serializer.factory property of the castor.properties to your new custom XMLSerializerFactory implementation as shown below:
Anyone who wants to map raw XML segments into data types.
None.
Lets say you have an XML structure:
And you want to save off portions of this XML in your objects, instead of having Castor map them immediately.
There are two approaches that can be used for this. The first, approach would be to use the AnyNode type. The benefits of this approach is that you do not have to do anything special to get the data in the mapping file, and can both unmarshal and marshal the xml data. The drawback is that you have to call toString() on the object to get the XML.
The second approach is to use a custom FieldHandler implementation to convert the values. The benefit of this approach is that you are able to convert into any type you want. The drawback is that there is currently no way to marshal the xml data back into XML. It ends up as XML encoded data inside the marshalled XML.
Here is an example mapping file that includes both examples.
The anyType field is set to java.lang.Object. Behind the scenes it is actually an AnyType object.
Also, notice that the stringXML field is of type java.lang.Object. This is because Castor looks at that first to determine what type of parsing needs to be done, then passes it on to the Field Handler, which converts it into whatever is desired.
Here is an example Field Handler that converts the input into a string.
Anyone who want’s to marshal Hibernate POJOs. This document shows how prevent undesirable XML output caused by Hibernate's lazy-loading technique.
A general understanding about the Hibernate persistence framework, its use of dynamic proxies for lazy-loading and Castor XML.
Assume that we have a Hibernate POJO named Person, which stores basic information about persons and set of Address objects. Address itself is another Hibernate POJO. This set of address objects is mapped in the Hibernate mapping file to load lazily, as shown below in the Hibernate mapping for the Person object:
When we want to marshal a Person object to XML, we use a standard Castor XML mapping file to map the Person class to the desired XML layout.
As shown below, marshalling the Person instance produces undesirable XML output. This is because hibernate (or other ORM frameworks) use dynamic proxy classes for lazy-loading.
As Hibernate returns dynamic proxies for lazy-loaded objects, Castor won't be able to find a mapping for these (proxy) classes, and in this case fall back to using introspection. To avoid this behaviour, Castor XML during marshalling must be (en)able(d) to detect such proxy classes and handle them in a special way.
As proxy objects usually implement proxy interfaces, Castor XML can be instructed to check for such interfaces at marshal time, and marshal classes that implement these interfaces in a different way. Castor XML, in its castor.properties configuration file, allows you to enlist (proxy) interfaces that should be used for checking. The property org.exolab.castor.xml.proxyInterfaces can be used to specify whether or not to search for interfaces. If the property is set, the objects to be marshalled will be analysed if they implement one of the given interface names. If that's the case, the superclass will be marshalled instead of the proxy class itself.
Setting this property as hown above now enables Castor XML to produce the desired output.
Anyone who wants to use Castor XML for XML data binding, namely marshalling operations, and produce XML document instances that carry a the version 1.1 in the XML preamble.
Before release 1.3.2, Castor was able to produce XML documents upon marshalling that had the following XML preamble (if not omitted on purpose) only:
With the release of the XML document standard version 1.1, it was necessary to add an option to have the following preamble generated:
To make Castor output version 1.1 in the XML preamble as produced upon marshalling an object instance to XML, the org.exolab.castor.xml.version property has to be overriden in a custom, user-specific castor.properties> file.
Alternatively, you can set the property directly on the XMLContext instance using ...
before creating Marshaller instances from the XMLContext instance using XMLContext.createMarshaller().
Anyone who wants to use a binding file with the Castor XML source generator. This document discusses various main concepts in the context of a non-trivial real word example, and intends to help people to get familiar with the basic concepts and discusses some implementation details.
The example given describes the steps required to build a binding file that helps users to overcome typical problems related to the use of more complex XML Schemas.
Two companies wish to trade with each other using a Supply Chain messaging system. This system sends and receives Purchase Orders and Order Receipt messages. After many months of discussion they have finally decided upon the structure of the Version 1.0 of their message XSD and both are presently developing solutions for it. One of the companies decides to use Java and Castor XML supprt for (un)marshalling and Castor's code generator to accelerate their development process.
If you run the Castor CodeGenerator on the above XSD you end up with the following set of classes. [You also get lots of warning messages with the present 0.99 version.]
The problem here is that there are two different elements with the same name in different locations in the XSD. This causes a java code generation conflict. Castor uses the element name as the name of the class. So the second class generated for the LineItem definition, which is different than the first, overwrites the first class generated.
A binding file is therefore necessary to help the Castor code generator differentiate between these generated classes. [i.e. You can 'bind' an element in the XSD to a differently named class file that you want to generate. Thus keeping different elements seperate]
The warning messages for Castor 0.99+ are very usefull in assisting you
in your creation of the binding file. For the example the warning messages for the example are;
Warning: A class name generation conflict has occured between element '/Data/OrderReceipt/LineItem' and element '/Data/PurchaseOrder/LineItem'. Please use a Binding file to solve this problem.Continue anyway [not recommended] (y|n|?)y
Warning: A class name generation conflict has occured between element '/Data/OrderReceipt/LineItem' and element '/Data/PurchaseOrder/LineItem'. Please use a Binding file to solve this problem.Continue anyway [not recommended] (y|n|?)y
Warning: A class name generation conflict has occured between element '/Data/OrderReceipt/LineItem' and element '/Data/PurchaseOrder/LineItem'. Please use a Binding file to solve this problem.Continue anyway [not recommended] (y|n|?)y
Warning: A class name generation conflict has occured between element 'complexType:ReceiptLineItemType/Sku' and element 'complexType:LineItemType/Sku'. Please use a Binding file to solve this problem.Continue anyway [not recommended] (y|n|?)y
Warning: A class name generation conflict has occured between element 'complexType:ReceiptLineItemType/Sku' and element 'complexType:LineItemType/Sku'. Please use a Binding file to solve this problem.Continue anyway [not recommended] (y|n|?)y
Warning: A class name generation conflict has occured between element 'complexType:ReceiptLineItemType/Sku' and element 'complexType:LineItemType/Sku'. Please use a Binding file to solve this problem.Continue anyway [not recommended] (y|n|?)y
The following binding file definition will overcome the naming issues for the generated classes.
Things to notice in the above binding.xml file are that the name path used is relative to the root of the XSD NOT the root of the target XML. Also notice that the two complex types have the "complexType:" prefix to identify them, and then the name path relative to the root of the XSD.
The new list of generated classes is:
The developers can now use these generated classes with Castor to (un)marshal the supply chain messages sent by their business partner.
Anyone who wants to use Castor XML for XML data binding, namely marshalling and unmarshalling operations.
You should have downloaded the Castor binaries or included Castor as a dependency in a Maven project.
For the purpose of showcasing the use of the XMLContext class, let's assume we have a simple Person class as follows:
Starting with Castor 1.1.2, the
Below is a code sample that shows how to use the XMLContext class for
umarshalling a Person instance using an
As shown above, the
When you need more than one
Anyone who wants to model non-hierarchical object relations in XML using Castor.
This document helps people to get familiar with the basic concepts and discusses some implementation details.
None.
As a motivating example for this HOW-To, consider a graph consisting of nodes and branches. For this example we're going to take a node-centric view of the graph, so each node is a Java object that contains a list of other nodes it is connected to (thus modeling the branches). The node class might look like:
The default marshalling behavior in Castor is to create a new element for each object contained by the object being marshalled. For a lot of applications this is acceptable as the Java object model being marshalled is hierarchical. The same goes for unmarshalling but in the opposite direction; i.e. a new object is created for each element in the XML.
Now consider the graph example above. If that model is marshalled or unmarshalled with the default behavior, all the relations between the nodes will be broken. Even using a mapping file like the one below won't help.
After unmarshalling each Node object will contain a list of siblings, but those siblings will be specific to that Node. They may be populated with the right data (nodeNum etc.) to begin with, but any changes won't propogate to the other nodes.
Enter identities and references -- using a mapping file, it is possible to tell Castor how to identify specific instances of a class and when to simply reference an object rather than create a new one. In the example above, assume nodeNum is unique across all nodes and thus can be used to identify each node individually. Once an identity is defined it is possible to instruct Castor to only reference instances of the class rather than creating new objects.
For the graph example above, the correct mapping file would look like this:
The key attributes in the mapping file are identity in the class element, and reference in the bind-xml element. When reference is set to true, Castor knows to create only a reference to the object rather than a full object. This accomplishes two things: first, it reduces the size of the XML file created during marshalling because each object is completely written out only once, and two, on unmarshal, the objects will maintain the correct relations to each other.
Marshalling an ArrayList of these Node objects then looks like:
Anyone who wants to map a class in Castor XML and wants to map fields as constructor arguments.
This document helps people to get familiar with the basic/advanced concepts of mapping and shows an example.
None.
Assume you have a class Foo, as shown below
As shown above, the Foo class has - in addition to the default constructor, which is required by Castor XML - a second constructor that allows you to specify a custom size at object initialization.
Here's the mapping file to instruct Castor XML about the existence of Foo respectively:
The setMethod="%1" fragment above tells Castor to use the size attribute as a constructor argument when calling Foo(int) during instantiation.
Anyone who wants to retrieve DTDs and/or schemas from a local JAR file rather than the network.
This document helps people to get familiar with the basic concepts and discusses some implementation details.
None. All the required files reside in the Castor JAR, but what version of Castor you have will determine the public/system IDs are recognized by the DTDResolver.
XML files often reference other files. The most common dependencies are either document type definitions (DTDs) from the DOCTYPE declaration or XML Schemas from the schemaLocation attribute.
Parsers usually only request schemas for validation, but more parsers are now requesting the DTDs whether validation is on or off. This allows the parser to resolve any entity references (i.e. & or <) that might be used in the document and defined in the DTD. This behavior can cause problems for machines with limited network connectivity, and in certain situations it is simply undesirable to have the parser going to the internet for each dependency.
The org.xml.sax.EntityResolver interface is the key to retrieving XML dependencies from locations other than the defined system location. The interface has one method:
During parsing, before it attempts to retrieve any external files, the parser will call the above method, giving the public and/or system ID for the file. The implementing object can then either return an InputSource through which the parser can access the file, or null if the parser should fetch the file via normal channels.
In Castor, the org.exolab.castor.util.DTDResolver class provides an implementation of EntityResolver that is designed to fetch all the Castor dependencies from the Castor JAR file. This includes:
Castor automatically uses a DTDResolver when loading a mapping file, but must be told to use one during unmarshalling:
The DTDResolver can also wrap another EntityResolver to allow resolver chaining. DTDResolver calls the nested EntityResolver before attempting to resolve the ID(s) itself.
For the DTDResolver to retrieve the desired file from the Castor JAR, either the public ID or the system ID must match exactly. Below are lists of public and system IDs for the versions of Castor, but when in doubt, check the code of DTDResolver.
Since Castor v0.9.9.1 the following IDs are preferred:
For older distributions, the following IDs have been accepted since Castor v0.9.5:
For details about the features added and the bugs fixed, please have a look at the release notes at http://castor.codehaus.org/release-notes.html
]]>As always, we encourage the users of Castor to contribute additional examples, tips, errata or how-tos to the project. The contributions collected at this place will be migrated into the standard HTML documentation.
]]>For details about the features added and the bugs fixed, please have a look at the release notes at http://castor.codehaus.org/release-notes.html
]]>This is a first release candidate for the upcoming 1.3 release. For details about the features added and the bugs fixed, please have a look at the release notes at http://castor.codehaus.org/release-notes.html.
]]>More info about the site, its features and its inner workings is in the FAQ at http://markmail.org/docs/faq.xqy.
]]>For details about the features added and the bugs fixed, please have a look at the release notes at http://castor.codehaus.org/release-notes.html
]]>For details about the features added and the bugs fixed, please have a look at the release notes at http://castor.codehaus.org/release-notes.html
]]>For details about the features added and the bugs fixed, please have a look at the release notes at http://castor.codehaus.org/release-notes.html
]]>For details about the features added and the bugs fixed, please have a look at the release notes at http://castor.codehaus.org/release-notes.html
]]>For details about the features added and the bugs fixed, please have a look at the release notes at http://castor.codehaus.org/release-notes.html
]]>This is a second milestone build for the upcoming 1.1 release.
For details about the features added and the bugs fixed, please have a look at the release notes at http://castor.codehaus.org/release-notes.html
]]>This is a second milestone build for the upcoming 1.1 release. As part of this release, there are a few noteworthy changes:
For details about the features added and the bugs fixed, please have a look at the release notes at http://castor.codehaus.org/release-notes.html
]]>This is a milestone build for the upcoming 1.1 release. For details about the features added and the bugs fixed, please have a look at the release notes at http://castor.codehaus.org/release-notes.html.
]]>For details about the features added and the bugs fixed, please have a look at the release notes at http://castor.codehaus.org/release-notes.html.
]]>For details about the features added and the bugs fixed, please have a look at the release notes at http://castor.codehaus.org/release-notes.html.
]]>For details about the features added and the bugs fixed, please have a look at the release notes at http://castor.codehaus.org/release-notes.html.
]]>For details about the features added and the bugs fixed, please have a look at the release notes at http://castor.codehaus.org/release-notes.html.
]]>For details about the functionality provided, please have a look at the documentation available at http://castor.codehaus.org/castor-spring-site/.
]]>The SVN repository is available at http://svn.codehaus.org/castor/castor-jpa/trunk
]]>For details about the features added and the bugs fixed, please have a look at the release notes at http://castor.codehaus.org/release-notes.html.
]]>It looks like during some Jira upgrade a few months ago, a couple of Jira settings got disabled. As a result, the original reporter of a Jira issue did not get notified about any changes to the issue (incl. e.g. state changes, comments, questions, etc.)...
]]>At http://docs.codehaus.org/display/CASTOR/CastorSocProjects, you'll find some suggestions we find suitable for the program, and per definition we would be glad to support a few projects.
Please understand, though, that mentoring capacities will be limited, though we will try to dedicate as much time as possible to the suggested projects. That implies that we depend on your dedication during the preparation of the detailed specification and description of the outcome.
The timeframe for applications is May 1 - May 8. So have a look at the projects offered before you sign up to the program and apply as a student to be mentored by us.
]]>For details about SVN access please have a look at: http://castor.codehaus.org/cvs.html.
]]>For details about the features added and the bugs fixed, please have a look at the release notes at http://castor.codehaus.org/release-notes.html.
]]>This is the last milestone build for the upcoming 1.0 release. For details about the features added and the bugs fixed, please have a look at the release notes at http://castor.codehaus.org/release-notes.html.
]]>This is a milestone build for the upcoming 1.0 release. For details about the features added and the bugs fixed, please have a look at the release notes at http://castor.codehaus.org/release-notes.html.
]]>This is a milestone build for the upcoming 1.0 release. For details about the features added and the bugs fixed, please have a look at the release notes at http://castor.codehaus.org/release-notes.html.
]]>This is a milestone build for the upcoming 1.0 release, and has no correlation to Christmas at all ... ;-). For details about the features added and the bugs fixed, please have a look at the release notes at http://castor.codehaus.org/release-notes.html.
]]>This is a maintenance release. For details about the features added and the bugs fixed, please have a look at the release notes at http://castor.codehaus.org/release-notes.html.
]]>This is a major feature release. For details about the features added and the bugs fixed, please have a look at the release notes at http://castor.codehaus.org/release-notes.html.
]]>Please use the below links for access to ...
The following sections assume that you have a valid Castor XML mapping for a Java entity named Product as follows:
The sources for this Product entity are as follows:
Before you'll be able to obtain an instance of Marshaller through Spring, you have to add a Spring bean definition to your Spring configuration as follows:
Based upon this configuration, you will be able to obtain a Marshaller instance as follows:
The Marshaller instance obtained in this way does not have any mapping information associated, and will thus use the introspection mechanism to establish a mapping between the Java object and the XML representations.
With the above Marshaller instance, you can set e.g. a java.io.Writer and simply start the marshalling process as shown below:
Before you'll be able to obtain an instance of Unmarshaller through Spring, you have to add a Spring bean definition to your Spring configuration as follows:
Based upon this configuration, you will be able to obtain a Unmarshaller instance as follows:
The Unmarshaller instance obtained in this way does not have any mapping information associated, and will thus use the default introspection mechanism to establish a mapping between the Java object and the XML representations.
With the above Unmarshaller instance, you can unmarshal the following XML document instance as shown subsequently:
To specify that the Castor (Un)Marshaller instances should use a custom mapping file (in addition to the default introspection mechanism), please amend above bean definition for the 'resolver' bean as follows:
Reference:
Release 0.9.6:
The Castor OQL implementation is currently in phase 3 of development.
NOTE: This documentation is not yet finished
This document describes an OQL to SQL translator to be added to the
Castor JDO Java object Persistence API. The translator will accept OQL
queries passed as strings, and generate a parse tree of the OQL. It will
then traverse the tree creating the appropriate SQL. The user will then
be able to bind parameters to parameterized queries. Type checking will
be performed on the bound parameters. When the user executes the query,
the system will submit the query to the SQL database, and then
postprocess the SQL resultset to create the appropriate result as a Java
Object or literal. The current
Four of the (now defunct) SourceXchange milestones for this project call for java source code. These milestones will be referred to here as phase 1, 2, 3, and 4. There are many possible OQL features that can be supported, but weren't discussed in the proposal or RFP. Many of these are probably unwanted. These additional features are specified as phase 5, which is out of the scope of this SourceXChange project.
The parser will construct a parse tree as output from an OQL query string given as input. The OQL syntax is a subset of the syntax described in the ODMG 3.0 specification section 4.12, with some additional constructs. Following is a description of the supported OQL syntax, and its SQL equivalent.
Certain features of OQL may not be directly translatable to SQL, but may still be supported, by post processing the query. For example, the first() and last() collection functions supported in OQL are not directly translatable to standard SQL, but a resultset can be post-processed to return the appropriate values. Features requiring post-processing of SQL resultsets will be documented as such below.
Currently the OQLQuery checks for correct syntax at the same time as it does type checking and other types of error checking. The new code will involve a multiple pass strategy, with the following passes:
This section describes the first pass which will be done by the parser. The parser will create a StringTokenizer like this:
=:|$", true);]]>This will create a StringTokenizer with the delimiter characters listed in the second argument, and it will return delimeters as well as tokens. The parser will also create a Vector to be used as a token buffer. As tokens are returned from the StringTokenizer they will be added to the Vector. Older tokens will be removed from the Vector when it reaches a certain size. The Vector will also be modified when the StringTokenizer returns multi character operators as seperate tokens, for example the -> method invocation operator.
The parser will consume tokens from the StringTokenizer, generating a ParseTree. Each ParseTree node will have a nodeType corresponding to its symbol in the OQL syntax. After each node is created it will look at the next token and act acordingly, either modifying its properties (i.e. for DISTINCT property of selectExpr), creating a new child node or returning an error. If the error travels up to the root node of the ParseTree, there is a syntax error in the OQL submitted. At the end of this pass, the ParseTree will contain an apropriate representation of the query, which will be analyzed, and used to create SQL. Below is the modified EBNF which will be the Castor OQL syntax.
query ::= selectExpr
| expr
selectExpr ::= select [distinct]
projectionAttributes
fromClause
[whereClause]
[groupClause]
[orderClause]
[limitClause [offsetClause]]
projectionAttributes ::= projectionList
| *
projectionList ::= projection {, projection }
projection ::= field
| expr [as identifier]
fromClause ::= from iteratorDef {, iteratorDef}
iteratorDef ::= identifier [ [as ] identifier ]
| identifier in identifier
whereClause ::= where expr
groupClause ::= group by fieldList {havingClause}
havingClause ::= having expr
orderClause ::= order by sortCriteria
limitClause ::= limit queryParam
offsetClause ::= offset queryParam
sortCriteria ::= sortCriterion {, sortCriterion }
sortCriterion ::= expr [ (asc | desc) ]
expr ::= castExpr
castExpr ::= orExpr
| ( type ) castExpr
orExpr ::= andExpr {or andExpr}
andExpr ::= quantifierExpr {and quantifierExpr}
quantifierExpr ::= equalityExpr
| for all inClause : equalityExpr
| exists inClause : equalityExpr
inClause ::= identifier in expr
equalityExpr ::= relationalExpr
{(= | !=)
[compositePredicate] relationalexpr }
| relationalExpr {like relationalExpr}
relationalExpr ::= additiveExpr
{(< | <=
| > | >= )
[ compositePredicate ] additiveExpr }
| additiveExpr between
additiveExpr and additiveExpr
compositePredicate ::= some | any | all
additiveExpr ::= multiplicativeExpr
{+ multiplicativeExpr}
| multiplicativeExpr
{- multiplicativeExpr}
| multiplicativeExpr
{union multiplicativeExpr}
| multiplicativeExpr
{except multiplicativeExpr}
| multiplicativeExpr
{|| multiplicativeExpr}
multiplicativeExpr ::= inExpr {* inExpr}
| inExpr {/ inExpr}
| inExpr {mod inExpr}
| inExpr {intersect inExpr}
inExpr ::= unaryExpr {in unaryExpr}
unaryExpr ::= + unaryExpr
| - unaryExpr
| abs unaryExpr
| not unaryExpr
| postfixExpr
postfixExpr ::= primaryExpr{[ index ]}
| primaryExpr
{(. | ->)identifier[arglist]}
index ::= expr {, expr}
| expr : expr
argList ::= ([ valueList ])
primaryExpr ::= conversionExpr
| collectionExpr
| aggregateExpr
| undefinedExpr
| collectionConstruction
| identifier[ arglist ]
| queryParam
| literal
| ( query )
conversionExpr ::= listtoset( query )
| element( query )
| distinct( query )
| flatten( query )
collectionExpr ::= first( query )
| last( query )
| unique( query )
| exists( query )
aggregateExpr ::= sum( query )
| min( query )
| max( query )
| avg( query )
| count(( query | * ))
undefinedExpr ::= is_undefined( query )
| is_defined( query )
fieldList ::= field {, field}
field ::= identifier: expr
collectionConstruction ::= array([valueList])
| set([valueList])
| bag([valueList])
| list([valueList])
| list(listRange)
valueList ::= expr {, expr}
listRange ::= expr..expr
queryParam ::= $[(type)]longLiteral
type ::= [unsigned] short
| [unsigned] long
| long long
| float
| double
| char
| string
| boolean
| octet
| enum [identifier.]identifier
| date
| time
| interval
| timestamp
| set <type>
| bag <type>
| list <type>
| array <type>
| dictionary <type, type>
| identifier
identifier ::= letter{letter| digit| _}
literal ::= booleanLiteral
| longLiteral
| doubleLiteral
| charLiteral
| stringLiteral
| dateLiteral
| timeLiteral
| timestampLiteral
| nil
| undefined
booleanLiteral ::= true
| false
longLiteral ::= digit{digit}
doubleLiteral ::= digit{digit}.digit{digit}
[(E | e)[+|-]digit{digit}]
charLiteral ::= 'character'
stringLiteral ::= "{character}"
dateLiteral ::= date
'longliteral-longliteral-longliteral'
timeLiteral ::= time
'longliteral:longLiteral:floatLiteral'
timestampLiteral ::= timestamp
'longLiteral-longLiteral-longLiteral
longliteral:longLiteral:floatLiteral'
floatLiteral ::= digit{digit}.digit{digit}
character ::= letter
| digit
| special-character
letter ::= A|B|...|Z|
a|b|...|z
digit ::= 0|1|...|9
special-character ::= ?|_|*|%|\
The following symbols were removed from the standard OQL Syntax for the following reasons:
The following symbols were added or modified.
The rest of the standard OQL syntax remains unchanged. Certain syntactically correct queries may not be supported in Castor. For example, top level expressions which do not contain a selectExpr anywhere in the query may not be supported. This will be discussed further in the next section.
The first pass over the ParseTree will do type checking, and create some structures used in the SQL generation pass. It will also check whether the identifiers used are valid, and whether the query uses unsupported features. The following table describes each type of node in the ParseTree, and how it will be processed in the first pass.
| expr |
|
Phase 5 |
| projectionAttributes |
|
Phase 5 |
| projectionList |
|
Phase 5 |
| projection |
|
Phase 1 |
| projection |
|
Phase 2 |
| fromClause |
|
Phase 1 |
| whereClause |
|
Phase 1 |
| whereClause |
|
Phase 2 |
| whereClause |
|
Phase 3 |
| whereClause |
|
Phase 4 |
| groupClause, havingClause |
|
Phase 4 |
| orderClause |
|
Phase 3 |
After the first pass, the ParseTree is free of errors, and ready for
the SQL generation step. The existing implementation of the OQLParser
uses the persistence API for SQL generation. This API lacks the
necessary features to generate SQL from any OQL. The SQLEngine class
which implements Persistence is used to create a JDBCQueryExpression.
The SQL is derived from the finder, which is a JDBCQueryExpression
produced by the SQLEngine. The problem is that the SQLEngine only
supports single objects. It cannot generate SQL for path expressions
like this:
select p.address from Person p
This query requires a SQL statement like this:
select address.* from person, address
where person.address_id = address.address_id
The buildFinder method should not be used to generate a queryExpression. The SQLEngine should be used to get a ClassDescriptor, and to create a new QueryExpression. The OQLParser should use the methods in the QueryExpression to generate the SQL. The JDBCQueryExpression which is an implementation of QueryExpression is also lacking in necessary features. This class should continue to be used, but the following features will need to be added:
The following table lists each type of tree node, and how it will be processed in the SQL generation pass.
| selectExpr |
|
Phase 2 |
| projection |
|
Phase 1 |
| projection |
|
Phase 2 |
| whereClause |
|
Phase 1 |
| whereClause |
|
Phase 2 |
| whereClause |
|
Phase 4 |
Please see the OQL section of the JDO FAQ.
The Parser and ParseTree classes will be improved through the phases
of this project. The top level of OQL to SQL translation will look very
simple, like this:
OQLParser parser = new OQLParser(query);
ParseTree pt = parser.getParseTree();
pt.checkPass();
These methods will have some additional parameters passed
for storing and retrieving data relevant to the query. Following is a
table containing a list of what will be introduced in each coding phase
of the project.
| Phase 1 |
|
| Phase 2 |
|
| Phase 3 |
|
| Phase 4 |
|
| Phase 5: |
|
Please find below various examples of OQL queries using the Java class files as outlined below.
The following fragment shows the Java class declaration for the Product class:
package myapp;
public class Product
{
private int _id;
private String _name;
private float _price;
private ProductGroup _group;
public int getId() { ... }
public void setId( int anId ) { ... }
public String getName() { ... }
public void setName( String aName ) { ... }
public float getPrice() { ... }
public void setPrice( float aPrice ) { ... }
public ProductGroup getProductGroup() { ... }
public void setProductGroup( ProductGroup aProductGroup ) { ... }
}
|
The following fragment shows the Java class declaration for the ProductGroup class:
public class ProductGroup
{
private int _id;
private String _name;
public int getId() { ... }
public void setId( int id ) { ... }
public String getName() { ... }
public void setName( String name ) { ... }
}
|
On a selected number of RDBMS, Castor JDO now supports the use of LIMIT/OFFSET clauses.
As per this release, the following RDBMS have full/partial support for this feature.
|
1) Oracle has full support for LIMIT/OFFSET clauses for release 8.1.6 and later.
2) For the LIMIT/OFFSET clauses to work properly the OQL query is required to include a ORDER BY clause.
The following code fragment shows an OQL query that uses the LIMIT keyword to select the first 10 ProductGroup instances.
query = db.getOQLQuery("select p from ProductGroup as p LIMIT $1");
query.bind(10);
|
Below is the same OQL query again, restricting the number of ProductGroup instances returned to 10, though this time it is specified that the ProductGroup instances 11 to 20 should be returned.
query = db.getOQLQuery ("select p from ProductGroup as p LIMIT $1 OFFSET $2");
query.bind(10);
|
In the case a RDBMS does not support LIMIT/OFFSET clauses, a SyntaxNotSupportedException will be thrown.
As of release 0.9.7, any new code artifacts should carry a new, Apache 2.0-style license. This shall include files that have been changed substantially through e.g. refactoring.
Copyright 2004-2005 Werner Guttmann Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
The code of this project is released under a BSD-like license [license.txt]:
Copyright 1999-2004 (C) Intalio Inc., and others. All Rights
Reserved. Redistribution and use of this software and
associated documentation ("Software"), with or without
modification, are permitted provided that the following
conditions are met:
1. Redistributions of source code must
retain copyright statements and notices. Redistributions must
also contain a copy of this document.
2. Redistributions in
binary form must reproduce the above copyright notice, this
list of conditions and the following disclaimer in the
documentation and/or other materials provided with the
distribution.
3. The name "ExoLab" must not be used to endorse
or promote products derived from this Software without prior
written permission of Intalio Inc. For written permission,
please contact info@exolab.org.
4. Products derived from this Software may not be called "Castor" nor may
"Castor" appear in their names without prior written permission
of Intalio Inc. Exolab, Castor and Intalio are trademarks of
Intalio Inc.
5. Due credit should be given to the ExoLab Project
(http://www.exolab.org/).
THIS SOFTWARE IS PROVIDED BY INTALIO AND CONTRIBUTORS ``AS IS'' AND
ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL INTALIO OR
ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
DAMAGE.
The key generator gives a possibility to generate identity field values automatically. During create the value of the identity field is set to the value obtained from the key generator. Different algorithms may be used here, both generic and specific for database server.
The key generator for the given class is set in the mapping
specification file (mapping.xml), in the
key-generator attribute of the class element,
for example:
The following key generator names are supported in Castor 1.0:
| MAX | "MAX( pk ) + 1" generic algorithm |
| HIGH-LOW | HIGH-LOW generic algorithm |
| UUID | UUID generic algorithm |
| IDENTITY | Supports autoincrement identity fields in Sybase ASE/ASA, MS SQL Server, MySQL and Hypersonic SQL |
| SEQUENCE | Supports SEQUENCEs in Oracle, PostgreSQL, Interbase and SAP DB |
Some of these algorithms have parameters, which can be specified
in the key-generator element of the mapping
specification file, for example:
It is possible to create several key generators with the same
algorithms but diffent parameters.
In this case you have to specify the alias attribute
in the key-generator element, for example:
Below all supported key generators a described in details.
MAX key generator fetches the maximum value of the primary key and lock the record having this value until the end of transaction. Then the generated value is set to (MAX + 1). Due to the lock concurrent transactions which perform insert to the same table using the same key generator algorithm will wait until the end of the transaction and then will fetch new MAX value. Thus, duplicate key exception is almost impossible (see below). Note, that it is still possible to perform multiple inserts during the same transaction.
There is one "singular" case of this algorithm: the case when the table is empty. In this case there is nothing to lock, so duplicate key exception is possible. The generated value in this case is 1.
This algorithm has no parameters. Primary key must have type integer, bigint or numeric.
This key generator uses one of the variants of the generic HIGH-LOW algorithm. It is needed a special auxiliary table ("sequence table") which has the unique column which contains table names (of the type char or varchar) and the column which is used to reserve values of the primary keys (of the type integer, bigint or numeric). The key generator seeks for the given table name, reads the last reserved value and increases it by some number N, which is called "grab size". Then the lock on the auxiliary table is released, so that concurrent transactions can perform insert to the same table. The key generator generates the first value from the grabbed interval. During the next (N - 1) invocations it generates the other grabbed values without database access, and then grabs the next portion. Note, that the auxiliary table must be in the same database as the table for which key is generated. So, if you work with multiple databases, you must have one auxiliary table in each database.
If the grab size is set to 1, the key generator each time stores the true maximum value of the primary key to the auxiliary table. In this case the HIGH-LOW key generator is basically equivalent to the MAX key generator. On you want to have LOW part of the key consisting of 3 decimal digits, set the grab size to 1000. If you want to have 2 LOW bytes in the key, set the grab size to 65536. When you increase the grab size, the speed of key generation also increases because the average number of SQL commands that are needed to generate one key is (2 / N). But that average number of key values that will be skipped (N / 2) also increases.
The HIGH-LOW key generator has the following parameters:
| table | The name of the special sequence table. | Mandatory |
| key-column | The name of the column which contains table names | Mandatory |
| value-column | The name of the column which is used to reserve primary key values | Mandatory |
| grab-size | The number of new keys the key generator should grab from the sequence table at a time. | Optional, default="10" |
| same-connection | To use the same Connection for writing to the sequence table, values: "true"/"false". This is needed when working in EJB environment, though less efficient. | Optional, default="false" |
| global | To generate globally unique keys, values: "true"/"false". | Optional, default="false" |
If the parameter "global" is set to "true", the sequence table contains only one row with "]]> instead of the table name. This row serves for all tables.
Don't forget to set same-connection="true" if you are working in EJB environment!
Note, that the class HighLowKeyGenerator is not final, so you can extend it in order to implement other variants of HIGH-LOW algorithm (for example, HIGH/MID/LOW or char key values).
This key generator generates global unique primary keys. The generated key is a combination of the IP address, the current time in milliseconds since 1970 and a static counter. The complete key consists of a 30 character fixed length string.
This algorithm has no parameters. Primary key must have type char, varchar or longvarchar.
IDENTITY key generator can be used only with autoincrement primary key columns (identities) with Sybase ASE/ASA, MS SQL Server, MySQL and Hypersonic SQL. After the insert the key generator selects system variable @@identity which contains the last identity value for the current database connection. In the case of MySQL and Hypersonic SQL the system functions LAST_INSERT_ID() and IDENTITY() are called, respectively.
This algorithm has no parameters.
The SEQUENCE key generator type is supported in conjunction with the following DBMS: Derby, Interbase, Oracle, PostgreSQL, and SAP DB. It generates keys using database sequence objects.
The key generator has the following parameters:
| sequence | The name of the sequence | Optional, default="{0}_seq" |
| returning | RETURNING mode for Oracle8i, values: "true"/"false" | Optional, default="false" |
| increment | Increment for Interbase | Optional, default="1" |
| trigger | Assume that there is a trigger that already generates key. Values: "true"/"false" | Optional, default="false" |
Usually one sequence is used for one table, so in general you have to define one key generator per table. But if you use some naming pattern for sequences, you can use one key generator for all tables. For example, if you always obtain sequence name by adding "_seq" to the name of the correspondent table, you can set "sequence" parameter of the key generator to "{0}_seq" (the default value). In this case the key generator will use sequence "a_seq" for table "a", "b_seq" for table "b", etc. Castor also allows for inserting the primary key into the sequence name as well. This is accomplished by including the {1} tag into the "sequence" parameter. Example: "{0}_{1}_seq"
Actually the SEQUENCE key generator is "4 in 1". With PostgreSQL it performs "SELECT nextval(sequenceName)" before INSERT and produces identity value that is then used in INSERT. Similarly, with Interbase it performs "select gen_id(sequenceName, increment) from rdb$database" before INSERT. With Oracle by default (returning=false) and with SAP DB it transforms the Castor-generated INSERT statement into the form "INSERT INTO tableName (pkName,...) VALUES (sequenceName.nextval,...)" and after INSERT it performs "SELECT seqName.currval FROM tableName" to obtain the identity value. With Oracle8i it is possible to use more efficient RETURNING mode: to the above INSERT statement is appened "RETURNING primKeyName INTO ?" and the identity value is fetched by Castor during INSERT, so that only one SQL query is needed.
In case when your table has an on_Insert trigger which already generates values for your key, like the following Oracle example:
create or replace trigger "trigger_name"
before insert on "table_name" for each row
begin
select "seq_name".nextval into :new."pk_name" from dual;
end;
you may set the "trigger" parameter to "true". This will prevent the "Sequence_name".nexval from being pulled twice (first time in the insert statement (see above), then in the trigger). Also usefull in combination with the "returning" parameter set to "true" for Oracle (in this case you may not specify the sequence name).
Please find below a list of properties that can be configured through the builder configuration properties, as defined in either the default or a custom XML code generator configuration file. These properties allow you to control various advanced options of the XML source generator.
By default, the Castor XML code generator will look for such a property file in the following places:
As of Castor 1.0.2, the Castor source generator now supports the generation of Java 5.0 compliant code. The generated code - with the new feature enabled - will make use of the following Java 5.0-specific artifacts:
To enable this feature (off by default), please uncomment the following property in your custom castorbuilder.properties file:
In previous versions, castor only supported (un)marshalling of "simple" java5 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. See the following example:
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. Examples for these cases are value="5" or value="-s". Castor now introduces an extended pattern, similar to the jaxb2 enum handling. 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. Additionally, some convenience methods are introduced, details about these methods are described after the following example:
Castor uses the static void fromValue(String value) method to retrieve the correct instance from the value in the xml input file. In our example, the input is "5", fromValue returns CompositeType.VALUE_5
Currently, we have to distinguish between enums with a class descriptor and the ones without. If you are using class descriptors, the EnumerationHandler uses the value() method to write the xml output.
If no descriptor classes are available, castor uses per default the toString() method to marshall the value. In this case, the override of the java.lang.Enum.toString() method is mandatory, because java.lang.Enum.toString returns the NAME of the facet instead of the VALUE. So in our example, "VALUE_10" would be returned instead of "10". To avoid this, castor expects an implementation of toString that returns "this.value".
If the java version is set to "5.0", the new default behavior of castor is to generate complex java5 enums for simpleType enumerations, as described above. In java 1.4 mode, nothing has changed and the old style enumeration classes using a HashMap are created.
Users, who are in java5 mode and still want to use the old style java 1.4 classes, can force this by setting the new "org.exolab.castor.builder.forceJava4Enums" property to true.
Bound properties are "properties" of a class, which when
updated the class will send out a
To enable bound properties, please add the following property definition to your custom builder configuration file:
When enabled, all properties will be treated as bound properties. For each class that is generated a setPropertyChangeListener method is created as follows:
Whenever a property of the class is changed, a
The source generator can treat the XML Schema structures such as <complexType> and element in two main ways. The first, and current default method is called the "element" method. The other is called the "type" method.
To change the "method" of class creation, please add the following property definition to your custom builder configuration file:
The source generator enables the user to set a super class to all the generated classes (of course, class descriptors are not affected by this option). Pleae note that, though the binding file, it is possible to define a super class for individual classes
To set the global super class, please add the following property definition to your custom builder configuration file:
An XML Schema instance is identified by a namespace. For data-binding purposes, especially code generation it may be necessary to map namespaces to Java packages.
This is needed for imported schema in order for Castor to generate the correct imports during code generation for the primary schema.
To allow the mapping between namespaces and Java packages , edit the castorbuilder.properties file :
Since version: 0.9.1
The Source Generator can override the equals() and hashCode() method for the generated objects.
To have equals() and hashCode() methods generated, override the following property in your custom castorbuilder.properties file:
Since version 0.9.4
It may be convenient to use java objects instead of primitives, the Source Generator provides a way to do it. Thus the following mapping can be used:
To enable this property, edit the castor builder.properties file:
Since version 1.1.1
With this property enabled, the XML code generator will use a new automatic class name resolution mode that has special logic implemented to automatically resolve class name conflicts.
This new mode deals with various class name conflicts where previously a binding file had to be used to resolve these conflicts manually.
To enable this feature (turned off by default), please add the following property definitio to your custom castorbuilder.properties file:
Specifies whether extra (additional) methods should be created for collection-style fields. Set this to true if you want your code to be more compatible with Castor JDO (or other persistence frameworks).
Adds additional getter/setter methods for the field in question, such as get/set by reference and set as copy methods.
As of release 1.2, Castor 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
call the
As we consider the code stable enough for a major release, we do encourage users to use the new Velocity-based mode and to provide us with (valuable) feedback.
Please note that we have changed the mechanics of changing the JClass printing type between releases 1.2 and 1.2.1.
As of release 1.2, the Castor XML code generator - if configured as shown below - now
supports generation of additional methods to allow programmatic access to
<xs:documentation> elements for top-level type/element definitions as
follows:
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:
This document provides object mapping examples and the corresponding Java objects and DDL for the database table.
The following fragment shows the Java class declaration for the Product class:
The following fragment shows the Java class declaration for the ProductGroup class:
The following sections show the DDL for the relational database tables PROD, PROD_GROUP, and PROD_DETAIL:
PROD:
PROD_GROUP:
PROD_DETAIL:
The following code fragment shows the object mapping for the ProductGroup class:
As a result of that declaration, Castor JDO will create the following SQL statements for creating, deleting, loading and updating instances of ProductGroup:
To declare the name field read-only, the field definition above for the field name needs to be changed to:
As a result of that declaration, Castor JDO creates the following SQL statements for creating, deleting, loading and updating instances of ProductGroup:
To declare the name field transient with regards to persistence, above field definition for the field name needs to be changed to:
The following code fragment shows the mapping file for the Product class. Apart from the simple field declarations, this includes a simple 1:1 relation between Product and ProductGroup, where every product instance is associated with a ProductGroup:
The following code fragment shows (again) the mapping file for the Product class. The field definition highlighted shows how to declare a 1:M relation between Product and ProductDetail, where every product instance is made up of many ProductDetails:
The following code fragment shows the corresponding mapping entry for the ProductDetail class that defines the second leg of the 1:M relation between Product and ProductDetail.
The following code fragment shows (again) the mapping file for the Product class. The field definition highlighted shows how to declare a M:N relation between Product and ProductCategory, where many products can be mapped to many product categories:
The following code fragment shows the corresponding mapping entry for the ProductCategory class that defines the second leg of the M:N relation between Product and Category.
As of release 0.9.9, Castor supports polymorphic queries on extend hierarchies. (That is, hierarchies where some entities "extend" other entities.) To highlight this new feature, let's add two new classes to what we have currently.
The corresponding DDL statements for the relational database tables COMP and CAR would look as follows:
COMP:
CAR:
Based upon the mapping defined for the Product class as shown above, the following code fragment shows the mapping for the Computer and Car classes.
Based upon this mapping, it is possible to execute the following OQL queries against this class model:
To return all computers:
To return all computers of a particular make:
To return all products (where Castor will return the actual object instances, i.e. a Computer instance if the object returned by the query is of type Computer or a Car instance if the object returned by the query is of type Car):
To return all products that belong to the specified product group (where Castor will return the actual object instances, i.e. a Computer instance if the object returned by the query is of type Computer or a Car instance if the object returned by the query is of type Car):
Based upon above definitions, here are a few OQL sample queries that highlight various artifacts of the OQL support of Castor JDO.
To Be Written
The best way to get in touch with us is via the dev and user mailing lists. For more information, please see Mailing Lists. You can also get directly in touch with various contributors and committers.
Castor developers and committors can also sometimes be found at the #castor IRC channel at irc.codehaus.org. You can find more information and alternate means of access to the IRC channel at our support page.
Please carefully make yourself familiar with the license model of Castor, available here.
Latest Released Version: Castor $STABLE_VERSION$ $STABLE_RELEASE$
Release date: $STABLE_RELEASE_DATE$
Release notes - What changed ?
The tarball and zips include all the JARs required by Castor, the docs, and the API JavaDocs. To fully install Castor, simply extract all the JARs into your classpath.
The SVN snapshot includes additional JARs required to build Castor. It is self-sufficient and does not require any external components other than javac.
The documentation set includes JavaDocs for the full source code, documenting class usage. A small documentation set without the full source JavaDocs is available in the tarball and zips.
All of the JARs included with Castor (used for building Castor) are available for distribution free of charge, subject to the respective license agreements.
All implementation JARs (i.e. not APIs) are available under an open source license and available from our FTP server. Open source licenses in use include Apache (ASF), Exolab, Mozilla (MPL), and public domain. All licenses are fully compatible with each other.
The example JAR includes fully functional samples that demonstrate the use of various features of Castor -- including marshaling and unmarshaling to and from XML, data persistence using JDO, and source code generation from an XML Schema instance.
The example web application (in form of a WAR archive) includes fully functional samples that demonstrate the use of Castor from within a standard J2EE web application. The WAR file can be deployed to any J2EE compliant web application container (including, amongst others, Tomcat, WebSphere, JBoss, and Weblogic) using the standard deployment method of your web application server.
The JARs in this directory carry a timestamp in their name. Please make sure that you always use the latest JAR file, unless you require a specific version.
For those of you working with Maven 2, please add the following dependency to your POM to include the Spring factory beans for Castor XML with your project:
As we currently provide snapshot releases only for the factory beans, you will have to add the following <repository> element to your POM as well, so that Maven 2 knows about the Codehaus Snapshot repository when trying to resolve and download dependencies.
The JARs in this directory carry a timestamp in their name. Please make sure that you always use the latest JAR file, unless you require a specific version.
For those of you working with Maven 2, please add the following dependency to your POM to include the Spring ORM package for Castor JDO with your project:
As we currently provide snapshot releases only for the factory beans, you will have to add the following <repository> element to your POM as well, so that Maven 2 knows about the Codehaus Snapshot repository when trying to resolve and download dependencies.
You may be able to find some past releases on the HTTP Server:
To obtain the latest SVN version, please use a SVN-enabled client to access our SVN server. Instructions for doing so can be found here.
For those of you behind a firewall with the SVN port non-accessible, please
download Castor from the SVN server using the HTTP interface at
JARs required to build Castor and dependencies for various packages are contained in the lib directory. For details, please see dependencies.
Castor is an Open Source data binding framework for Java[tm]. It's the shortest path between Java objects, XML documents and relational tables. Castor provides Java-to-XML binding, Java-to-SQL persistence, and more.
Please check here for any information related to changes of the HTML documentation.
In some cases it is desirable to map a plain sequence of fields
in a database record to more complicated structure of attributes
in a Java object, where the target attributes are contained (nested)
in other attributes.
In brief, you can specify a path to the target attribute as a name
of the field in a configuration file, and Castor is able to handle
such nested attributes.
For example:
The first case is an attribute of an application type that is a container for some value of a Java type supported by Castor. Usually the application type also has some business methods. Examples are: class Balance that contains a BigDecimal value and has some accounting-specific methods; class CountryCode that contains a String value and has methods validate(), getDisplayName(), etc.; class Signature that contains a byte[] value and has some security-specific methods. In order to use such type with Castor you should provide a pair of methods to get/set the value of the Castor-supported type, e.g. getBigDecimal/setBigDecimal, getCode/setCode, getBytes/setBytes.
Assume that you have the class Address
public class Address {
private CountryCode _country;
private String _city;
private String _street;
public CountryCode getCountry() {
return _country;
}
public void setCountry(CountryCode country) {
_country = country;
}
...
}
where the class CountryCode is like this
public class CountryCode {
private String _code;
private static String[] _allCodes;
private static String[] _allDisplayNames;
public String getCode() {
return _code;
}
public void setCode(String code) {
_code = code;
}
public void getDisplayName() {
...
}
then write in the configuration file:
...
]]>
When reading the object from the database Castor will use
object.getCountry().setCode(value);
to set the nested attribute value.
Moreover, if object.getCountry() is null, Castor will create the
intermediate object of the application type:
country = new CountryCode();
country.setCode(value);
object.setCountry(country);
When writing the object to the database Castor will use
value = object.getCountry().getCode();
to get the value of the correspondent database field.
The second case is an attribute that is a part of a compound attribute, which contains several database fields. For example, database fields person_country, person_city, person_street of the table PERSON correspond to one compound attribute "address" of the class Person:
public class Person {
private String _firstName;
private String _lastName;
private Address _address;
public Address getAddress() {
return _address;
}
public void setAddress(Address address) {
_address = address;
}
...
}
where the class Address is the same as in the previous section.
Then write in the configuration file:
...
]]>
Similarly to the previous section, Castor will use a proper
sequence of get/set methods to access the nested attributes and
will create the intermediate objects when necessary.
Don't forget to provide parameterless constructors for the
container classes.
When developing using Castor, we recommend that you use the various setLogWriter methods to get detailed information and error messages.
Using a logger with
Using a logger with
Using a logger with
A simple trace logger can be obtained from
Interested in integratating Castor's logging with Log4J? Then see this question in the JDO FAQ.
If you are using JDO objects with the default access mode ('shared') and too many transactions abort when attempting to commit due to locks, you should consider upgrading to an 'exclusive' mode. When two transactions attempt to modify and store the same object at the same time, lock issues arise. Upgrading to an 'exclusive' mode will prevent concurrent transactions from modifying the same object at once.
If too many transactions abort when attempting to commit due to dirty checking, you should consider upgrading to a 'locked' mode. When external database access modifies the same objects being managed by Castor, Castor will complain that objects are dirty. Upgrading to a 'locked' mode will prevent concurrent update.
Be advised that 'exclusive' mode introduces lock contention in the Castor persistence engine, and 'locked' mode adds lock contention in the database. Lock contention has the effect of slowing down the application and consuming more CPU.
If too many transaction abort due to deadlock detection, consider modifying the application logic. Deadlock occurs when two transactions attempt to access the same objects but not in the same order.
There are two types of inheritence: Java inheritence and relational inheritence.
With Java inheritence, two objects extend the same base class and map to two different tables. The mapping file requires two different mappings for each of the objects. For example, if Employee and Customer both extend Person, but Employee maps to the table emp and Person to the table person, the mapping file should map both of these objects separately.
With relation inheritence, one table provides the base information and another table provides additional information using the same primary keys in both. Use the extends attribute to specify such inheritence in the mapping file. For example, if Computer extends Product and the table comp provides computer-specific columns in addition to product columns in prod, the mapping for Computer will specify Product as the extended class.
When a class just extends a generic base class or implements an interface, this form of inheritence is not reflected in the mapping file.
It is possible to use different objects and mappings to the same tables. For example, it is possible to define a subset of a table and load only several of the columns, or load an object without its relations.
To determine the first and last names and e-mail address of an object without loading the entire person object, create a subset class and map that class to a portion of the table. Such a class cannot be used to create a new person, but can be used to delete or modify the person's details.
Use partial views with care. If you attempt to load the same record using a full
object and a subset object, changes to one of these objects are allowed, but
changes to both will result in a conflict and roll back the transaction.
Locking will not work properly between full and subset objects.
Also note, that each of the two objects will have its own cache, so
if you update the first object and load the second, you may obtain old values.
To avoid this situation you may turn off the cache for both objects:
When an object is loaded into memory in the default access mode ('shared'), a read lock is acquired on that object. When the transaction commits, if there are changes to the object a write lock will be required. There is no guarantee that a write lock can be acquired, e.g. if another transaction attempts to change the same object at the same time.
To assure concurrent access, you may upgrade the object's lock by calling the
Object locking is recommended only if concurrent access results in conflicts and aborted transactions. Generally locks results in lock contention which has an effect on performance.
Check your CLASSPATH, check it often, there is no reason not to!
Castor requires that classes have a public, no-argument constructor in order to provide the ability to marshal & unmarshal objects of that type.
create-method is an optional attribute to the <field> mapping element that can be used to overcome this restriction in cases where you have an existing object model that consists of, say, singleton classes where public, no-argument constructors must not be present by definition.
Assume for example that a class "A" that you want to be able to unmarshal uses a singleton class as one of its properties. When attempting to unmarshal class "A", you should get an exception because the singleton property has no public no-arg constructor. Assuming that a reference to the singleton can be obtained via a static getInstance() method, you can add a "create method" to class A like this:
and in the mapping file for class A, you can define the singleton property like this:
This illustrates how the create-method attribute is quite a useful mechanism for dealing with exceptional situations where you might want to take advantage of marshaling even when some classes do not have no-argument public constructors.
Note: As of this writing, the specified create-method must exist as a method in the current class (i.e. the class being described by the current <class> element). In the future it may be possible to use external static factory methods.
Castor XML mapping is a way to simplify the binding of java classes to XML document. It allows to transform the data contained in a java object model into/from an XML document.
Although it is possible to rely on Castor's default behavior to marshal and unmarshal Java objects into an XML document, it might be necessary to have more control over this behavior. For example, if a Java object model already exists, Castor XML Mapping can be used as a bridge between the XML document and that Java object model.
Castor allows one to specify some of its marshalling/unmarshalling behavior using a mapping file. This file gives explicit information to Castor on how a given XML document and a given set of Java objects relate to each other.
A Castor mapping file is a good way to dissociate the changes in the structure of a Java object model from the changes in the corresponding XML document format.
The mapping information is specified by an XML document. This document is written from the point of view of the Java object and describes how the properties of the object have to be translated into XML. One constraint for the mapping file is that Castor should be able to infer unambiguously from it how a given XML element/attribute has to be translated into the object model during unmarshalling.
The mapping file describes for each object how each of its fields have to be mapped into XML. A field is an abstraction for a property of an object. It can correspond directly to a public class variable or indirectly to a property via some accessor methods (setters and getters).
It is possible to use the mapping and Castor default behavior in conjunction: when Castor has to handle an object or an XML data but can't find information about it in the mapping file, it will rely on its default behavior. Castor will use the Java Reflection API to introspect the Java objects to determine what to do.
Note: Castor can't handle all possible mappings. In some complex cases, it may be necessary to rely on an XSL transformation in conjunction with Castor to adapt the XML document to a more friendly format.
For Castor, a Java class has to map into an XML element. When Castor marshals an object, it will:
or
It will then use the fields information from the mapping file to determine how a given property of the object has to be translated into one and only one of the following:
This process will be recursive: if Castor finds a property that has a class type specified elsewhere in the mapping file, it will use this information to marshal the object.
By default, if Castor finds no information for a given class in the mapping file, it will introspect the class and apply a set of default rules to guess the fields and marshal them. The default rules are as follows:
When Castor finds an element while unmarshalling a document, it will try to use the mapping information to determine which object to instantiate. If no mapping information is present, Castor will use the name of the element to try to guess the name of a class to instantiate (for example, for an element named 'test-element', Castor will try to instantiate a class named 'TestElement' if no information is given in the mapping file). Castor will then use the field information of the mapping file to handle the content of the element.
If the class is not described in the mapping file, Castor will instrospect the class using the Java Reflection API to determine if there is any function of the form getXxxYyy()/setXxxYyy(<type> x). This accessor will be associated with XML element/attribute named 'xxx-yyy'. In the future, we will provide a way to override this default behavior.
Castor will introspect object variables and use direct access _only_ if no get/set methods have been found in the class. In this case, Castor will look for public variables of the form:
public <type> xxxYYY;
and expect an element/attribute named 'xxx-yyy'. The only handled collections for <type> are java.lang.Vector and array. (up to version 0.8.10)
For primitive <type>, Castor will look for an attribute first and then an element. If <type> is not a primitive type, Castor will look for an element first and then an attribute.
The following sections define the syntax for each of the mapping file artefacts and their semantical meaning.
This section defines a small domain model that will be referenced by various mapping file (fragments/samples) in the following sections. The model consists of two two classes Order and OrderItem, where an order holds a list of order items.
As shown above in bold, the Order instance has a (private) field 'orderItems' to hold a collection of OrderItem instances. This field is publically exposed by corresponding getter and setter methods.
<!ELEMENT mapping ( description?, include*, field-handler*, class*, key-generator* )>
The <mapping> element is the root element of a mapping file. It contains:
A mapping file look like this:
The <class> element contains all the information used to map a Java class into an XML document. The content of <class> is mainly used to describe the fields that will be mapped.
The auto-complete attributes is interesting as it allow a fine degree of control of the introspector: it is possible to specifiy only the fields whose Castor default behavior does not suite our needs. These feature should simplify the handling of complexe class containing many fields. Please see below for an example usage of this attribute.
The following mapping fragment defines a class mapping for the OrderItem class:
When marshalling an OrderItem instance, this yields the following XML:
The following mapping fragment defines a class mapping for the same class, where for all properties but id introspection should be used; the use of the auto-complete attribute instructs Castor XML to use introspection for all attributes other than 'id', where the given field mapping will be used.
When marshalling the very same OrderItem instance, this yields the following XML:
By removing the <map-to> element from above class mapping, ...
... Castor will use introspection to infer the element name from the Java class name (OrderItem), applying a default naming convention scheme.
When marshalling the very same OrderItem instance, this yields the following XML:
<map-to> is used to specify the name of the element that should be associated with the given class. <map-to> is only used for the root class. If this information is not present, Castor will:
Please note that it is possible to change the naming scheme used by Castor to translate between the XML name and the Java class name in the castor.properties file.
The following mapping fragment defines a <map-to element for the OrderItem class, manually setting the element name to a value of 'item'.
The following mapping fragment instructs Castor to assign a namespace URI of http://castor.org/sample/mapping/ to the <item> element, and use a namespace prefix of 'castor' during un-/marshalling.
When marshalling an OrderItem instance, this will yield the following XML:
<field> is used to describe a property of a Java object we want to marshal/unmarshal. It gives:
From this information, Castor is able to access a given property in the Java class.
In order to determine the signature that Castor expects, there are two easy rules to apply.
1. Determine <type>.
If there is no 'collection' attribute, the <type> is just the Java type specified in <type_attribute> (the value of the 'type' attribute in the XML document). The value of <type_attribute> can be a fully qualified Java object like 'java.lang.String' or one of the allowed short name:
Castor will try to cast the data in the XML file in the proper Java type.
The type of the object inside the collection is <type_attribute>. The 'default implementation' is the type used if the object holding the collection is found to be null and need to be instantiated.
For hashtable and maps (since 0.9.5.3), Castor will save both key and values. When marshalling output <key> and <value> elements. These names can be controlled by using a top-level or nested class mapping for the org.exolab.castor.mapping.MapItem class.
Note: for backward compatibility with prior versions of Castor, the saveMapKeys property can be set to false in the castor.properties file.
For versions prior to 0.9.5.3, hashtable and maps, Castor will save only the value during marshalling and during unmarshalling will add a map entry using the object as both the key and value, e.g. map.put(object, object).
It is necessary to use a collection when the content model of the element expects more than one element of the specified type.
2. Determine the signature of the function
If 'direct' is set to true, Castor expects to find a class variable with the given signature:
public <type> <name>;
If 'direct' is set to false or omitted, Castor will access the property though accessor methods. Castor determines the signature of the accessors as follow: If the 'get-method' or 'set-method' attributes are supplied, it will try to find a function with the following signature:
public <type> <get-method>();
or
public void <set-method>(<type> value);
If 'get-method' and 'set-method' attributes are not provided, Castor will try to find the following function:
public <type> get<capitalized-name>();
or
public void set<capitalized-name>(<type> value);
<capitalized-name> means that Castor takes the <name> attribute and put its first letter in uppercase without modifying the other letters.
The content of <field> will contain the information on how to map this given field to SQL, XML, ...
Exceptions concerning collection fields:
The default is to treat the 'get-method' as a simple getter returning the collection field, and the 'set-method' as a simple getter used to set a new instance on the collection field.
If a 'get-method' is provided for a collection field, Castor - in adition to the default behaviour described above - will deviate from the standard case for the following special prefixes:
public Iterator iterate...();
A 'get-method' starting with the prefix 'iterate' is treated as Iterator method for the given collection field.
public Enumeration enum...();
A 'get-method' starting with 'enum' is treated as Enumeration method for the given collection field.
If 'set-method' is provided for a collection field, Castor - in addition to the default behaviour described above - will accept an 'add' prefix and expect the following signature:
public void add...(<type> value);
This method is called for each collection element while unmarshalling.
In the case of XML mapping, the content of a field element should be one and only one <bind-xml> element describing how this given field will be mapped into the XML document.
Starting with release 0.9.5, for attribute mapped fields, support has been added to map a constructor field using the set-method attribute.
To specify that a field (mapped to an attribute) should be used as a constructor argument during object initialization, please specify a set-method attribute on the <field> mapping and use "%1" - "%9" as the value of the set-method attribute.
For example:
Note that because the set-method is specified, the get-method also must be specified.
Tip: the XML HOW-TO section has a HOW-TO document for mapping constructor arguments, incl. a fully working mapping.
The following mapping fragment defines a <field> element for the
member property of the org.some.package.Root class,
specifying a custom
The same custom field handler as in the previous sample can be defined with a separate configurable <field-handler> definition, where additional configuration can be provided.
and subsequently be referred to by its name as shown in the following field mapping:
Assume you have a class mapping for a class Order which defines - amongst others - a field mapping as follows, where the field item refers to an instance of a class Item.
Marshalling an instance of Order would produce XML as follows:
If you do not want the Item instance to be marshalled, but only its fields, change the field mapping for the item member to be as follows:
The resulting XML would look as follows:
The <bind-xml> element is used to describe how a given Java field should appear in an XML document. It is used both for marshalling and unmarshalling.
Since 0.9.5.3, the bind-xml element supports a nested class mapping, which is often useful when needing to specify more than one mapping for a particular class. A good example of this is when mapping Hashtable/HashMap/Map.
Here is an example of how Castor Mapping can be used. We want to map an XML document like the following one (called 'order.xml'). model.
Into the following object model composed of 3 classes:
The sources of these classes follow.
The XML document and the java object model can be connected by using the following mapping file:
The following class is an example of how to use Castor XML Mapping to manipulate the file 'order.xml'. It unmarshals the document 'order.xml', computes the total price, sets the total price in the java object and marshals the object model back into XML with the calculated price.
Ordinarily, a mapping will only reference types that are concrete classes (i.e. not interfaces nor abstract classes). The reason is that to unmarshal a type requires instantiating it and one cannot instantiate an interface. However, in many real situations, object models depend on the use of interfaces. Many class properties are defined to have interface types to support the ability to swap implementations. This is often the case in frameworks.
The problem is that a different mapping must be used each time the same model is to be used to marshal/unmarshal an implementation that uses different concrete types. This is not convenient. The mapping should represent the model and the specific concrete type used to unmarshal a document is a configuration parameter; it should be specified in the instance document to be unmarshalled, not the mapping.
For example, assume a very simple object model of an engine that has one property that is a processor:
A typical mapping file for such a design may be:
It is possible to use such a mapping and still have the marshal/unmarshal process work by specifying the concrete implementation of IProcessor in the document to be unmarshalled, using the xsi:type attribute, as follows:
In this manner, one is still able to maintain only a single mapping, but vary the manner in which the document is unmarshalled from one instance document to the next. This flexibility is powerful because it enables the support of polymorphism within the castor xml marshalling framework.
Suppose we wanted the following XML instead:
In the above output our XML name changed to match the type of the class used instead of relying on the xsi:type attribute. This can be achieved by modifying the mapping file as such:
Since 0.9.5
The location attribute allows the user to map fields from nested elements or specify a wrapper element for a given field. Wrapper elements are simply elements which appear in the XML instance, but do not have a direct mapping to an object or field within the object model.
For example to map an instance of the following class:
Some helpful hints...
Castor comes with a tool that can automatically create a mapping from class files. Please see the XML FAQ for more information.
Sometimes to handle complex situations you'll need to create your own FieldHandler. Normally a FieldHandler deals with a specific class and field, however generic, reusable FieldHandlers can also be created by extending org.exolab.castor.mapping.GeneralizedFieldHandler or org.exolab.castor.mapping.AbstractFieldHandler. The FieldHandler can be specified on the <field> element.
For more information on writing a custom FieldHandler please see the following: XML FieldHandlers.
You may map any attributes to constructor arguments. For more information on how to map constructor arguments see the information available in the section on set-method above.
Please note that mapping elements to constructor arguments is not yet supported.
Tip: the XML HOW-TO section has a HOW-TO document for mapping constructor arguments.
Sometimes it's useful to prevent Castor from checking for a default constructor, such as when trying to write a mapping for an interface or type-safe enum. You can use the "undocumented" verify-constructable="false" attribute on the <class> element to prevent Castor from looking for the default constructor.
While you can always use your own custom FieldHandler for handling type-safe enumeration classes, Castor does have a built-in approach to dealing with these types of classes. If the type-safe enum class has a public static <type> valueOf(String) method Castor will call that method so that the proper instance of the enumeration is returned. Note: You'll also need to disable the default constructor check in the mapping file (see section 7.4 above to see more on this).
For all releases prior to 0.9.6, the release notes can be found here.
To persist an Java enum it needs to be converted to a string. To do so Castor previously called toString() method of the enum. This worked out well until the toString() method got overwritten by a user to provide localized messages to be displayed for the enum values. In such a case the localized message got written to the database which caused failures when entity was loaded from database again. By calling name() method to convert the enum value to an string this will not happen any more.
The following Interfaces, Classes, Methods and Properties that had been deprecated at previous Castor releases have been removed.
The entry in to enable connection proxies in properties file should now be:
If regular expressions are being used with Castor XML, Castor XML now throws a IllegalStateException when no regular expression engine id specified in a custom castor.properties file (using the org.exolab.castor.regexp property). Please check with the reference guide to see what regular expression engines are supported.
You can configure Castor to use Atomikos transaction manager as follows:
It is now possible to specify named native (SQL) queries at the class level:
For various reasons, support for Ant as build tool has been dropped altogether. Please switch to use Maven 2, with the relevant project-specific details available at here.
Please note that the code base still includes Ant build files. Please do not use them! Ant files in the trunk are in the process of being removed, though this will take us some time.
The classes CoreConfiguration, XMLConfiguration and CPAConfiguration have been replaced by CoreProperties, XMLProperties and CPAProperties respectively. For backward compatibility we have kept the *Configuration classes and declared them deprecated. As we intend to remove *Configuration classes with next Castor release we encourage you to change your code to use *Properties instead.
A new option has been added to specify the location of a custom Castor properties file by the means of a system property. This alters the sequence with which Castor XML searches for a custom properties as weil.
To specify the location of a Castor XML property file by using a system property, please use ....
As of this release, Castor requires a Java 5.0 (and above) JVM at run-time. In addition, the XML code generator now emits Java 5.0-complaint code as well (which can be changed back to Java 1.4 compliance by setting the org.exolab.castor.builder.javaVersion property.
Added new org.exolab.castor.xml.lenient.integer.validation property to allow configuration of leniency for validation for Java properties generated from <xs:integer> types during code generation. This will allow successful validation for Java members that have been generated with Castor versions of 1.0.5 and older.
For long transactions (detached objects) to work it was required that the entity has been kept in cache from being loaded until its update. If the entity was expired from cache before the update an ObjectModifiedException had been thrown. While this is no problem if all entities of an application can be kept in cache all the time, it is one for large scale applications with millions of entities.
With release 1.3 we have changed the handling of timestamps. While it is still possible to rely on cache only it is now also possible to persist the timestamp together with the other properties of the entity. Doing so will ensure that the timestamp do not change even if the entity got expired from cache from being loaded until it get updated. If this happens the entity gets reloaded during update which also loads the previous timestamp. Having said that it still is possible that an ObjectModifiedException is thrown when another user has changed the same entity in the meantime.
See an example entity and its mapping below:
As we had to change the package of the drivers in castor.properties anyway, we also renamed the property that configures the classnames of the available drivers from org.exolab.castor.jdo.engines to org.castor.cpa.persistence.sql.driver.factories.
The entry in properties file should now be:
As we had to change the package of the drivers in castor.properties anyway, we also renamed the property that configures the classnames of the available drivers from org.exolab.castor.jdo.keyGeneratorFactories to org.castor.cpa.persistence.sql.keygen.factories.
The entry in properties file should now be:
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:
Users are encouraged the use the new Velocity-based mode and to provide us with (valuable) feedback.
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.
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.
Be aware that no proxy interfaces are defined by default as the interface search slightly decreases marshalling performance.
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:
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:
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.
See the description in the Source Generator Properties section for details.
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:
and subsequently refer to this custom (configurable) field handler by its name as shown in the following field mapping:
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.
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:
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.
New JavaNaming is an exchangeable service instantiated trough XMLContext and accessed in a non-static way.
New XMLClassDescriptorResolver internally works with strategy and command pattern to have the possibility to enhance class resolving for future implementations (e.g. JAXB support).
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.
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:
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:
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:
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.
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.
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.
Castor XML now supports Java 5 enums in all cases where either a mapping file is used or it is relied upon default introspection.
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.
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.
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:
This new mode will avoid class name conflicts by prepending XPATH fragments or type suffices to the 'normal' class name as generated otherwise.
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 the XML schema type <xs:hexBinary> during XML code generation.
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.
The XML (Un-)Marshaller now supports the data type hexBinary.
The public interface of XMLClassDescriptorResolver has been improved and streamlined, adding various new methods for pre-loading class descriptors. Please check here for details.
To specify an existing root object to be used during unmarshalling,
Added new functionality to XMLClassDescriptorResolver to pre-load class descriptors for a package. Please find details about this new feature at the best practises for Castor XML.
As Sun has included Apache's Xerces with Java 5.0 by default, we have added support for using the Xerces instance as shipped with the JRE/JDK for serialization. As such, for Java 5.0 users, this removes the requirement to download Xerces separately.
To enable this new feature, please change the following property in your local castor.properties file (thus redefining the default value) as shown below:
As of this release, Castor now builds under JDK 6.0. Castor XML has been tested under JDK 6.0. However, Castor JDO has not really been tested under JDK 6.0. Note that you may need to use a JDBC 4.0 compatible connector with this new JDK.
If you are using the Castor code generator to generate code from schemas that use xsd:import, whether or not code was generated from the imported schemas was controlled by a combination of switches. Now it is controlled only by the "-generateImportedSchemas" option of SourceGeneratorMain, the Ant task option of the same name, or if you are calling codegen programmatically, the method sgen.setGenerateImportedSchemas(true);.
The XML CTF has been moved to its own area. It has been moved from ./src/tests/ into ./xmlctf/. All scripts to run the CTF have been updated for this change.
At the Google Summer of Code program for 2006, the student Le Duc Bao worked for Castor. With support of his mentor Ralf Joachim, he implemented a generator for DDL scripts from scratch.
Castor DDL Generator creates a SQL script to drop/create tables, unique keys, sequences and so on, from a Castor JDO mapping file.
This will generate the SQL script mapping.sql in the same directory mapping.xml is located.
As part of this release, we have started to move several areas of functionality to separate deployment units, resulting into additional JARs available for download:
In addition, as outlined above, the new DDL generator has been made available as a separate deployment unit as well, resulting into ...
Please note that the Castor XML (and JDO) JARs do not include these components anymore. In other words, if you want to use both Castor XML (for (un-)marshaling) and the XML code generator for code generation from an XML schema, you will have to download both JARs. For details, please have a look at the download instructions.
As part of the work for fixing bug 1760, it has been recognized that the approach taken as part of working on issue 1741 was slightly too ambitious.
As such, the XML code generator has been changed (again) to generate the following Java types for elements/attributes typed with <xs:int> and <xs:integer>:
Type
Old Java type
New Java type
As part of the work for fixing bug 1421, it has been recognized that the code generated pre-patch did not comply with the set of rules defined in the XML schema specification.
As such, the XML code generator has been changed to generate the following Java types for elements/attributes typed with <xs:int> and <xs:integer>:
Type
Old Java type
New Java type
The only difference between the artifacts generated is that a different Java type is used with a different (and appropriate to the specification) value range. Thus, the value range that will be accepted by the generated Java instance variables has changed.
The CTF currently requires the Sun JDK (or SDK) to execute, although it may be possible to execute with GNU gcj or with JRockit. The CTF will not work if you are using only a JRE. This is because the CTF uses the Sun Java compiler API to compile code as needed for Source Generator and Marshaling Framework tests. The CTF code is written to allow easy extension for additional compiler frameworks, so if you use a compiler or runtime that is not supported, you should be able to easily add support for a new framework. If you want to do this, contact Castor committors for assistance and direction and they'll set you on the right course.
Two new features have been added to the CTF that allow users to add Java-version-specific tests. The first new feature applies to an entire test, that is, the full suite of tests described by a single TestDescriptor.xml file. If you add the following tag to a TestDescriptor.xml:
<MinimumJavaVersion>1.5</MinimumJavaVersion>
then the entire suite of tests described by that test descriptor will be skipped if the version of Java executing the test suite is not at least the minimum version specified.
For the second new feature, if you add the following tag to an individual Unit Test in a TestDescriptor.xml:
<JavaSourceVersion>1.2</JavaSourceVersion>
then for that individual unit test, all code will be compiled with the javac parameter -source 1.2, using the version specified.
For both of these parameters, you are expected to supply a value that is allowed by the javac -source command-line option, although if you specify an integer between 5 and 9 (inclusive), that value will automatically be converted to the correct value.
In the source generator, all facets are now implemented for all of the XML Schema date/time types with one exception: validation for the "fixed" facet of xsd:dateTime is not implemented. This is because Castor marshals dateTime as a java.util.Date, which does not contain time zone information. A later release of Castor may marshal xsd:dateTime into a java.util.Calendar instead of java.util.Date.
An additional unit test type has been added to the MarshallingTest and SourceGeneratorTest test types that allows invoking user-supplied arbitrary code that will either return a boolean "false" or an Exception if the user-test fails or it will throw an exception if the user-test fails. For a sample of this new unit test type, see the tests in the directory
MasterTestSuite/sourcegenerator/Facets/DateTimeNoTimeZone/
Previously, the class descriptors (used during marshaling and unmarshaling to provide constraints, validation assistance, etc.) were generated into the same directory (same package) as the classes they describe. Starting with this release, the class descriptors are generated into a subpackage named "descriptors" one directory lower than the package where the classes being described are generated. Doing so prevents the class descriptors from cluttering up the directory where the code the developer cares about will be generated.
An additional benefit of this change occurs if you generate source into a directory that already contains other source code. In this instance, it can be difficult for ANT to determine whether or not you need to regenerate the generated source code, that is, whether the XSD file is newer or older than the generated source. Under the usual circumstance where the descriptors subpackage contains only generated code, you can use the ANT <uptodate> task to compare the timestamp of the XSD file against the timestamps of the descriptors, and thus reliably know whether or not you have to regenerate source code.
For marshaling and unmarshaling, the class descriptors will be located via the ".castor.cdr" files located in the directories (packages) where the classes are generated. If these files are deleted or are not kept (we highly recommend including these files in your JAR file) then the class descriptor resolver will first look for the class descriptors in the same package where the classes to be described are. If they are not found there, then the class descriptor resolver will look in a subpackage "descriptors." This maintains backwards compatibility with code generated under older Castor releases.
It is now -- at the <member> level -- possible to specify a Java member's visibility (different from the default value "private") similar to ...
Valid values for the visibility attribute are protected, private and public, as per the definition in binding.xsd.
Added support for specifying additional collection types in a binding file, similar to ...
The following types have been added: 'collection', 'set' and 'sortedset'.
The default IDResolverImpl class has been changed so that a validation exception will be thrown if an empty or duplicate ID value is encountered.
The XML code generator has been enhanced so that it is possible to provide a binding for the following enumeration ...
as follows:
Castor XML now supports validation of <xsd:ID>s during marshaling, preventing the following scenarios from being marshaled successfully (throwing a ValidationException instead):
The Castor code generator now uses 'java.util.List' as type when generating code for a Java member (as well as the type used for the corresponding getter and setter methods) rather than the old 'java.util.ArrayList'.
To not lose features like JDBC 3.0 introduced with the 1.0 release of Castor, we decided to use reflection or dynamic proxies in some places. This allows one to use these features with Java 1.4 while still being able to use Castor with Java 1.3.
We have added a database appender for log4j through CastorJDO to our
codebase in the org.castor.tools.log4j package. The appender
has to be configured through log4j.xml configuration file as usual.
To use the appender within your application you need to create tables
to hold the log information at your database. An example script to create
these tables as well as examples of mapping.xml and jdo-config.xml can
also be found in org.castor.tools.log4j package.
Before you use the logger for the first time you need to initialize CastorJDO.
Thereafter you can use your logger as usual. Log4j will use CastorAppender to write the log information to the database.
One additional thing you need to take care of: As CastorAppender does some caching to reduce database operations, you have to tell it to write all cached information to database before you close your application.
We also provided a way to extend the information logged to database. For an example extension take a look at LogReferenceExtension and TestCastorAppender classes as well as the example mapping file.
As part of a field mapping, it is now possible to specify two special methods that will be treated in a non-standard way. If the 'get-method' specified on a field mapping starts with either 'enum' or 'iterate', it will be treated in a way that the collection (container) is only exposed through this 'enumeration'/'iteration' method.
To disabled selected features on the XML parser used internally by Castor XML, please use the new property org.exolab.castor.sax.features-to-disable as shown below
# Comma separated list of SAX 2 features that should be disabled
# for the default parser.
#org.exolab.castor.sax.features-to-disable
For a sample and for the place to add future test cases for the Master Test Suite, see the directory tree src/tetsts/xml/MasterTestSuite/sourcegenerator/generationOnly, although regression tests should be added to the regression suite
Support for Progress has been added. For initial information about configuration of Castor JDO for the use with Progress, please see src/tests/jdo/progress.xml.
In addition to the already existing methods, two new unmarshal() methods have been added to Unmarshaller, namely ...
The Castor source generator now supports the generation of Java 5.0 compliant classes. The generated code - with the new feature enabled - will make use of the following Java 5.0-specific artefacts:
To enable this feature (off by default), please uncomment the following property in your custom castorbuilder.properties file:
Added new property to castor.properties to disable use of package-based '.castor.xml' files during class resolution selectively, which is enabled by default.
To disable this feature, please uncomment the following property in your custom castor.properties file:
In the past Castor differentiated between single and multiple field identities of persistent objects. For single field identities Castor hold the identitiy object itself while the objects of a multiple field identity where wrapped by an instance of Complex class. This caused various if-then-else constructs to differentiat the 2 representations of identities.
With the refactoring identities are now always wrapped by an instance of Identity class being it a single or a multiple fields one. This resulted in much cleaner code at various areas and in addition we could improve type checking by declaring lots of properties and parameters to be of Identity class instead of simply Object.
While we could manage to be backward compatible for all methods that
gets an identity passed (e.g. Database.load(Class, Object))
this was not possible for Database.getIdentity(Object).
Instead of the single field identity or an instance of Complex class
for multiple field identities it now always returns an instance of
Identity class.
You have to be aware that you need to adapt your code to get things
working as before if you use Database.getIdentity(Object)
method.
As of release 1.0.2 the MappingLoader implementations need to be configured in castor.properties file. While this also allows to specify external MappingLoader implementations to be used by Castor, it now is also required to specify the 2 internal implementations in this file.
#
# MappingLoader implementations
#
org.castor.mapping.Loaders=\
org.exolab.castor.jdo.engine.JDOMappingLoader,\
org.exolab.castor.xml.XMLMappingLoader
You have to be aware that you need add the new configuration property to you custom castor.properties file.
On April 14. 2006 we have migrated Castor source repository from CVS to SVN. At the moment we still provide read only access to CVS but this does not reflect commits to SVN after the migration. The read only access to CVS is intended for you to create patches of your current work and move it over to SVN. Be aware that we will switch off CVS soon.
For details about SVN access please have a look at: SVN/JIRA.
By specifing
at class mapping you can now use ehCache with Castor JDO. As of ehcache 1.2, ehcache can be used as a distributed cache.
By specifing
at class mapping you can now use Gigaspaces with Castor JDO, supporting all possible use scenarios of Gigaspaces (local cache, remote cache, local master cache, distributed cache, partitions) in a flexible way.
Refactored the SQLServer-specific classes to support ANSI-SQL-92 compliant syntax in addition to the existing code base.
This is a reminder that we have started to add some features that more or less depend on features made available with Java 1.4 (only), such as the JDBC 3.0 API enhancements. As such, we have made Java 1.4 a key requirement for the upcoming Castor 1.0 release.
For all the releases prior to 1.0, the release notes can be found at here.
castor-1.3.2.orig/src/doc/releases-old.xml 0000644 0000000 0000000 00000001773 11544322135 015302 0 ustarStarting with release 1.3 of Castor, documentation of previous Castor releases will be available for browsing for a restricted number of releases. The following table links to the documentation sets for the enlisted releases.
Below is a list of tasks that have been identified for refactoring in Castor JDO. This list is continually evolving and should be checked often. There are no scheduled release dates for these items. This is because Castor JDO is entirely a volunteer effort and team members contribute in their spare time. Some of these tasks are in progress and some have not been started at all.
There is always plenty of work to be done. If you would like to participate, please let us know. If you see a task that you would like to work on please let us know. I you see a task that you would like to work on but has already been assigned to someone, that doesn't mean that you can't help out or even take it over. Simply contact the JDO project leader (available here).
Description:
Castor is very tightly coupled in it's design. This tight coupling
leads to maintainence trouble, difficult to understand code, etc.
Volunteer:
Status: not started
Date Started:
Notes:
See the mail list threads titled
Castor JDO Status and
Strategy Proposal.
These threads are especially long and tend to be broken on
mail-archive.com. But there are some very good ideas amongst these two
threads concerning the modularization of Castor JDO.
This is a high-level architectural change that includes many of the
items in this list.
Description:
Switching the logging mechanism in Castor
over to using the
Jakarta Commons Logging with Log4J as the default logger.
Not only will this help to improve the logging quality, but it will
also allow users to choose their logging framework of choice.
Volunteer: Bruce Snyder
Status: completed
Date Started: 5 May 2003
Notes:
Not sure if Jakarta Commons Logging should be used in Castor
because of the inability to configure some finer features in Log4J.
See this
article for some info. This article may be talking about
programmatic configuration of Log4J which I'm not really worried
about. All of the configuration in Castor will take place in a
properties or XML file.
Post Mortem:
Jakarta Commons Logging was used with Log4J as the default logger. Now
the amount of logging just needs to be increase and configurations
offered in the default properties files for ease of disabling stuff
that's spewing. I'll be adding a class to support the TRACE level as
well.
Description:
Writing test cases is a critical effort to the
evolution of Castor JDO. All bug fixes and new functionality must contain
test cases unless the bug fix is trivial. All test cases are written
using the Castor Test Framework for JDO
(CTF-JDO).
The verison of JUnit used by Castor is quite outdated (version 3.5). This needs to be updated to the latest version (as of this writing, version 3.8.1). There is a certain amount of work involved with this in changing all assert() calls to the newer, more specific assert calls (e.g. assertTrue(), assertEquals(), assertNull(), assertNotNull(), etc.). Also look into the use of Log4Unit as opposed to JUnit. Log4Unit is an extension to JUnit that provides a logging component to JUnit to provide better logging for both failures and successes.
In addition to using JUnit, a database specific extension to JUnit called DbUnit should be considered. DbUnit helps to manage test data sets by importing/exporting flat XML data sets to/from a database for each test or set of tests being executed.
Volunteer: Bruce Snyder
Status: not started
Date Started:
Notes:
Description:
Currently Castor JDO does not make any use of JDBC tx isolation levels
and this needs to be corrected.
Volunteer:
Status:
Date Started:
Notes:
This impacts Connection duration and needs to be investigated further.
Description:
The Castor OQL engine should be refactored to make us of a parser
generator like ANTLR or JavaCC.
This will make maintenance and adding features incredibly easier.
Volunteer: Paul Botta
Status: ANTLR implemenation complete
Date Started:
Notes:
Many thanks to Paul Botta for his hard work on the ANTLR implemenation.
Now this implementation just needs some tests to prove it so that it can
be committted it to CVS.
This layer should also be made pluggable allowing one or more query engines to plugged in simultaneously (e.g. OQL, XQuery, EJBQL, etc.). The tests.jdo.OqlTests class needs to be completed before this work can take place. This will provide a baseline before the removal of the current OQL engine.
Tranql may be used to achieve this task. As a side affect, Tranql may be also do a couple other jobs as well (e.g. caching and transaction context). There will also be a programmtic query API for this.
Description:
The SQLTypeConvertors inner class of SQLTypes should be refactored to
make it easier to plug in additional convertors.
Volunteer:
Status: not started
Date Started:
Notes:
Description:
Castor should include a mechanism for queries to be externalized in the
object mapping descriptor.
Volunteer:
Status: not started
Date Started:
Notes:
This would allow for named queries that do not require recompilation
for changes. These queries would be included automatically via the
Castor XML unmarshalling of the object mapping descriptor via the
<includes> element.
This may not be able to be accomplished at all with new programmtic query API.
Description:
The ClassMolder should be broken up into several classes to make use
of a dual strategy pattern.
Volunteer:
Status: not started
Date Started:
Notes:
The relationship type (e.g. one-to-one, one-to-many, many-to-many) is
the first strategy layer. The implementation type (e.g. interface,
abstract, concrete) is the second strategy layer.
Description:
In 2002 I started adding an API for a TransactionManagerFactory so that
Castor JDO can make use of a J2EE container's transaction manager
(e.g. JBoss, Weblogic, Websphere, etc.).
Volunteer: Werner Guttmann/Bruce Snyder
Status: completed
Date Started: Apr 2004
Notes:
Description:
Investigate whether the TransactionContext class can be replaced
through the use of ThreadLocal.
Volunteer: Bruce Snyder
Status: completed
Date Started: Apr 2004
Notes:
Description:
Castor's current cache implemenation is not very robust. It lacks any
procedure for manual object eviction and it should really be using
some sort of balanced tree (e.g. java.util.TreeMap) for reasons of
speed, etc., etc.
Note that Vince Adamo has posted a patch for object eviction in the current Castor API.
Volunteer:
Status: open
Date Started:
Notes:
There should really be a cache API. This would abstract the entire cache
engine allowing it to be made pluggable. In fact, I would much rather
consider using a JSR 107
implementation than writing our own API. Because this layer will be
pluggable, a distributed cache implementation should be provided using
JavaGroups.
Also, the dirty checking needs to be refactored so it's cleaner and
more straightforward in its duties.
Tranql may be used to achieve this task.
Description:
Handling of interfaces and abstract classes with regard to both object
mapping and queries.
Volunteer:
Status: not started
Date Started:
Notes:
Maybe this could be handled for the object mapping by using nested
<class> elements???
Interface idea - introduce the 'implements' attribute to the
<class> element:
]]>
Obviously an interface can be determined by using java.lang.Class#isInterfaces() and/or
java.lang.Class#isInterface().
]]>
The use of the 'extends' attribute for the abstract class is not
unique enough to determine that the class is abstract or concrete.
But by using java.lang.Class#isAssignableFrom() and/or
java.lang.Class#getSuperclass() will work.
Queries - objects should already be cast properly:
The above query would return all Products including
Computers, etc.
Another item that will need to be added is a mapping for interfaces and abstract classes. The <class> element could certainly be used for this possibly by introducing another attribute to the <class> element. I'm thinking about an attribute named 'abstract' that is simply a boolean whose default is false so that it won't affect concrete classes. Then it serves as a marker for interfaces and abstract classes only.
Not sure if this will really work. It will need experimentation to determine.
Description:
A database connection pooler should be integrated directly into
Castor. This would limit us to supporting JDBC 3.0
compliant drivers. Anything that's not JDBC 3.0 compliant would
still be supported via an implemention within the driver for a
pooled DataSource.
Volunteer:
Status: not started
Date Started:
Notes:
Here is a list of database connection poolers:
Description:
Research the possibility of creating a JCA Connector for Castor to
hook into application servers that support JCA.
Volunteer:
Status:
Date Started: not started
Notes:
Description:
This task covers two topics:
Volunteer:
Status:
Date Started: not started
Notes:
This is to increase awareness of Castor's use as well as Castor's
awareness of other projects.
Description:
Remove the requirement of all objects to explicitly implement the
Timestampable interface.
Volunteer:
Status:
Date Started:
Notes:
Currently Castor requires all objects involved in a long transaction
to implement the Timestampable
interface. This requirement can easily be removed via a dymanic proxy
implementation.
Description:
There are a few bugs that *must* be fixed, specifically
986,
925,
These bugs have been around for quite a while and should have been
fixed long ago.
Volunteer:
Status: not started
Date Started:
Notes:
Description:
This task surrounds the effort to continually improve the code
documentation including code examples, adding an @author tag
to any class you modify, etc. This task must be carried
out by everyone.
Volunteer:
Status: ongoing
Date Started:
Notes:
There's many users of Castor JDO out there, who (want to) use Castor JDO in in high-volume applications. To fine-tune Castor for such environment, it is necessary to understand many of the product features in detail and to be able to balance their use according to the application needs. Even though many of these features are detailed in various places, people have frequently been asking for a 'best practise' document, a document that brings together these technical topics (in one place) and presents them as a set of easy-to-use recipes.
Please be aware that this document is under construction, but still we believe that - even when in its conception phase - it provides valuable information to users of Castor JDO.
Let's start with some general suggestions that you should have a look at. Please don't feel upset if some are really primitive but there may be users reading this document that are not aware of them.
Switch to version 0.9.9 of Castor as we have fixed some 100+ bugs that may cause some of your problems.
Sidenote: Performance has, generally, improved recently. If you're not seeing performance improvements, then it's worth spending some time thinking about why.
Initialize your JDOManager instance once and reuse it all over your application. Don't reuse the Database instances. Creating them is inexpensive, and JDBC rules state that one thread <-> one JDBC connection is the rule. Do not multithread inside of a Database instance; as a corrolary, do not multithread on a single JDBC connection.
Use a Datasource instead of a Driver configuration as they enable connection pooling which gives you a great performance improvement.
We highly suggest DBCP, here, with the beneficial use of prepared statement caching.
Should you be running on a system where read performance is critical, feel free to take the SQL code generated by castor, and dumped to logs during the DB mapping load in debug output, and turn those into stored procedures that you then invoke via SQL CALL to perform those loads; however, I find personally that stored procedures would be a minimal improvement over the DBCP prepared statement cache; your mileage may vary. db.load() has performance benefits that are worth keeping, IMO, and the pleasure of having pretty stored procedures in your database is far outweighed by the nightmare of change management.
Have a look at the HTML docs for Jakarta DBCP, which has details about how to use and configure DBCP with Castor and Tomcat.
Note: 'prepared statement caches' refer to the fact that DBCP is a JDBC 3.0-compliant product, and as such has to support caching of prepared statements. This basically allows the JDBC driver to maintain a pool of prepared statements across all connections, a feature that has been added to the JDBC specification with release 3.0 only.
DBCP setup is generally outside of the scope of this list, but basically, here's my two cent description:
Hit the deploy button, and bob's your uncle.
Always commit or rollback your transactions and close your Database instances properly; also in fail situations.
Note:Just the obvious general rule on Java objects that hold resources: Don't wait for the VM to finalize to have something happen to your objects when you could have released critical resources at the appropriate point in the codebase.
Keep your transactions as short as possible. If you have an open transaction that holds a write lock on an object no other transaction can get a write lock on the same object which will lead to a LockNotGrantedException.
It doesn't make sense to make a own transaction for every change you want to do to an object as this will slow down your application. On the other hand if you have transactions with lots of objects involved taking an valuable amonth of time you may consider to split this transactions to reduce the time an object is locked.
Also keep in mind that folks using lockmode of DBLocked do FOR UPDATE calls on things they read while the transaction is open; if you're using dblocked mode, be aware of how your application does things. If you're in one of the other modes, locks happen inside castor, and it's your responsibility to always use the right access mode when accessing content.
If you can, for example, decide at the API layer whether or not an operation is going to ever need to modify an object, and know that you will only ever use an instance in read only mode, load objects with access mode read only, and not shared.
Limit use of read-write objects to situations in which it is likely you will need to perform updates.
Imagine, for a moment, that these transactions were in DBLocked mode - transactions which translate directly into locks on the database.
If you're opening something up for modification on the DB - marking it as select FOR UPDATE - then that row will be locked until you commit. The database would prevent any other transaction that wants to touch that row from doing anything to it, and it would block on your transaction - deadlock at the SQL level.
Castor does the same things internally for its own access modes - Shared and Exclusive. Each has different locking semantics; having good performance means understanding those locking semantics.
For example - read only transactions (should be) cheap. So there's no issue with holding those transactions open a long time; because they only translate, for an instant, into a lock. The lock is released the moment the load is completed and the object is dropped into read-only state within your transaction; read only operations therefore operate, pretty much, without locking.
The lock is of course acquired because you might also have it in SHARED or EXCLUSIVE mode on another thread - and that read-only operation isn't safe until those transactions close.
Once the lock is released, you're lock-free again, so the transaction basically has nothing in it that needs anything doing.
That's not to say that holding transactions open is good practice - but transactions should always be thought of as cheap to create and destroy and expensive to hold on to - never do heavy computation inside of one, unless you're willing to live with the consequences that arise from holding transactions on object sets that others might need to access.
Query or load your objects read only whenever possible. Even if castor creates a lock on them this does not prevent other threads from reading or writing them. Read only queries are also about 7 times faster compared with default shared mode.
for queries:
to load an object by its identity:
Default accessmode is evaluated as follows:
One cannot stress how important this is: If 99% of your application never writes an object, and you as a programmer know it won't, then do something about it. If you're in a situation where you want the object to be read-only most of the time, and only want a writable every now and then, do so just-in-time by performing a load-modify-store operation in a single transaction for the shareable you want.
In other words: Don't use read-write objects unless you know you're likely to want to write them.
If there is a possibility you should prefer Database.load(Class, object) over Query.execute(String). I suggest that as load() first tries to load the requested object from cache and only retrieves it from database when it is not available there. When executing queries with Query.execute() the object will always be loaded from database without looking at the cache. You may gain a improvement by a factor of 10 and more when changing from Query.execute() to Database.load().
We hope above suggestions help you to resolve the problems you have. If you still need more performance there are areas of improvement that are more difficult to resolve. For further ideas to improve your applications performance you should take a loock at out performance test suite (PTF) which you can find in Castor's source distribution under: src/tests/ptf/jdo.
Now, there's lots left to do - there is still the issue, for example, of dependent objects being slightly sub-optimal in performance both in terms of the SQL that gets generated and the way it gets managed - but there will be improvements over time to the way that this and other operations are performed.
But performance should be good right now. If it isn't, you'll need to think about whether you are using the optimal set of operations. No environment can predict your requirements - hinting to the system when objects can be safely assumed to be read-only is vital to a high-performance implementation.
Castor JDO is an Object-Relational Mapping and Data-Binding Framework, which is written in 100% pure Java[tm]. Castor can map relational database data into Java Data Object based on user-defined mapping schema. In the other point-of-view, it provides java data objects a persistence layer.
It frees programmer from dealing with database directly and replacing the entire burden of composing updating the database. Proper SQL statements are automatically generated for loading, updating, creating and deleting. Changes to objects in transaction are automatically done to data source at commit time. Thus programmer can stay in pure-Java without remember all the details in the backing database, after the creation of database tables and the mapping schema. The separation of persistence and programming logic also enable much clearer object-oriented design, which is important in larger projects.
JDO is transactional. Data objects loaded in Castor are properly locked and isolated from other transactions. Castor supports full 2-phase commit via xa.Synchronzation. Castor supports several locking modes, including "shared", "exclusive", "database locked", and "read-only".
In addition, Castor supports "long transactions", whichs allow objects to be read in one transaction, modified, and then committed in a second transaction, with built-in dirty-checking to prevent data that has been changed since the initial transaction from being overwritten.
Through automatic dirty-checking and deadlock detection, Castor can be used to ensure data integrity and reduce unnecessary database updates.
A subset of OQL, defined in the Object Management Group (OMG) 3.0 Object Query Language Specification, is supported for interacting with the database. OQL is similar to SQL, though operations are performed directly on Java objects instead of database tables, making the language more appropriate for use within a Java-based application.
Castor implements a data cache to reduce database accesses, providing several alternative LRU-based caching strategies.
Castor supports different cardinalities of relationship, including one-to-one, one-to-many and many-to-many. It also supports both object and database record inheritance. It distinguishes between related (i.e. association) and dependent (i.e. aggregation) relationships during an object's life cycle, automatically creating and deleting dependent objects at appropriate times in the independent object's life cycle.
Multiple-column primary keys, and a variety of key generators are supported.
Castor automatically manages persistence for objects that contain Java collection types, including Vector, Hashtable, Collection, Set, and Map. Lazy loading (of collections as well as simple 1:1 relations) is implemented to reduce unnecessary database loading. Lazy loading can be turned on or off for each individual field (of any supported collection type for 1-to-many and many-to-many relations).
Other features include a type converter for all Java primitive types (see the info on supportedtypes).
No pre-processor (aka pre-compiler), class enhancer (bytecodes modification) is needed or used for data-binding and object persistence.
Castor JDO works in an application that uses multiple ClassLoaders, making it possible to use in an EJB container or servlet, for example. A Castor-defined callback interface, "Persistent", can be implemented if the objects wants to be notified on Castor events: jdoLoad(), jdoCreate(), jdoRemove() and jdoTransient(). This makes it possible to create user-defined actions to take at various times in an object's life cycle.
The Java-XML Data-Binding Framework (Castor XML) has been merged with Castor JDO for users who need both O/R Mapping and Java-XML Data-Binding together.
The following relational databases are supported:
Database support includes Oracle 8.1.x and different versions of Sybase Enterprise and Anywhere. Users can implement the Driver interface to adapt Castor to the differences in SQL syntax supported by different relational DBMS's, as long as the DBMS supports JDBC 2.0, multiple ResultSet, and transactions. Thanks to many individual open source contributors, drivers for different database are available.
The usual Castor transactions are called here short
transactions: an object is read, modified and written within the
bounds of one transaction.
Long transactions consist of two Castor transactions:
an object is read in the first and written in the second.
Between them the object is sent "outwards" and modified there.
For example, the object may be send to a client application and
dispayed to a user, or it may be sent to a servlet engine and is
displayed on a web page. After that the modified object returns
back and is written to the database in the second transaction.
At this point the object is usually not the same physical instance
as one that was read in the first transaction.
The example code for writing the object in the second Castor
transaction follows:
Note, that it is natural to read the object in the first
transaction in the read-only mode.
Since the time interval between the first and the second
transaction is relatively big, it is desirable to perform dirty
checking, i.e. to check that the object has not been modified
in the database during the long transaction.
For that the object must hold a timestamp: it is set by
Castor during the first Castor transaction and is checked during
the second one.
In order to enable the dirty checking for long transactions,
the object should implement the interface
org.exolab.castor.jdo.TimeStampable
having two methods: long jdoGetTimeStamp() and
void jdoSetTimeStamp(long timeStamp)
The advantage of the bounded dirty checking is that it doesn't require any changes to the database schema. It uses the Castor cache to store object timestamps. The disadvantage of this algorithm is that it is bounded by a lifetime of the cached copy of the object. After the cached copy has been purged, db.update() causes ObjectModifiedException.
Thus, parameters of the cache define dirty checking capabilities. The cache-type attribute is part of the <class> element in the XML mapping. Consider the existing cache types:
For long transactions (detached objects) it was required that the entity has been kept in cache from being loaded until its update. If the entity was expired from cache before the update an ObjectModifiedException had been thrown. While this is no problem if all entities of an application can be kept in cache all the time, it is one for large scale applications with millions of entities.
With release 1.3 we have changed the handling of timestamps. While it is still possible to rely on cache only it is now also possible to persist the timestamp together with the other properties of the entity. Doing so will ensure that the timestamp do not change even if the entity got expired from cache from being loaded until it gets updated. If this happens the entity gets reloaded during update which also loads the previous timestamp. Having said that it still is possible that an ObjectModifiedException is thrown when another user has changed the same entity in the meantime.
See an example entity and its mapping below:
To be defined ...
Before using the
Before using the
As already explained, Castor is an
open-source product. This means that the source code is available at
no charge and may be obtained using SVN or
downloaded via
Due to the nature of the project, there is no guaranteed level of support (of commercial quality) offered by the project and its community. As outlined here, the online documentation is the best place to start.
Having said that, it is noteworthy to mention that there's plenty of companies out there that offer ...
This page provides you with various reference points, addressing most of the above areas.
We hope that the information provided is of value to you, our customers, and we are more than happy to discuss any suggestions/recommendations related to this offering.
This section identifies various (mainly) open source projects where Castor is used and/or that offer tight integration with Castor or parts thereof.
Apache Cocoon is a web publishing framework built around the concepts of separation of concerns and component-based web development.
As part of this framework, Cocoon provides a component, the CastorTransformer, that marshalls an object hierarchy (for which a mapping file or a class descriptor hierarchy exists) to XML and inserts it as a stream of SAX events into a Cocoon pipeline.
Further information on the integration of Apache Cocoon and Castor can be found here.
Please find information about professional services related to Castor, as well as a registry of individuals/companies and their offerings in this area here.
In order to understand how the JDO transaction model affects applications performance and transactional integrity, you must first understand the semantics of the Java Data Objects. Java Data Objects are objects loaded from and stored to the database, but are disassociated from the database itself. That is, once an object has been loaded into memory, changes to the object in memory are not reflect in the database until the transaction commits.
The following table shows a sample code and the state of the JDO object and the relevant database field:
| Code | Object value | Record value |
| results = oql.execute(); | N/A | X |
| obj = results.next(); | X | X |
| obj.setValue( Y ); | Y | X |
| db.commit(); | Y | Y |
Concurrency conflicts do not occur when an object is changed in memory, but rather when the transaction commits and changes are saved back to the database. No changes are saved if the transaction rolls back.
Conflicts could occur if two threads attempted to modify the same object, or the same thread recieves two objects associated with the same database record and performs different changes to each object. Castor solves these issues through a transaction-object-identity association.
When the same transaction attempts to query the same database record twice, (e.g. as the result of two different queries) the same object is returned, assuring that different changes will be sychronized through the same object.
When two transactions attempt to query the same database record, each transaction recieves a different object mapping to the same record, assuring that changes done in one transaction are not visible to the other transactions. Changes should only become visible when the transaction commits and all its changes are made durable.
This approach places the responsibility of synchronization and deadlock detection on the Castor persistence engine, easing the life of the developer.
Concurrent access requires use of locking to synchronize two transactions attempting to work with the same object. The locking mechanism has to take into account several possible use of objects, as well as help minimize database access through caching and is-modified checking.
Locking modes are declared in the class element of the XML mapping on a per class basis.
The shared mode is the default for all objects, unless otherwise specified in the mapping file. Shared mode allows two transactions to read the same record at the same time. Each transaction will get it's own view of the record as a separate object, to prevent in-memory changes from conflicting with each other. However, the values loaded from the database are the same for both transactions.
When transactions query different objects or query the same objects but for read-only purposes, shared access provides the most efficient means of access in terms of performance, utilizing record caching and eliminating lock contention. For example, when each transaction retrieves a different Customer record and all transactions retrieved the same set of Department records but hardly ever change them, both Customer and Department should be declared as having a shared lock.
However, when two transactions attempt to access the same object, modify it, and commit the changes, a concurrency conflict will occur. Some concurrency conflicts can lead to one of the transactions aborting. For example, if two transactions happen to load the same Account object with a balance of X, one adds 50 and the other adds 60, if both were allowed to commit the changes the new account balance will be either X+50 or X+60, but not X+110.
In the above case either exclusive or db-locked modes should be used to reduce potential conflicts. However exclusive and db-locked modes may cause the application to perform slower due to lock contention and should not be used as the general case. In rare cases conflicts may occur where shared locks are the preferred choice, e.g. when two transactions attempt to modify the same Department object, or somehow get hold of the same Customer records.
Castor detects such conflicts as they occur and uses two mechanisms to deal with them: write locks and deadlock detection. When a transaction commits Castor first tries to determine whether the object has been modified from it's known state (i.e. during query). If the object has not been modified, Castor will not attempt to store the object to the database. If the object has been modified, Castor acquires a write lock on the object preventing other transactions from accessing the object until the current transaction completes storing all changes to the database. A write lock prevents other transactions from acquiring either a write or read lock, preventing them from accidentally loading a dirty image of the object.
If the second transaction has a read lock on the object, the current transaction will block until the second transaction releases the lock, either by rolling back or by not modifying its object. If the other transaction modifies the object and attempts to store it, a deadlock occurs. If both transactions have a read lock, both require a write lock in order to proceed and neither can proceed until the other terminates.
Castor detects such deadlock occurences and causes the second transaction to rollback, allowing the first transaction to commit properly. Such conflicts do not happen often, but when they happen some transactions will fail. The application developer should either be aware of the possibility of failing, or choose to use a more severe lock type.
Conflicts occur not just from other Castor transactions, but also from direct database access. Consider another application modifying the exact same record through direct JDBC access, or a remote server connecting to the same database. To detect such conflicts Castor uses a dirty checking mechanism.
When an object is about to be stored, Castor compares the current values in the database records with those known when the object was originally loaded from the database. Any changes are regarded as dirty fields and cause the transaction to rollback with the proper error message.
Not all fields are necessarily sensitive to dirty checking. The balance in a bank account is a sensitive field, but the date of the last transaction might not be. Since the date does not depend on the original value of the account, but on the last modification to it, dirty checking can be avoided.
A field marked with dirty="ignore" will not take part in dirty checking. Furthermore, modifications to such a field will not require a write lock on the object, further improving throughput. Marking fields as non-dirty should be done with extreme care.
The exclusive mode assures that no two transactions can use the same record at the same time. Exclusive mode works by acquiring a write lock in memory and synchronizing transactions through a lock mechanism with configured timeout.
Using in-memory locks, exclusive access provides some transaction synchronization that is efficient in terms of performance and increases the chance of a commit being successful. It does not, however, guarantee commit. Since the lock is acquired by Castor, it can be used to synchronize Castor access, but other forms of direct database access may still modify the database record.
When a transaction obtains an object that was specified as exclusive access in the mapping file or when performing a query, Castor will always obtain a write lock on that object. The write lock will prevent a second transaction from being able to access the object either for read or write, until the current transaction commits. If the object is already being accessed by another transaction, the current transaction will block until the other transaction commits and release the lock.
It is possible to upgrade from a shared to an exclusive lock by calling the
Because direct database access can modify the same record as represented by an exclusive locked object, Castor uses dirty checking when updating the database. Dirty checking does not have a severe affect on performance, and can be disabled by marking all the fields of the object with dirty="ignore".
To reduce the possibility of dirty reads, Castor will always synchronize exclusive locked objects with the database at the beginning of a transaction. That is, when an object is loaded the first time in a transaction with an exclusive lock, Castor will retrieve a fresh copy of the object from the database. Castor will not, however, refresh the object if the lock is upgraded in the middle of a transaction using the lock method.
Exclusive mode does cause lock contention and can have an affect on application performance when multiple transactions attempt to access the same record. However, when used smartly with on a small set of objects it can help reduce the possibility of concurrency conflicts. It can also be used to force an object to be loaded from the database and the cache refreshed.
The locked mode performs optimistic locking using the underlying database engine to assure that only one transaction has access to the record. In addition to acquiring a write lock in memory, Castor performs a query with a special SQL construct (FOR UPDATE in Oracle, HOLDLOCK in Sybase) to guarantee access by one transaction.
In the event that the same database record will be accessed directly through JDBC, stored procedure, or a second machine using Castor, the only way to achieve object locking is through the database layer. However, such write locks should be cooperative, that is, other forms of database access should attempt to use the same locking mechanism.
In some isolation levels, when Castor acquires a write lock on the database it will prevent other applications from accessing the same record until the Castor transaction commits. However, certain isolation levels allow other applications to obtain a dirty image of the record.
Write locks on the database have a severe impact on application performance. They incur overhead in the database manager, and increase lock contention. It is recommended to use database locks with care, pay extra attention to the isolation level being used, and follow good practices recommended by the database vendor with regards to such locks.
In the future long transaction will be supported. Long transactions rely on the dirty checking mechanism and only hold connections open for as long as they are required for queries. Long transactions cannot be used with database locking.
Locked mode must be specified for the object in the mapping file or when conducting the query. It is not possible to upgrade to a locked lock in the middle of a transaction.
Objects loaded in this mode are always synchronized with the database, that is, they will never be obtained from the cache and always re-loaded for each new transaction.
When a query is performed in read-only mode or no mode is specified and the object is marked as read-only in the database, Castor will return a transient object. The returned object will not be locked and will not participate in the transaction commit/rollback.
When the same object is queried twice in a transaction as read-only, Castor will return two separate objects, allowing the caller to modify one object without altering the other. Castor will utilize the cache and only perform one load from the database to the cache.
Read-only access is recommended only when the object is intentionally queried as read-only and changes to the object should not be reflected in the database. If the object will not be modified, or modifications will be stored in the database, it is recommended to use the shared mode. Shared mode allows the same object to be returned twice in the same transaction.
The visibility of changes occuring in one transaction to other transactions depends upon the transaction isolation level specified for the database connection. Whether or not the changes are visible in the current transaction depends upon the operation being done.
There are four types of changes, the following table summarizes the affect of each change in one transaction on other queries in that transaction as well as other transactions.
| Type of change | Same transaction | Other transaction |
| Create new object | New object is visible and will be returned from a query | New object might be visible, depending on isolation level, but access is blocked until the first transaction completes |
| Delete existing object | Object is no longer visible and will not be returned from a query | Object might not be visible, depending on isolation level, but access is blocked until the first transaction completes |
| setXXX() | Change is visible in object itself | Change is not visible, object is accessible depending on lock |
| update() | Change is visible in object itself | Change might be visible, depending on isolation level, object might be accessible depending on lock |
API Reference:
Castor DDL Generator creates a SQL script to drop/create tables, unique keys, sequences and so on from a Castor JDO mapping file.
This will generate the SQL script mapping.sql in the same directory mapping.xml is located.
The DDL Generator has a number of different options which may be set. Some of them are specified at the command line while others need to be configured through a properties file. Most of the options are located in global properties file org/castor/ddlgen/ddlgen.properties but there are also some options that are specific for one database engine. The specific properties can be found at org/castor/ddlgen/engine/<database>/<database>.properties.
The DDL Generator supports generation of SQL scripts for the following database engines:
Castor is an open-source product. This means that the source code is available at no charge and may be obtained using SVN or may be downloaded via the Codehaus distribution server.
Since castor is freely available, including the source code, there is no guaranteed level of support available. The online documentation is the best place to start. If you have trouble or have more advanced questions not available in the online documentation, then please consider subscribing to one of the various available mailing lists. In general, the lists are the best place to ask questions about the product.
We moved to The Codehaus in January 2005, and we greatly benefit from the infrastructure available at this site. Due to this, we are in a position to offer you additional communication channels:
Please note, though, that for problems of any kind, you should still use one of the mailing list as your preferred way of communicating to us, as this enables other users to browse through old email at one of the available mailing list archives.
The online documentation is available throughout the website. To get started simply click on the appropriate sections listed in the menu bar located to the left side of this page.
If you can't find something in the documentation, try looking through the examples (as shipped as part of the source distribution).
There are also numerous presentations and articles available about Castor to help get you started.
If you find a bug, please file a report at Codehaus' issue management
system (JIRA), available at
Before submitting bugs or asking for features to be added/implemented, please read the Bugzilla Etiguette and Bug Writing Guidelines from Mozilla.org. as a general introduction to submitting such requests.
Commercial support is not provided through this project at this time. Having said that, please note that there are a growing number of third party individuals/companies providing such support, as detailed here.
Reference:
As explained at the introduction to Castor JDO, Castor has support for many advanced features such as caching, depend relations, inheritance, polymorphism, etc. The below sections detail these features, as their understanding is required to use Castor JDO in a performant and secure way.
All information related to caching and related concepts supported by Castor has been consolidated into one place, and is available here.
Castor distinguishes the relationship of two objects as dependent or related, and maintains the life cycle independently for the two types of relationships. Starting from Castor 0.9, the developer can explicitly define a dependent relationship in the mapping file.
When using independent relations, related objects life cycle is independent of each other, meaning that they have to be created, removed and updated (for long transaction) independently.
When using dependent relations, one data object class must be declared as depends on one other data object class in the mapping file, and such an object is called a dependent data object class. A data object class without depends declared in the mapping is called a master object. A master object can be depended upon by zero or more dependent data object class.
As of Castor 0.9, a dependent object class can be related to other master data object classes including extended classes, but cannot depend on more than one master class.
If an object class declared as depends on another class, it may not be created, removed or updated separately. Attempting to create, remove or update a dependent object will result in ObjectNotPersistcapableException. Note that Castor doesn't allow a dependent object instance to change its master object instance during a transaction. Each dependent object can have only one master object. Both dependent and master objects must have identities, and may or may not make use of key-generators.
Here is the DTD for declaring dependent object:
For example,
Castor supports different cardinalities of relationship, namely one-to-one, one-to-many, and many-to-many. Many-to-many relationship must be related rather than dependent, because each dependent object can have only one master object.
Many-to-many requires a separate table for storing the relations between two types of objects. Many-to-many introduces two attributes, namely many-key and many-table that reside in the <sql> element which is a sub-element of the <field> element. For all many-to-many relations, a many-table must be specified. If the column name of the primary key of the class is different from the foreign keys columns of the class in the relation tables, then the relation table columns can be specified using the many-key attributes. Similarly, if the column name of the primary key of the related class is different from the foreign key columns of the related class, then the relation table columns can be specified using the name attribute.
The many-table is used to store relations in a separate table
So, for example, if the SQL table is the following,
| id | name | salary |
| 1482 | Smith, Bob | $123,456 |
| 628 | Lee, John | $43,210 |
| 1926 | Arnold, Pascal | $24,680 |
| id | name | comment |
| 3 | Accounting | |
| 7 | Engineering | The very important department. :-) |
| e_id | d_id |
| .... | .... |
Then, the mapping for employee data object would look like this
As of release 0.9.6, Castor has full support for lazy loading object instances referenced as part of all relation types currently supported:
As of release 0.9.6, Castor supports lazy-loading of 1:1 relations. Imagine the following class mapping:
Per definition, when an instance of Department is loaded through e.g. Database.load(), Castor will not (pre-)load the Employee instance referenced (as such reducing the size pf the initial query as well as the size of the result set returned). Only when the Emplyoee instance is accessed through Department.getEmployee(), Castor will load the actual object into memory from the persistence store.
This means that if the Employee instance is not accessed at all, not only will the initial query to load the Department object have had its complexity reduced, but no performance penalty will be incurred for the additional access to the persistence store either.
The elements in the collection are only loaded when the application asks for the object from the collection, using, for example, iterator.next(). The iterator in Castors lazy collection is optimized to return a loaded object first.
In the mapping file, lazy loading is specified in the element of the collections <field>, for example,
declares that the collection of type Employee in a Department is lazy loaded.
If lazy loading is specified for a field of a class, Castor will set the field with a special collection which contains only the identities of the objects. Because of that, it requires the data object to have the method setDepartment( Collection department) in the data object class which was not required in previous versions.
The support of multiple column primary keys (also called compound primary keys) was another major enhancement added into Castor 0.9. Specifying multiple column primary keys is simple and straightforward, in the mapping file,
Multiple column primary keys work with both master and dependent objects, all cardinalities of relationship, including one-to-one, one-to-many and many-to-many, as well as lazy loading.
However, multiple column primary keys should only be used to adhere to an existing database design, not when designing a new database. In general, it is not a good idea to use an identity or identities which can be modified by the user, or which contain application-visible data. For example, if the system allows the user name to be changed, using user name as identity is highly discouraged, as this practice can require a major data migration to a new schema to update all foreign keys to adhere to a new primary key structure, should the user name no longer be adequate as a primary key. It should be noted that Castor doesnt support identity change, as specified in the ODMG 3.0 specification. So, primary keys changes are almost certainly a large trade off between data integrity and performance. Well chosen primary keys are usually single (not multiple) column numeric or character fields for the reasons outlined above, as well as performance, as joining operations are faster for single column primary keys.
For the various persistence operations as available through the
Once your entity class implements the
Castor JDO allows for two simple ways of specifying its required configuration, e.g.
by the means of supplying Castor JDO with an XML-based configuration file, and by
specifying its configuration programmatically via the
The default way to configure how Castor interacts with a specific database system is by using a configuration file. It specifies the means to obtain a connection to the database server, the mapping between Java classes and tables in that database server, and the service provider to use for talking to that server (For a more flexible, programmatic way without configuration files see section JDOConfFactory).
The application will access the database(s) by its given name (database/name) and will be able to persist all objects specified in the included mapping file(s).
The engine attribute specifies the persistence engine for this database server. Different database servers vary in the SQL syntax and capabilites they support, and this attribute names the service provider to use.
The following names are supported in Castor:
|
Note: Castor doesn't work with JDBC-ODBC bridge from Sun. In particular, MS Access is not supported.
The means to acquire a database connection is specified in one of three ways: as a JDBC driver URL, as a JDBC DataSource, or as a DataSource to lookup through JNDI. When Castor is used inside a J2EE application server it is recommended to use JNDI lookup (see the jndi element), allowing the application server to manage connection pooling and distributed transactions.
The class mapping is included from an external mapping file, allowing multiple mappings to be included in the same database configuration, or two databases to share the same mappings. For concurrency and integrity reasons, two database configurations should never attempt to use overlapping mappings. It is recommended to use one database configuration per database server.
The mapping file is specified using a URL, typically a file: URL. If the database configuration file and mapping file reside in the same directory, use a relative URL. Relative URLs also work if the database configuration and mapping files are obtained from the application JAR and reside in the same classpath.
The driver element specifies the JDBC driver for obtaining new connections to the database server. The driver is obtained from the JDBC DriverManager and must be located in the class path. The JDBC URL locates the driver and provides the access properties. Additional properties may be specified using param elements (e.g. buffer size, network protocol, etc).
Use the class-name attribute to specify the driver class for automatic registration with the JDBC DriverManager. If missing, the driver must be registered in any other means, including properties file, Class.forName(), etc.
For example, to configure an Oracle 8 thin driver, use:
The data-source element specifies the JDBC DataSource for obtaining new connections to the database server. DataSources are defined in the JDBC 2.0 standard extension API which is included with Castor, and implement the interface javax.sql.DataSource.
The DataSource implementation class name is specified by the class-name attribute and configured through Bean-like accessor methods specified for the param element. The DTD for the param element is undefined and depends on the DataSource being used.
For example, to configure a PostgreSQL 7.1 DataSource, use:
The jndi element specifies the JDBC DataSource for obtaining new connections to the database server through a JNDI lookup. The JNDI environment naming context (ENC) is used to obtain a suitable DataSource..
When running inside a J2EE application server, this is the preferred method for obtaining database connections. It enables the J2EE application server to configure the connection, maintain a connection pool, and manage distributed transactions.
For example, to specify a J2EE DataSource, use:
As opposed to release pre 0.9.6, transaction demarcation is now configured in the JDO configuration file. As such, the user has to specify which transaction demarcation to use. Transactions when used with Castor JDO can either be local or global, and you instruct Castor to use a specific mode by supplying a <transaction-demarcation> element.
When using Castor JDO stand-alone and you want Castor to control transaction demarcation, please use the <transaction-demarcation> element as follows:
When running inside a J2EE application server, and you want to use global (XA) transactions, please make use the <transaction-demarcation> element as follows:
In this mode, the <transaction-manager> element specifies the transaction manager that is used by your J2EE container to control these transactions.
The following transaction managers are supported in Castor:
In addition to specifying the transaction manager name, it is possible to pass arbitrary name/value pairs to the transaction manager instance.
Note: At the moment, only the JNDI transaction manager factory supports such an attribute. In this context, the jndiEnc attribute can be used to specify what JNDI ENC to use to lookup the transaction manager as shown below:
The following configuration file instructs Castor JDO to execute against an Oracle RDBMS using the thin (type 4) JDBC driver, and refers to three mapping files that define mappings for product, order and customer related data.
The following configuration file uses a connection obtained from the
J2EE application server and a single mapping file:
Castor JDO uses JDBC prepared statements to execute SQL statements against the specified RDBMS of your choice. Per definition, Castor JDO does not provide any prepared statement pooling. As such, Castor relies on prepared statement pooling being provided by different means.
One such way is to use Jakarta's Commons DBCP as database connection pool, and to turn prepared statement pooling on by configuring DBCP accordingly.
Please check with Using Pooled Database Connections for general information about hot to use DBCP with Castor.
Besides the examples listed above, more configuraton examples can be found in the configuration files for the Castor JDO tests, which can be found in src/tests/jdo once you have downloaded and expanded the Castor source package. For each database (vendor) supported, you are going to find a database-specific JDO configuration file in this directory, e.g. src/tests/jdo/mysql.xml for mySQL or src/tests/jdo/oracle.xml for Oracle.
Many applications need to connect to a database using varying
user accounts or database instances. To accomplish this, the utility
class
The following code snippet shows an example how to create a JDO configuration without the use of a default XML-based database configuration file:
As an alternative to using a org.exolab.castor.jdo.conf.Driver, you can also configure Castor to use a JDBC 2.0 DataSource:
For validation, the configuration file should include the following
document type definition. For DTD validation use:
The Castor JDO database configuration DTD is:
| Castor Namespace | http://castor.org |
| Mapping DTD |
-//EXOLAB/Castor Object Mapping DTD Version 1.0//EN http://castor.org/mapping.dtd |
| Mapping XML Schema |
-//EXOLAB/Castor Object Mapping Schema Version 1.0//EN http://castor.org/mapping.xsd |
| JDO Configuration DTD |
-//EXOLAB/Castor JDO Configuration DTD Version 1.0//EN http://castor.org/jdo-conf.dtd |
| JDO Configuration Schema |
-//EXOLAB/Castor JDO Configuration Schema Version 1.0//EN http://castor.org/jdo-conf.xsd |
| SourceGenerator Binding file Namespace | http://castor.org/SourceGenerator/Binding |
| Source Generator Binding File |
-//EXOLAB/Castor Binding Schema Version 1.0//EN http://castor.org/binding.xsd |
| DSML Namespace | http://www.dsml.org/DSML |
| DSML DTD and Schema |
dsml.dtd
dsml.xsd dsml-import.dtd dsml-search.dtd |
An alternative to using the command line as shown in the previous section, the Castor DDL Generator Ant Task can be used to call the DDL generator for class generation. The only requirement is that the castor-<version>-anttasks.jar must be on the CLASSPATH.
Please find below the complete list of parameters that can be set on the Castor source generator.
Alternatively to specifying the file property, it is possible to work with a nested <FileSet> element or with the dir property.
Below is an example of how to use this task from within an Ant target definition named 'castor:ddl:src':
Please note that the complete documentation for XML marshalling and unmarshalling has been moved to the new reference guide.
In order to run the examples located in src/examples, there are a number of steps that must first take place. These steps are outlined below:
The script files example.sh and example.bat can be used to run the provided examples. The first argument is the example package name. For example, to build and run the JDO example:
build.sh examples example.sh jdo
The JDO sample will test persistence between a set of Java classes (Product, ProductGroup, ProductDetail) and a known SQL schema. You can use the create.sql file to generate the database schema for the purpose of this test.
The mapping between the Java objects and SQL schema is described in the file mapping.xml. The JDBC connection to use is described in the file database.xml. The provided file uses PostgreSQL as the database server and JDBC driver. You can modify this file for your database server and use any JDBC 1.0 or 2.0 driver.
The database information and mapping are automatically read from the JDO example directory. There is no need to provide any parameters on the command line.
The performance test uses the ODMG engine as well as direct JDBC access. You must provide the JDBC URI and class name to use for this test on the command line.
Usage:
example.sh jdo
Do not run this sample against a production LDAP server unless you are sure it will not affect the information in your directory!
The DSML sample will attempt to import the supplied directory information from the test.xml file using the import policy described in the import.xml. file. It will then run a search against the LDAP server using the search criteria in the search.xml file and dump it to the console.
You must modify search.xml, import.xml and test.xml and adapt them to your LDAP directory structure. The default files assumes the root directory dc=intalio,dc=com and includes some sample LDAP entries.
Usage:
jndi|mozilla Selects whether to use the JNDI or Mozilla Directory
SDK implementations
host The LDAP host name (port number is optional)
rood-dn The root DN used for authenticating when importing
root-pwd The root password used for authenticating when importing
]]>
For example:
example.sh dsml mozilla ldap.intalio.com dc=intalio,dc=com secret
This section provides a place to link external examples of using Castor. If you have an example that you feel would be useful, please send us the URL. Also notify us if any links are broken.
Goran Zugic and Duka Krunic of ebXMLsoft Inc. have some samples using Castor XML and Castor JDO. The examples use Castor 0.9.2 and offer good insight in using XML and JDO together.
This document describes the advantages of using Castor with JBoss, an overview of the JBoss MBean approach and directions on configuring JBoss to use Castor JDO. The advantage of using Castor JDO within JBoss is that you have access to key J2EE features such as JNDI, JDBC datasources and transaction management (JTA). Although it is possible in principle to achieve this with other commercial J2EE servers, a ready-to-use plug-in is available to integrate Castor JDO within JBoss.
Once integrated, Castor JDO can be used with session beans and BMP entity beans as an alternative to CMP entity beans and in many cases is faster and more efficient. An example of using Castor JDO with a stateless session bean has been created and is available here. This is a demonstration of the transient entity design pattern, described here.
Castor JDO is integrated with JBoss through the JMX server environment provided by JBoss. The plug-in consists of a JMX MBean or managed bean that implements the Castor DataObjects interface by wrapping a JDO object. The MBean accomplishes the following tasks at the startup of JBoss 3.x:
There are two jars needed to use Castor JDO with JBoss:
Note: Xerces is required also, but is distributed with JBoss 3.2.1.This section details the steps required to integrate Castor JDO with JBoss 3.x. In brief, these are:
Installing JBoss 3.x is outside of the scope of this discussion and is adequately covered by the JBoss documentation. Once JBoss is installed it is necessary to copy the two other dependencies (Castor and the Castor plugin) to the lib directory of the JBoss server instance you wish to install Castor for. The following path assumes you wish to install Castor on the "default" server: (JBOSS_HOME/server/default/lib).
It is desirable to use Castor with a javax.sql.Datasource as this will
allow you to use connection pooling and distributed transactions, assuming
your driver supports these. Datasources are configured by placing a config
file ending in -ds.xml in the deploy directory of the server
instance you wish to use. For example, to configure a Microsoft SQL Server
XADatasource for the default server using the InetSoft Opta 2000 driver
you would place a file with the information below in the JBOSS_HOME/server/default/deploy
directory:
Copy your database.xml and mapping.xml to the configuration directory for your JBoss server instance: for example, JBOSS_HOME/server/default/conf.
Your database.xml should reference the datasource you created in the
previous step. For the datasource above:
Note that if you are not using Microsoft SQL Server, you should not use
the sql-server engine - consult the Castor documents
here to find out
what engine you should use for your RDBMS.
The JBoss MBean server looks for MBean configuration files in the deploy directory of a server instance: JBOSS_HOME/server/default/deploy. These files will end in -service.xml. The MBean parses the xml file, creates the MBean instance and uses introspection to set properties on the MBean based on the attributes in the configuration.
To configure the JBoss MBean, place a file called castor-jdo-service.xml
in JBOSS_HOME/server/default/deploy with the following contents:
Note the following features of the configuration:
To test your configuration, try and start the JBoss server instance you are
attempting to configure. Watch the console carefully for any stacktraces
or other error messages. With any luck, at some stage you should see something
like:
11:12:59,025 INFO [MainDeployer] Starting deployment of package: file:/C:/jboss
/server/default/deploy/castor-jdo-service.xml
11:12:59,181 INFO [CastorJDOImpl] Creating
11:12:59,196 INFO [CastorJDOImpl] Created
11:12:59,212 INFO [CastorJDOImpl] Starting
11:13:00,759 INFO [CastorJDOImpl] Started
Go to the JMX Console (http://localhost:8080/jmx-console) of your
JBoss machine. You should see the following link under the jboss
entry:
name=MyAppJDO,service=CastorJDO
Click on the link to see the status of the service. It should be started.
You can also check the status of your datasource by looking for it under the jca entry in the console.
To do:
Check the JDO FAQ here for common questions regarding JDO usage.
The Castor project has been developed out of need: the need to get stuff done and the need to write useful code. It has been designed and coded over many cups of Dunkin Donut's Hazlenut coffee, Starbucks' Latte, and tall no-whip White Mochas, as proof that coffee beans do come in handy. A few rogue contributors prefer the sweetness of Coca Cola to the bitterness of coffee.
We maintain a full list of contributors past and present.
The Castor Project was started and originally developed by Keith Visco and Assaf Arkin of Intalio, Inc. Contributors are welcome to join this project. Please join us on the mailing list.
Castor makes use of and includes several third-party software components such as Xerces, Jakarta ORO, and Jakarta Regexp, all developed by the Apache Software Foundation. Castor also makes use of and includes the JUnit testing framework, which is only used in the build and testing components.
The Castor type mechanism assures proper conversion between Java types and external types.
Castor XML converts all Java fields into XML element and attribute values.
Castor JDO converts Java fields into SQL columns which are persisted through the JDBC driver. Due to implementation details, the field type expected by the JDBC driver is not always the field type defined for the mapped object.
The most common occurrences of mistyping is when using fields of type FLOAT, DOUBLE, NUMERIC, and DECIMAL. SQL type FLOAT actually maps to Java type java.lang.Double. SQL types NUMERIC and DECIMAL map to Java type java.math.BigDecimal.
When such an inconsistency occurs, Castor JDO will throw an IllegalArgumentException during object persistence with a message indicating the two conflicting types.
In order to avoid runtime exceptions, we recommend explicitly specifying types in the mapping file using the SQL typing convention. See SQL Type Conversion.
Castor DAX converts all Java fields into LDAP attribute values. LDAP attribute values are always textual and are represented as the string value of the field, e.g. "5" or "true".
LDAP attributes may also contain binary values. When storing byte arrays or serialized Java objects, DAX will store them as byte arrays.
The field element includes an optional attribute called type which can be used to specify the Java type of the field. This attribute is optional since Castor can always derive the exact Java type from the class definition.
We highly recommend that developers use the type field in their mapping file as a means to provide static type checking. When loading a mapping file, Castor will compare the actual Java type with the type specified in the mapping and will complain about inconsistencies.
The field type can be specified either given the full class name (e.g. java.lang.Integer) or using a short name. The following table lists all the acceptable short names and the Java types they represent:
|
In addition, support for the following Castor-internal field types has been added:
|
Castor will use the JDBC ResultSet.getDate(int, Calendar) and related methods which take a Calendar object to specify the timezone of the data retrieved from the database when the timezone information is not already specified in the data; this ensures that the "current" timezone is applied.
The default time zone can be configured in the castor.properties file; see the configuration section for details on how to configure Castor with information about your default time zone.
To change the timezone to a different timezone than the default, please set a (different) value on the org.exolab.castor.jdo.defaultTimeZone property:
Castor JDO uses the JDBC getObject/setObject methods in order to retrieve and set fields. These methods do not perform automatic type conversion, often resulting in unexpected behavior. For example, when using a NUMERIC field with direct JDBC access, application developers tend to call getInteger() or getFloat(), but the Java object returned from a call to getObject is often a java.math.BigDecimal.
Castor JDO implements automatic type conversion between Java and SQL. For this mechanism to work, the mapping file must specify the SQL type being used for Castor to employ the proper convertor. If no SQL type is specified, no conversion will occur, possibly resulting in an IllegalArgumentException being thrown.
SQL types are specified with the sql-type attribute using either the default Java type returned by the JDBC driver (e.g. java.lang.Integer or the proper SQL type name (without precision). The following table lists the supported SQL type names and the corresponding Java types:
|
The following example illustrates how to specify SQL type in field mapping:
Please note that java.util.Date is not automatically converted into a java.sql.Date object; while it is in theory possible to do so, there are three different possible storage formats for date information: as a java.sql.Date, java.sql.Time, and java.sql.Timestamp. Rather than impose a possibly inappropriate data mapping on an entry, no automatic transformation will take place.
JDBC drivers which do not, themselves, perform a mapping between java.util.Date and the sql format specified on the database will throw an error when java.util.Date is passed to them on the prepared statement. Moreover, auto-conversion of java.util.Date is outside of the JDBC specification; it is not a supported auto-convert format.
Users wishing to store date information into the database should ensure that they set date, time, or timestamp as the sql type on the sql-type attribute.
Some of the type convertors may have a string parameter, which changes the conversion algorithm. The parameter is specified in square brackets after the SQL type, for example:
where "0" is the character value for false and "1" is the character value for true.
In the above example the first of a bunch of parameterized type convertors is used, "boolean --> char" convertor. The parameter must have length 2, the first character is the value for false, the second character is the value for true. The default value is "FT". The actual SQL type should be char(1).
The second and third convertors are "boolean --> integer" and "boolean --> numeric". Its parameter must be + for +1 or - for -1 representing true. False is always converted to 0. For example:
If the parameter is not specified, true is converted to +1.
The fourth convertor is "date --> char". Its parameter must be a correct pattern for SimpleDateFormat. For example:
If the parameter is not specified, the conversion is performed using toString() method of the Date class.
The fifth and the sixth convertors are "date --> integer" and "date --> numeric". Their parameters are also patterns having syntax based on the SimpleDateFormat syntax, but repeated characters are eliminated. The following table shows the substitution rules that are used to obtain the SimpleDateFormat pattern from the parameter.
|
For example, "YMD" parameter is expanded to "yyyyMMdd" SimpleDateFormat pattern, "YMDhmsS" parameter is expanded to "yyyyMMddHHmmssSSS" SimpleDateFormat pattern. The length of the expanded parameter gives the minimal number of decimal digits that the actual SQL type must support. The default value of the parameter is "YMD".
The date and time types of org.exolab.castor.types package support 2
timelines as defined by XML schema specification. One for timezoned values and one
for non-timezoned values which are treated to be local. When converting such types
to long the timezone information is lost. In most cases it is no problem to loose
for which timezone the value was specified if the value get converted to UTC time
before. But we also loose if the value had a timezone or not. This causes that
we do not know to which timeline the value belongs. If we just treat it as
non-timezoned value while it has been a timezoned one we have changed the value.
Therefore we have added support for another parameterized type converter. This one
allows you to specify if the date and time values created out of a persisted long
value are meant to be timezoned or not. By default, without a parameter, local
date or time instances are created without a timezone. If you specify the parameter
utc in mapping the date or time values are created based on UTC timezone.
It need to be noted that such a mapping can only handle date and time values of one
of the 2 timelines defined by XML schema specification. Having said that this only
applies to the conversion of such values to long and does not cause issues when
converting to string and back.
BLOB and CLOB stand for binary and character large objects (or in Sybase, IMAGE and TEXT types, respectively). This means that most likely you don't want to load the whole objects into memory, but instead want to read and write them as streams. Usually these types are not comparable via the WHERE clause of a SQL statement. That is why you should disable dirty checking for such fields, e.g.
In this example CLOB field will be read as a String. This may cause OutOfMemoryError if the text is really large, but in many cases mapping CLOB to String is acceptable. The advantage of mapping to String is that we obtain a Serializable value that can be passed via RMI. Similarly you can map BLOB and CLOB to byte[] and char[] types, respectively:
Now, assume that mapping to String is not acceptable. The natural Java type mapping for the BLOB type is java.io.InputStream, and this mapping is supported by Castor:
The natural Java type mapping for the CLOB type is java.io.Reader, but this mapping is not supported by Castor because java.io.Reader doesn't provide information about the length of the stream and this information is necessary for JDBC driver (at least for the Oracle driver) to write the value to the database. This is why the CLOB type is mapped to java.sql.Clob:
When you read data from the database, you can use the getCharacterStream() method to obtain a java.io.Reader from java.sql.Clob. When you write data to the database, you can either use the helper class org.exolab.castor.jdo.engine.ClobImpl to construct java.sql.Clob from java.io.Reader and the length:
or implement the java.sql.Clob interface yourself.
But be aware of the followng restriction: if you map BLOB to java.io.InputStream or CLOB to java.sql.Clob, then you should turn caching off for the Java class containing those values, e.g.:
Blob and Clob values cannot be cached, because they are alive only while the ResultSet that produced them is open. In particular, this means that you cannot use dirty checking for long transactions with such classes.
First, let me say you are not the first to ask this question, and you won't be the last. For many, the term "Castor" has a mysterious aura which leaves the user with a craving, a necessity if you must, of wanting an explanation. The need to understand has plagued people of the human race for some time now.
Some have speculated that Castor comes from the heavens. Either being an astronomer or having flipped through the pages of a Merriam Webster dictionary you may have run across the reference to Castor. Castor in this context is part of a "double star" within the Gemini constellation, the twin star is called Pollux. For all those looking to the sky for the answer, let me reassure you that we do not use Castor in this context. Actually with all the smog here in California, the developers of Castor rarely look to the sky for anything.
A few individuals, brave souls indeed, have even suggested that Castor may be somehow related to the Castor plant, which produces Castor oil. Ugh! Let me reassure everyone, our use of the term Castor has nothing to do with this plant or its by products! If you really think we'd name our software after this plant, please go try some Castor oil for yourself and then come back to us when you've been convinced otherwise.
An even smaller number of you (mostly German in origin) have suggested that Castor may come from those big trucks used in Germany that haul off Nuclear waste (...but to where?). Now why would a small software project dedicated to relational mapping and data binding want anything to do with that?
Some have speculated that some how the name comes from the act of "casting" one type into another. This is a rather interesting speculation. Castor is a pretty advanced "Casting" framework, however, this speculation is as far from the truth as is the distance from Earth to Castor and Pollux.
Other more intuitive people, perhaps by looking at the (now no longer existing) Castor logo, have deduced that Castor is actually a Beaver. Yes it's true. Castor is the more formal or scientific name for a simple little Beaver. This raises a more interesting question.
Let me first state that we have absolutely nothing to do with MIT. We certainly wouldn't mind being affiliated with such a prestigious educational institution; however, I'm certain that they mind that our minds are nowhere near the kind of mind that they look for during their recruitment process. Not that I actually understand what that means, but if you're an MIT alum you are probably relieved we didn't attend.
Now, on to the explaination...
The truth of the matter is that it's highly classified, and on a need-to-know basis. Even members of our own team do not know. However we are allowed to post more speculations on this topic. The most common speculation is that a beaver is well-known for its engineering skills. It cuts down trees, and builds dams and lodges. Since Castor builds source code, using blueprints (an XML Schema), then it too is an engineer.
A more abstract yet rather interesting speculation that builds on the previous reads as follows: XML is based on "trees" or "groves". A beaver cuts down trees. Therefore Castor removes the notion of trees from processing XML documents. This is an interesting observation in that Castor does just that. Castor eliminates the "tree" methodology when dealing with XML. It is an XML data binding framework which allows you to deal directly with your data instead of thinking in terms of a "tree".
Another equally good speculation is that a beaver is one of the cutest little animals in the world and we just couldn't resist giving it some due attention.
There are other speculations, some of which we can not in good nature add to this page. We cannot comment on which speculation may be closer to the truth. We let each user decide on his or her own. Simply choose the speculation which most reduces your craving for more understanding, and feel free to come up with your own speculations.
--Keith
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..
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:
against the up-to-date SVN version, or
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.
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.
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.
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.
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:
In addition, there's various modules available that represent integration and performance test suites for the main modules:
Finally, there's a module to provide Maven 2 archetypes for Castor:
Last but not least, there's a module to provide the project documentation for Castor:
To build Castor using Maven - assuming that you have got Maven 2 locally installed - please issue ...
To run the complete set of JUnit tests, issue ...
To build the project JARs locally, issue ...
To install the generated JARs into your local Maven repository, issue ...
To additionally run the (plenty) integration test suites available with Castor during testing, please issue ...
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:
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.
In above sample, a Jira issue number has been used to uniquely identify the individual modules in 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 compilemvn eclipse:eclipseFor all releases prior to 0.9.7, the release notes can be found here.
For all releases prior to 0.9.6, the release notes can be found here.
This is a reminder that we have started to add some features that more or less depend on features made available with Java 1.4 (only), such as the JDBC 3.0 API enhancements. As such, we have made Java 1.4 a key requirement for the upcoming Castor 1.0 release.
Two new XML how-tos have been added to the XML HOW-TOs page, one on fetching XML dependencies (DTDs and schemas) from JAR files rather than network locations, and one on using identities and references in XML. The XML Mapping documentation was also updated so that the DTD public ID used in examples matches one in Castor's DTDResolver (this aids in fetching the DTD from the Castor JAR rather than the web address).
The cache types fifo and lru are based on a set of articles in the O'Reilly Network by William Grosso, to implement a simplified and 1.3-compatible implementation of a Hashbelt algorithm.
Hashbelts are simple, in principle. Instead of walking all objects and finding out when they're supposed to expire, use a "conveyor belt" approach. At any particular point in time, objects going into the cache go into the front of the conveyor belt. After a certain amount of time or when the size limit of a container has been reached, move the conveyor belt - put a new, empty container at the front of the conveyor belt to catch new objects, and the one that drops off of the end of the conveyor belt is, by definition, ready for garbage collection.
As seen in his system, you can use a set of pluggable strategies to implement the actual hashbelt bits. A container strategy allows you to change out the implementation of the container itself - from simple hashtable-based implementations, up through more complex uses of soft referenced or hashset-based implementations, depending on what you need and what you want it to be used for. A pluggable "expire behavior" handler allows you to determine what action is taken on something which drops off of the bottom of the conveyor belt.
As of release 1.0 Castor knows of 11 cache types. To use this cache types, their factories need to be configured in castor.properties file. If you use a custom castor.properties file you need to add the new cache factories to be able to use the new cache types.
#
# Cache implementations
#
org.castor.cache.Factories=\
org.castor.cache.simple.NoCacheFactory,\
org.castor.cache.simple.TimeLimitedFactory,\
org.castor.cache.simple.CountLimitedFactory,\
org.castor.cache.simple.UnlimitedFactory,\
org.castor.cache.distributed.FKCacheFactory,\
org.castor.cache.distributed.JcsCacheFactory,\
org.castor.cache.distributed.JCacheFactory,\
org.castor.cache.distributed.CoherenceCacheFactory,\
org.castor.cache.distributed.OsCacheFactory,\
org.castor.cache.hashbelt.FIFOHashbeltFactory,\
org.castor.cache.hashbelt.LRUHashbeltFactory
The DTD declaration to configure caching in Castor mapping is as follows:
In difference to all other cache types the fifo and lru cache types offer various configuration options. Both of them have 6 parameters to configure their behaviour.
A fifo cache with default values explained above is specified by:
A lru cache with capacity=300 and ttl=300 is defined by:
An example of a customized configuration of a fifo cache is:
We removed following classes and methods that had been deprecated for a while now.
As we have started to add some features that more or less depend on features made available with Java 1.4 (only), such as the JDBC 3.0 API enhancements, we have made Java 1.4 a key requiremnt for the upcoming Castor 1.0 release.
This decision is a result of a discussion on the mailing lists a couple of months ago, where nobody was voicing any objections.
By specifing
With this addition, it is now possibel to query whether a particular XML element (represented by an XMLClassDesscriptor internally) is abstract or concrete, that is (in the context of source generation) a result of a <complexType> definition or an <element> declaration. This is particularly relevant for tool providers who need to integrate with Castor XML, and as a result of this addition can now use the new isElementDefinition() method to query an artifact's state.
Added XML HOW-TOs for mapping collections and maps.
Added new
Added support for the postgreSQL column type 'SERIAL' to the identity key generator. With this change, it's now possible to use the identity key generator with postgreSQL on columns with type 'SERIAL'. Castor internally will issue a call to
to automatically retrieve the value assigned due to 'SERIAL' column during the insert operation.
Added new ZIP archive to distribution that contains a fully self-contained Castor JDO sample applicationthat runs against an embedded Apache Derby database.
Simply download the the archive, unpack it, and in the target directory created, execute 'java -jar castor-1.0M2-examples.jar' to have the test executed. This will (magically) create a Derby database (on-the-fly) and use it to execute the Castor JDO code against it.
In addition to the current way of specifying the identity column(s) for a given class, it is now possible to declare a field to be part of the identity as shown below:
It is now possible to define a one-to-many relation with a collection type of 'iterator'. This allows the access of custom collection classes that are not supported through the standard collection types through Castor JDO.
It is now possible to define a one-to-many relation with a collection type of 'enumerate'.
To use the Xerces implementation delivered with Weblogic 7 and 8 you have to change castor.properties file to contain the following entry:
# Defines the (default) XML serializer factory to use by Castor,
# which must implement org.exolab.castor.xml.SerializerFactory;
# default is org.exolab.castor.xml.XercesXMLSerializerFactory
org.exolab.castor.xml.serializer.factory=org.exolab.castor.xml.wls8.WeblogicXercesXMLSerializerFactory
Added support for java.util.List as collection type for Castor XML.
Support for Borland's Pointbase has been added. For initial information about configuration of Castor JDO for the use with Borland's Pointbase, please see src/tests/jdo/pointbse.xml.
This new method allows to check, whether a particular object (as identified by the object identity and the object class) is currently locked with Castor JDO.
Added a section about the various methods available on the Persistence interface to the HTML docs.
With 'case-insensitive' commandline option of source generator you are now able to instruct Castor to use case insensitive lookups for enumerated type values.
As a result of this refactoring, we had to change the way a XMLSerializer is created (instantiated). Rather than letting Castor know about the XMLSerializer to use, as in
# Defines the default XML serializer to be used by castor
# The serializer must implement org.apache.xml.serialize.Serializer
#
org.exolab.castor.serializer=org.apache.xml.serialize.XMLSerializer
the user is now required to specify an XMLSerialzer factory as follows:
# Defines the (default) XML serializer factory to use by Castor,
# which must implement org.exolab.castor.xml.SerializerFactory;
# default is org.exolab.castor.xml.XercesXMLSerializerFactory
org.exolab.castor.xml.serializer.factory=org.exolab.castor.xml.XercesXMLSerializerFactory
As of this release, we only support the XercesXMLSerializerFactory as shown above, but provide users with three new interfaces (namely Serializer,OutputFormat and XMLSerializerFactory) that need to be implemented to support any other's XML parser custom serialization mechanism.
Take care to adjust your custom castor.properties file to reflect the changed packages of CacheFactories.
#
# Cache implementations
#
org.castor.cache.Factories=\
org.castor.cache.simple.NoCacheFactory,\
org.castor.cache.simple.TimeLimitedFactory,\
org.castor.cache.simple.CountLimitedFactory,\
org.castor.cache.simple.UnlimitedFactory,\
org.castor.cache.distributed.FKCacheFactory,\
org.castor.cache.distributed.JcsCacheFactory,\
org.castor.cache.distributed.JCacheFactory,\
org.castor.cache.distributed.CoherenceCacheFactory
Note: By also moving CacheFactoryRegistry to org.castor.cache package the property has been renamed from 1.0M1 a second time.
The DTD declaration is as follows:
The new syntax is still backward compatible to the old one but allows to enable debugging of cache access for a specific class as well as passing individual configuration parameters to each cache instance. Only count-limited and time-limited of the current cache types support parameters. Parameter names are case sensitive and are silently ignored if they are unknown to a cache type.
It need to be noted that there are 3 parameter names that are reserved for internal use. If you specify a parameter with one of the names: type, name or debug their value will silently be overwritten with another one used internally.
A count-limited least-recently-used cache (LRU) for 500 objects
can be specified by:
A time-limited first-in-first-out cache (FIFO) that expires
objects after 15 minutes can be specified by:
The debug attribute can be used to enable debugging for objects of a single class only, as described below.
If you like to get debug messages for every access to cache independend of the caches type or the class of the object that is accessed you only need to set logging level of org.castor.cache to debug. As this may lead to lots of debug messages, you are not interested in, there are 2 options to reduce the number of the messages.
If you are interested in all accesses to a specific cache type you set the logging level of this implementation to debug.
To get debug messages of accesses to objects of a specific class there are 2 things you need to do. To be able to get debug messages at all you need to set logging level of org.castor.cache.Cache to debug first. Then you only need to set the debug attribute of the class you are interested in to true in the mapping.
Note: By allowing to pass individual configuration properties from mapping to cache we again changed the way debugging is enabled. The property in castor.properties file from relaese 1.0M1 is no longer supported.
Support has been added for the new collection type 'sortedset'. This allows users of Castor (XML and JDO) to use collections of type java.util.SortedSet to allow for automatic ordering of the collection upon e.g. insertion of the data.
User can either specify a java.util.Comparator instance using the comparator attribute on the field mapping, or make the entities stored within the SortedSet implement java.util.Comparable.
With this refactoring JDOConfFactory has also been moved from org.exolab.castor.jdo.util to org.castor.jdo.util package. In addition we allowed to specify a name attribute on the jdo-conf tag that will be used in future to distinguish between different configurations.
Take care to adjust your custom castor.properties file to reflect the changed packages of CacheFactories.
#
# Cache implementations
#
org.castor.jdo.cacheFactories=\
org.castor.cache.simple.NoCacheFactory,\
org.castor.cache.simple.TimeLimitedFactory,\
org.castor.cache.simple.CountLimitedFactory,\
org.castor.cache.simple.UnlimitedFactory,\
org.castor.cache.distributed.FKCacheFactory,\
org.castor.cache.distributed.JcsCacheFactory,\
org.castor.cache.distributed.JCacheFactory,\
org.castor.cache.distributed.CoherenceCacheFactory
By setting the property org.castor.jdo.cacheDebug to true you are able to get debug messages for every cache access in the configured log.
#
# True if proxy class should be used to debug access to cache
# (default: false).
#
#org.castor.jdo.cacheDebug=false
Take care to adjust your custom castor.properties file to reflect the changed packages of TransactionManagerFactories.
#
# TransactionManagerFactory implementations
#
org.castor.transactionmanager.Factories=\
org.castor.transactionmanager.WebSphereTransactionManagerFactory,\
org.castor.transactionmanager.WebSphere5TransactionManagerFactory,\
org.castor.transactionmanager.WebSphere51TransactionManagerFactory,\
org.castor.transactionmanager.LocalTransactionManagerFactory,\
org.castor.transactionmanager.JNDIENCTransactionManagerFactory,\
org.castor.transactionmanager.JOTMTransactionManagerFactory
In addition a new property has been introduced that allows to configure if the transaction manager shell be acquired instantly when he is registered or lazy when it is needed for the first time.
#
# Shell the TransactionManager be initialized at registration or lazily when
# requested for the first time? Defaults to false.
#
org.castor.transactionmanager.InitializeAtRegistration=false
Added support for JOTM as transaction co-ordinator. As a result, the following transaction managers are supported.
The new implementation of the Database.getIdentity(Object) does not rely on the object being loaded in the same transaction anymore. It is even not required to have an active transaction. The identity will now be determined by calling the getters of the fields defined as identities in the mapping. If a mapping for the objects class could not be found a ClassNotPersistenceCapableException will be thrown. Null is only returned if the objects identity is null.
Note:Care should be take if you previously used the null return of Database.getIdentity(Object) to determine if the object has been loaded in the current transaction before.
Added org.castor.jdo.util.JDOUtils.closeDatabase() method to close an open database instance without throwing exceptions. Any active transaction will be silently rolled back.
Added code to DTDResolver so that any URL/URIs against http://castor.org/... will be resolved against (local) files from within the Castor JAR(s).
Fixed a problem with obtaining the underlying JDBC connection used by Castor internally when there was no valud transaction. The code has been changed so that a PersistenceException will be thrown to indicate the lack of a valid transaction.
This is the final 0.9.9 release, a feature release for Castor JDO and XML.
Please note that we are providing the usual suspects (binaries, docs and sources) for this release at the Codehaus.
We are currently planning for a Castor 1.0 release in about 8+ weeks, which we mainly see as a bug fix release and a one-time opportunity to get the HTML documentation into a better shape .. ;-).
Please note that we have - in addition to the features added and bugs fixed as documented with 0.9.9M1 and 0.9.9M2 - started to makes substantial changes to the project documentation as follows:
As mentioned above, these pages are work in progress and shall be expanded for the upcoming 1.0 release.
Please note that we are providing the usual suspects (binaries, docs and sources) for this release at the Codehaus. We recommend, though, to download the complete package, as the HTML docs at the main Castor site has not been updated, and to build the documentation yourself.
Preparations for the final release have started. Since the last release candidate, the following problem areas have been addressed.
Please note that we are providing the usual suspects (binaries, docs and sources) for this release at the Codehaus. We recommend, though, to download the complete package, as the HTML docs at the main Castor site has not been updated, and to build the documentation yourself.
Support for polymorphism has been completely rewritten, allowing you to load objects that are part of an extend relationship by their base types, with Castor JDO returning the actual (leaf) classes.
With the following class hierarchy ...
it will be possible to execute OQL queries as follows:
SELECT product FROM Product product
and Castor JDO will return the actual Laptop and Server instances. For a complete set of code examples, please review src/tests/ctf/jdo/tc9x/TestPolymorphism.java.
Both castor-0.x.y.jar and castor-0.x.y-xml.jar now carry an updated and up-to-date MANIFEST file.
Support for Apache Derby (starting with release 10.1.1.0) has been added. For initial information about configuration of Castor JDO for the use with Apache Derby, please see src/tests/jdo/derby.xml.
Known issues:
As of this release, four new cache types have been added:
As some of these cache implementations allow you to use it in a distributed mode, this allows Castor JDO to be used in a clustered (multi-JVM) environment. In such an environment, Castor JDO wil make use of the underlying cache provider to replicate/distribute the cache content between the various JDOManager instances.
Support for the transient attribute has been added to the <sql> element has been added. This allows you to define a field mapping as follows:
<field name="prop1" type="string">
<sql name="prop_1" transient="true" />
<bind-xml name="property1" />
</field>
allowing you to include a field for XML un-/marshalling, but exclude it from persistence.
Enumerations are a common method for ensuring data integrity, both in software and in relational databases. As a platform for linking the two, we added support for persisting class fields whose type is a Java typesafe enumeration to Castor JDO.
To use this new feature your typesafe enumeration should follow the enum pattern commonly used and provide a static valueOf(String) method. An enum of different kinds of computer equipment may look like:
public class KindEnum {
private static final Map KINDS = new HashMap();
public static final KindEnum MOUSE = new KindEnum("Mouse");
public static final KindEnum KEYBOARD = new KindEnum("Keyboard");
public static final KindEnum COMPUTER = new KindEnum("Computer");
public static final KindEnum PRINTER = new KindEnum("Printer");
public static final KindEnum MONITOR = new KindEnum("Monitor");
private final String _kind;
private KindEnum(final String kind) {
_kind = kind;
KINDS.put(kind, this);
}
public static KindEnum valueOf(final String kind) {
return (KindEnum) KINDS.get(kind);
}
public String toString() { return _kind; }
}
At your Product class you may want to have a property that tells you what kind of computer equipment a product is of.
public class Product {
private int _id;
private String _name;
private KindEnum _kind;
public Product() { }
public int getId() { return _id; }
public void setId(int id) { _id = id; }
public String getName() { return _name; }
public void setName(String name) { _name = name; }
public KindEnum getKind() { return _kind; }
public void setKind(KindEnum kind) { _kind = kind; }
}
Your mapping for the Product class should be:
<class name="Product" identity="id">
<description>Product with kind enum</description>
<map-to table="enum_prod"/>
<field name="id" type="integer">
<sql name="id" type="integer"/>
</field>
<field name="name" type="string">
<sql name="name" type="char"/>
</field>
<field name="kind" type="KindEnum">
<sql name="kind" type="char"/>
</field>
</class>
To add this new feature we added an additional check when searching for field types. Like before Castor first searches for know types and thereafter for a mapping for the class you specified as type. If both of them do not match it now checks if the class specified as type is available at classpath and has a static valueOf(String) method. Only if all of this conditions are met it will be viewed as a valid mapping.
Pre patch we always returned a boolean value even if the database contained a value which does not conform to the rules defined. This behaviour caused that we could load records with wrong values without problems but got a ObjectModifiedException when we tried to update these values as our update statment includes checking of all old values in the where clause of SQL statement.
With the patch this behavier changes to strict checking if the loaded char/string value matches one of the boolean characters defined by conversion rule. If the value does not match a ClassCastException explaing the fail reason will be thrown.
Several code areas of Castor JDO have been severly refactored or rewritten from scratch, leading to some significantly improved runtime performance. This includes amongst others a reduced execution time when dealing with a large number of entities loaded as part of a single transaction, etc.
This is the final 0.9.7. release, mainly a maintenance release. We are currently planning the next release which will be Castor 0.9.9, a feature release.
Whilst this change is non-intrusive per se, please note that you might have to change a local castor.properties file if you happened to re-specify key generators in there.
Support for multiple database configurations has been re-enabled.
For all the releases prior to 0.9.7, the release notes can be found at here or here.
As of release 1.0M3, the Castor JDO examples have been packaged in a new way and are available for download at the download page. In the following sections, we explain the steps required to unpack this new archive, and how to execute the tests.
In order to be able to run the new Castor JDO examples, please download the new castor-${RELEASE}-examples.zip from the download page and put it into some location on your computer.
To unpack the ZIP file downloaded, issue one of the following commands:
or
You can now run the examples using the directions provided in the next section.
In the directory where you have unpacked the ZIP file you'll find a castor-1.1M2-examples.jar. In addition, you'll find a directory named lib where you'll find several JAR files required to run the samples.
To execute the samples, issue the following command:
... et voila ! You'll see various lines of logging output flashing by whilst the Castor JDO samples are executing against a database.
The Castor JDO sample will test persistence between a set of Java classes (Product, ProductGroup, ProductDetail, etc.) and perform this code against an Apache Derby instance as RDBMS. For this purpose, the sample code will start an embedded Derby instance on the fly, create the required tables, and then continue to execute several code fragments using various Castor JDO artifacts (JDOManager, Database, etc.) against this embedded database.
In other words, everything is self-contained and there is no need to install a database, create a database schema, or create database tables. Everything required for the tests is initiated and set up from within the sample code.
XML: Added support for namespace to package mappings on the Unmarshaller
and UnmarshalHandler. This basically fixes issues where Castor
can't find the right package to look for classes during
unmarshalling. This is main for those people using generated
source code, as using a mapping file you must specify the
packages and namespaces appropriately.
(kvisco - 20041104)
XML: Fixed bug in SourceGenerator where class names for SimpleType
instances with Enumeration facets were not getting resolved properly.
(kvisco - 20041104)
XML: Fixed bug 1685, A StackOverflowError was occuring at certain times
during container processing if the input XML was invalid.
Details: http://bugzilla.exolab.org/show_bug.cgi?id=1685
(kvisco - 20041005)
XML: Fixed StackOverflowError in FieldValidator which can occur during
validation of object models with circular references.
(kvisco - 20041005)
XML: Fixed bug 1592: DecimalValidator was not taking into account a leading
sign ('+' or '-').
Details: http://bugzilla.exolab.org/show_bug.cgi?id=1592
(kvisco - 20041004)
XML: Fixed bug 1666: UnmarshalState._markedList Vector is a performance
bottleneck. Applied patch from David Thal which replaces the
Vector with a HashSet.
(kvisco - 20040910)
XML: Fixed bug 1658: Handling of whitespace is never preserved for
container objects. Applied patch from Chris Giordano which
basically inherits the whitespace preserving state from
the parent UnmarshalState.
(kvisco - 20040910)
XML: Fixed bug 1634: Whitespace handling while unmarshalling is flawed.
Updated the whitespace handling logic in UnmarshalHandler#characters
method and checked in a test case.
(kvisco - 20040910)
XML: Updated the Marshaller to use ContentHandler directly instead
of wrapping in a ParserAdapter. Users Marshalling to a
ContentHandler should see a significant speed up when
Marshalling.
(kvisco - 20040910)
XML: Fixed a bug in the Marshaller with the xsi:type logic not being
strict enough. Sometimes the Marshaller was not adding xsi:type
when it was needed. I've modified this logic a bit to make it
output xsi:type more often in order to preserve round tripping.
(kvisco - 20040910)
XML: Fixed bug 1560 by adding some additional checks for null
in the XMLClassDescriptorImpl.
(kvisco - 20040729)
XML: Updated the Unmarshaller to make sure it gets the ClassLoader
from the passed in class if no user specific loader has been
specified.
(kvisco - 20040729)
XML: Fixed bug with FieldHandlerFactory support in introspector by
making sure the the type specified by the FieldHandler
replaces that of the introspection. This allows primitives
to be correctly handled by the custom FieldHandler.
(kvisco - 20040720)
XML: Fixed java.util.Set support in the introspector.
(kvisco - 20040713)
XML: Fixed a cyclic include bug with the IncludeUnmarshaller, added
some code to make sure the main schema couldn't include itself.
(kvisco - 20040624)
XML: Fixed bug 1524: Stack Overflow when container elements occur in
instance document. The problem was primarily due to the
MarshalFramework#searchInheritence method which was allowing
the ClassDescriptors for schema groups to be searched.
(kvisco - 20040608)
XML: Fixed bug 1633 XML Date Timezone Not unmarshalled correctly.
Patch from axia@sonusnet.com.
(kvisco - 20040527)
JDO: Fixed bug 1617 using contribution from Patrick vanKann [patrick.vankann@cookie-fortune.com]
Fixed an incorrectly coded equality check related to global transaction demarcation.
Details: http://bugzilla.exolab.org/show_bug.cgi?id=1617
(Werner - 20040516)
JDO: Fixed bug 1534.
Added code to allow users to use their own cache implementation with Castor.
In general, available cache implementations are now specified in castor.properties.
(Werner - 20040513)
XML: Fix for bug 1632. StringValidator.normalize wasn't handling empty
strings properly. Patch from Ulli Hafner.
(kvisco - 20040511)
XML: Performance change to org.exolab.castor.util.List to demand create internal Object[]
From various performance improvements contributed by Ian Richards (also CODA)
(afawcett - 20040510)
XML: One fix and various minor enhancements to classes in 'javasource' package.
(afawcett - 20040510)
XML: Performance enhancement to AnyNode2SAX.java (use when processing xsd:any elements)
from various performance improvements contributed by Ian Richards (also CODA)
(afawcett - 20040508)
XML: Fixed bug 1506 - Enhancement for EnumeratedTypeAccess interface
using patch contributed by Robert La Ferla.
(kvisco - 20040505)
ALL: Reworked the mailing list guidelines. Added various sections re: cross-posting, etc.
(Werner - 20040502)
JDO: Fixed bug 1605 using contribution from Emir Causevic [emirc@gawab.com]
Brought test setup for SAP DB in-line with test requirements.
(Werner - 20040429)
JDO: Fixed bug 1605 using contribution from Emir Causevic [emirc@gawab.com]
Brought test config file for SAP DB in-line with XML Schema.
(Werner - 20040429)
JDO: Fixed bug 1368 using contribution from Tim O'Brien [tobrien@discursive.com].
Small (mostly syntactical) changes to src/doc/jdo-faq.xml. Added a reference
to XPath as well.
(Werner - 20040428)
JDO: Fixed bug 1607 using contribution from Emir Causevic [emirc@gawab.com]
Added test for IdentityKeyGenerator to SAP DB test suite.
(Werner - 20040428)
JDO: Fixed bug 1092 using contribution from Rhett Sutphin [rhett-sutphin@uiowa.edu].
Fixed default namespace declaration, changed some small syntax issues.
(Werner - 20040427)
JDO: Fixed bug 1606 using contribution from Emir Causevic [emirc@gawab.com]
Fixed problem with incorrectly quoting non-function names for SAP DB.
(Werner - 20040427)
JDO: Fixed bug 1607 using contribution from Emir Causevic [emirc@gawab.com]
Added support for SAB DB to IdentityKeyGenerator.
(Werner - 20040427)
JDO: Fixed bug 1605 using contribution from Emir Causevic [emirc@gawab.com]
Fixed various problems related to the setup of JDO test data with SAP DB.
(Werner - 20040427)
JDO: Fixed bug 1615 using contribution from frric@wmdata.com [frric@wmdata.com]
Fixed a typo in a debug statement (wrong message resource key used).
(Werner - 20040426)
JDO: Fixed bug 1601 using contribution from Tomasz Piontek [piontek@man.poznan.pl]
Added code to support org.exolab.castor.types.Duration as a native type
in Castor JDO. Added convertors for type conversion org.exolab.castor.types.Duration
<--> java.lang.Long.
(Werner - 20040421)
JDO: Fixed bug 1554 using contribution from Stein M. Hugubakken [dulci@start.no]
Fixes a memory leak with the linked-list implementation by removing LinkedList
completely; uses the Hashtable directly, resulting in much better performance.
ValuesEnumeration no longer use a Vector, but intercepts the initial
enumeration to provide the values.
(Werner - 20040420)
JDO: Fixed bug 1597 using patch from Emir Causevic [emirc@gawab.com]
(Bruce - 20040408)
JDO: Fixed bug 1588.
Introduces various checks and additional exception handling wrt to using TimeStampables.
(Werner - 20040406)
ALL: Fixed bug 1585 adding separate build folders for src/tests and src/examples
to the Eclipse project files
(Werner - 20040330)
JDO: Fixed bug 1573 using contribution from Stein M. Hugubakken [dulci@start.no]
This improves code quality for the complete jdo package (except conf.*)
by removing unused import statements and local variables.
(Werner - 20040330)
ALL: Fixed bug 1568 using contribution from jpinto@inescporto.pt [Joo Luis Pinto].
Streamlines Eclipse related project files.
(Werner - 20040319)
JDO: Added many enhancements to the tx mgr API including code improvements,
jdo-conf.xsd changes, dynamic code generation using Castor XML as well
as a refactored Ant build descriptor all from both myself and Werner.
(Bruce - 20040323)
ALL: Fixed bug 1563 using a patch from Keith
(Bruce - 20040323)
ALL: Fixed bug 1566 using contribution from jpinto@inescporto.pt [Joo Luis Pinto].
Updates Eclipse related project files.
(Werner - 20040319)
XML: Fixed bug with new HashMap handling when dealing with
references.
(kvisco - 20040308)
XML: Added behavior change in Mapping files...field mappings
now use parent namespace by default to help ease the
pain of writing mapping files.
(kvisco - 20040307)
XML: Added patch to prevent introspection of transient fields
or static final fields.
(kvisco - 20040305)
XML: Updated unmarshalling to handle xml:space attribute.
Whitespace preserving + stripping can now be controlled
via the Unmarshaller#setWhitespacePreserve method.
(kvisco - 20040301)
XML: Fixed Bug 1539 Getting java.lang.IllegalStateException:
Invalid dateTime format
(kvisco - 20040301)
XML: Added Marshaller patch that fixes container attribute
processing for items in collection. Fixes an
IllegalArgumentException
Patch from Balaji Adikesavelu
(kvisco - 20040223)
XML: Added minor enhancement to generated source for boolean
types to prevent unecessary creation of Boolean instances.
Enhancement request 1527.
(kvisco - 20040222)
XML: Fixed stack overflow with cyclic mapping imports.
(kvisco - 20040222)
XML: Removed dependency on Apache Commons Logger for Castor XML,
this will become a dependency again in Castor 0.9.6.
(kvisco - 20040222)
XML: Prevented warning about name conficts from being printed if the
-f flag is being used.
(kvisco - 20040221)
XML: Fixed SourceGenerator warning with simpleTypes conflicting with
element names.
(kvisco - 20040221)
XML: Fixed bug 1541, a regression which was causing an endless
loop and source code that was uncompilable.
(kvisco - 20040221)
XML: Patch for bug 1474 SchemaWriter assigns wrong
namespace to base complexType.
Patch from Jackie Paradis
(kvisco - 20040216)
XML: Patch for bug 1461 JakartaRegExpEvaluator issue
Patch from Johan Van vlerken.
(kvisco - 20040213)
XML: Fixed bug 1475 - removed check for DocumentHandler (which
prevented wrapping in a ParserAdapter)
(kvisco - 20040213)
XML: Patch for bug 1449 - Configuration.loadProperties throws
SecurityException when running under app-server.
Patch from Joakim Ohlrogge.
(kvisco - 20040213)
XML: Patch for bug 1471 - unspecified type causing uncompilable source
(kvisco - 20040213)
XML: Fixed bug 1272 - Uncompilable code with boundproperties
Patch from Brett Randall and Peter Lin
(kvisco - 20040213)
XML: Fix for bug 1245: Nicer variable names for typesafe enumerations
from Source Generator. Patch from Rhett Sutphin.
(kvisco - 20040213)
XML: Fixed bug 1530 by adding readResolve method when generating enumerations
to handle deserialization issues. Patch contributed by Thomas De Smedt
(kvisco - 20040213)
XML: Patch to prevent duplicate simpleType class generation. This was causing
unnecessary warnings during source code generation.
(kvisco - 20040213)
JDO: Fixed bug 1514 adding Eclipse related project files.
Added new Ant target 'prepare-eclipse' to copy Eclipse-specific project files
to the base directory.
(Werner - 20040212)
JDO: Fixed bug 1521 refactoring the performance cache code.
This introduces a new interface (Cache.java) which all existing cache
implementations implement. This lays the foundation for many additions
as noted in the bug report.
(Werner - 20040210)
JDO: Fixed bug 1462 using contribution from Christoph Ernst [christoph.ernst@dit.de]
Fixes a problem with SQL type conversions between java.sql.Timestamp and
java.util.Date and vice versa. Additionally, this fixes a couple of problems
with the use of various resource entries (jdo.store, etc.) and generally
improved code quality by removing unused import statements and local
variables.
(Werner - 20040206)
JDO: Fixed bug 1522 using contribution from Stein M. Hugubakken [dulci@start.no].
Removed deprecated and unused methods from Database.java and
DatabaseImpl.java.
(Werner - 20040205)
JDO: Fixed bug 1499 using contribution from Stein M. Hugubakken [dulci@start.no].
DatabaseImpl.finalize() now outputs a warning if the instance about to be
garbage-collected still has valid scope. In addition, improves code
quality in DatabaseImpl.java by removing unused import statements and
local variables.
(Werner - 20040124)
JDO: Fixed bug 1417 using contribution from Stein M. Hugubakken [dulci@start.no].
Added missing entry for resource string "persist.missingEnd" to
messages.properties.
(Werner - 20040129)
ALL: Fixed bug when using extends of a class from an included mapping.
(kvisco - 20040128)
XML: Fixed bug 1477: Use of fixed value elements fails in choice blocks
(kvisco - 20040122)
JDO: Fixed bug 1500 using contribution from Martin Fuchs [martin-fuchs@gmx.net]
Fixes a problem with dereferencing members of Complex that are set to null.
(Werner - 20040122)
JDO: Fixed bug 1498 using contribution from Stein M. Hugubakken [dulci@start.no]
This patch improves performance by checking Log.isDebugEnabled() when using
Log.debug() statements.
(Werner - 20040119)
JDO: Fixed bug 1495 using contribution from Stein M. Hugubakken [dulci@start.no]
This improves code quality in the jdo.drivers package by removing
unused import statements and local variables.
(Werner - 20040119)
XML: bind-xml now allows nesting a class mapping to enable the user
to map a specific class differently in different situations.
(kvisco - 20040109)
XML: Fix for bug 1439 (improves Hashtable / Map handling)
(kvisco - 20040109)
XML: Fix bug where wrong field descriptor may be returned if the class
descriptor also supports wildcards.
(kvisco - 20040108)
JDO: Fixed bug 1493 using contribution from Stein M. Hugubakken [dulci@start.no]
This patch improves code quality in the jdo.engine package by removing
unnecessary import statements in various classes.
(Werner - 20040118)
XML: Patch to make sure cyclic imports/includes on the primary schema
don't occur.
(kvisco - 20031216)
JDO: Fixed bug 1484 as noted by Jon Revie [revie@rhinointernet.com]
(Bruce - 20031210)
XML: Fix for handling built-in attributes such as xml:lang and xml:base
for XML mapping files.
(kvisco - 20031208)
JDO: Fixed bug 1473 as noted by Jon Revie [revie@rhinointernet.com]
(Bruce - 20031206)
JDO: Fixed bug 1472 as noted by Jon Revie [revie@rhinointernet.com]
(Bruce - 20031206)
JDO: Fixed bug 1466 as noted by [arthurb@cs.uu.nl].
(Bruce - 20031203)
JDO: Fixed the SQLTypes TypeConverters so that each anonymous method
that calls a getter that wraps DateFormat et al. only does so
once.
(Bruce - 20031124)
XML: Improved class name conflict detection and reporting
(kvisco - 20031119)
XML: Fix for incorrect descriptor generation for groups that contain
only optional elements
(kvisco - 20031118)
XML: Added error notification when unresolved references occur during
unmarshalling.
(kvisco - 20031117)
JDO: Switched the logging mechanism in Castor over to use Jakarta Commons
Logging with Log4J as the default logging package.
(Bruce - 20031110)
JDO: Fixed bug 1391 using contribution from xgard@gmx.de.
(Bruce - 20031110)
JDO: Fixed bug 1452 as noted by Marc Guillemot[mguillemot@yahoo.fr].
(Bruce - 20031110)
XML: Fix for bug 1423 (EnumFieldHandler can't handle nillable element).
Applied Stephane Pelchat's patch [stephane (at) ofoto.com]
(kvisco - 20031110)
XML: Improved the error messages for the FieldValidator to use the
xmlName + fieldName to make the message more intuitive.
(kvisco - 20031110)
XML: Added basic support for xs:token (treated as a string)
(kvisco - 20031110)
XML: Added support for FieldHandlerFactory, which allows using
custom GeneralizedFieldHandler instances per type
without having to specify them on a per-field basis in the
mapping file. Currently this must be set through the
Introspector, but an easier configuration will be available
in a future release.
(kvisco - 20031023)
XML: Add a new option in the CTF to allow dynamic configuration
of the marshalling framework by using the java reflection.
(Arnaud - 20031017)
XML: Fix attribute processing when marshalling an AnyNode.
Namespace handling was not enabled
(Arnaud - 20031016)
XML: Enhance SAX2ANY to be compliant with the use of XML Reader.
(Arnaud - 20031016)
XML: Improvements to the CTF (better error reporting)
(Arnaud - 20031015)
XML: Fixed xsi:type bug when xsi:type appears on the root element.
(kvisco - 20031010)
XML: Fix for 'xml' prefix cannot be declared exception when using
Xerces 2.x, when using SAX 2.0.
(kvisco - 20031010)
XML: Added the Source Generator command-line option
'-generateImportedSchemas' that lets you specify
the automatic generation of Java for imported XML Schemas.
(Arnaud - 20031010)
XML: Fix for unmarshalling primitives as root elements.
(kvisco - 20031003)
XML: Updated FieldValidator to prevent validation of transient fields.
(kvisco - 20031003)
XML: Some Unmarshalling performance improvements.
(kvisco - 20030927)
XML: Added SchemaReader#setErrorHandler method. Patch provided
by Nick Betteridge.
(kvisco - 20030925)
XML: Updated to use XMLReader instead of SAX Parser by
default.
(kvisco - 20030925)
XML: Added direct support for SAX 2 ContentHandler in the
UnmarshalHandler.
(kvisco - 20030925)
XML: Added SimpleType#removeFacets method. Patch provided
by Nick Betteridge.
(kvisco - 20030925)
XML: Fixed NullPointerException when trying to marshal a
Vector as the root object.
(kvisco - 20030923)
XML: Fix for bug 1322, this is an improved patch for handling
primitives in the XMLFieldDescriptorImpl#canAccept method.
Proposed patch from Alan Coleman.
(kvisco - 20030923)
XML: Fix for bug 1407, make sure namespace/package mapping is
properly set. This fixes the improper include of the "types" package,
missing the remainder of the package name.
(kvisco - 20030919)
XML: Fix for location paths that contain two or more ancestor paths.
Fix provided by Scott Schenksj.
(kvisco - 20030918)
XML: Fix for bug 1314, make sure we use LocalConfiguration to return
the proper XMLNaming instance.
(kvisco - 20030912)
XML: Fixed static properties issue when calling the SourceGenerator#main
method multiple times from another program (instead of on the command
line).
(kvisco - 20030912)
XML: Fix for bug 1396, updated LocalConfiguration to make sure that
the local properties are used instead of the default properties
when loading SAX parser features.
(kvisco - 20030909)
XML: Fixed issue with wildcard introspection; removed an errant "break"
statement in the XMLClassDescriptorImpl which was causing the
wildcard descriptor to get in the way of a potential exact match.
Patch from Dan Christopherson.
(kvisco - 20030822)
JDO: Fixed bug 1376: Accessing the javax.sql.DataSource object from a
DatabaseRegistry instance
(bruce - 20030807)
XML: Updated XMLInstance2Schema to handle empty elements that contain
attributes. The attributes were previously being ignored.
(kvisco - 20030730)
XML: Fixed issue when using default XML namespace for special XML
attributes, such as xml:lang, and xml:base, etc.
(kvisco - 20030730)
XML: Fixed issue with unmarshalling namespace nodes that have the same
namespace URI as an existing locally declared namespace URI.
(kvisco - 20030725)
JDO: Fixed bug 1355: SAP DB will not execute a function that is quoted.
(bruce - 20030710)
XML: Fix for default wildcard namespace when reading an XML Schema.
(kvisco and Tom Murray - 20030703)
XML: Added support for "merged" locations. If two or more "consecutive" fields
in a class mapping refer to the same "location" they will be now be
merged under the same element instead of creating a new element.
Currently there is no way to specify separate elements (unless you place
a different field mapping in-between the specified field mappings).
(kvisco - 20030625)
XML: Fixed bug 1334: Incorrect unmarshalling using same name, but different "location".
(kvisco - 20030625)
XML: Fixed bug 1333: <bind-xml> location attribute does not always work.
This issue had to due with not marshalling attribute fields that use
the bind-xml location attribute if no element fields used that same
location.
(kvisco - 20030625)
JDO: Integrated API enhancement to support cache flushing/eviction from
Vince Adamo [vadamo@vignette.com]. See bug 1091 for details.
JDO: Fixed bug 1107. Actually this was fixed in version 0.9.5 by bug 1313
(Bruce - 20030610)
XML: Fixed bug 1319: Incorrect Java inheritance generated by castorBuilder
with extended complex types in choices. Patch submitted by Alan
Coleman.
(kvisco - 20030603)
XML: Clear the <package> implementation in the binding file and fix bug
regarding <namingXML>
(Arnaud - 20030602)
XML: Fixed some issues with UTC offsets with DateFieldHandler when
timezone had zero offset from UTC during daylight savings.
patch prodived by Phil Pinel.
(kvisco - 20030529)
XML: Fixed code generation for nested groups that can occur more than once and that
are the only particle of the group.
(Arnaud - 20030523)
JDO: Fixed bug 1313: Default capacity on count-limited cache type is 30 not 100
Fix noted by Stein M. Eliassen [stein.m.eliassen@start.no]
(Bruce - 20030516)
XML: Fixed bug 1279: Castor should be JAXP-enabled. I added initial
JAXP support. To use a JAXP parser instead of Xerces, modify
the castor.properties file and set the "org.exolab.castor.parser"
property to empty as such: org.exolab.castor.parser=
(kvisco - 20030501)
XML: Fixed bug 1301: UTC offsets are not output by default. Initial
patch contributed by Leif Oines. Some changes by myself to remove
use of SimpleDateFormat.
(kvisco - 20030428)
XML: Fixed bug 1300: UTC offset calculations do not account for Daylight
Saving time. Initial patch contributed by Leif Oines. Some changes
by myself to remove use of SimpleDateFormat.
(kvisco - 20030428)
XML: Fixed issue with mapping multiple elements with the same name but
different namespace to separate fields.
(kvisco - 20030423)
XML: Added support for constructor arguments for attribute mapped fields.
Information will be added to the documentation soon. See bug 1177
[http://bugzilla.exolab.org/show_bug.cgi?id=1177] for more information.
(kvisco - 20030422)
JDO: Fixed Bug 1261 and 1253 : In case of CALL SQL binding param inside
parens results adds extra paren
(Mickael - 20030415)
JDO: Fixed bug 1290: Possible bug in object value rollback of primitive types.
(Bruce - 20030413)
JDO: Fixed Bug 1106 : JDO mapping with collection="array" does not work
(Mickael - 20030325)
JDO: Fixed Bug 1045 : date->char[yyyy-MM-dd hh:mm:ss] parameterized type not supported
(Mickael - 20030325)
XML: Added initial support for wrapper elements, which are now supported
via the bind-xml "location" attribute. More information will be
available in the docs, hopefully soon.
(kvisco - 20030313)
XML: Applied Edwin Dankert's patch to DatatypeHandler (used by the
XMLInstance2Schema tool) to support empty string values.
(kvisco - 20030312)
XML: Fixed Bug 1232: The facet 'MinInclusive' was not handle properly for decimal
datatype.
(Arnaud - 20030225)
JDO: Fixed Bug 1165 : Castor closes connections too early with global transactions
(Mickael - 20030221)
XML: Fixed the handling of include in the binding file. Problem reported
by Brett Ramdeen [bramdeen@certapay.com]
(Arnaud - 20030210)
JDO: Fixed Bug 1151 : Use Complex primary key crashed
(Mickael - 20030207)
XML: Fixed issue when processing the annotations of element and attribute
references for creating Javadoc. If local annoations do not exist,
then the annotations from the referenced declaration is used.
(kvisco - 20030206)
XML: Fixed bug 1195: support for unbounded XML Schema int types was broken.
(Arnaud - 20030205)
XML: Source Generator: The '-type' command line parameter now allows a fully
qualified class name as an input. This class must extend FieldInfoFactory.
(Arnaud - 20030205)
XML: Fixed issue with attribute references and AttributeDecl#getUse()
incorrectly following the reference to obtain the value from the
referenced AttributeDecl. Attribute references specify the "use"
value, top-level elements do not.
(kvisco - 20030204)
XML: Fixed bug #1193: Decimal validation was not handling correctly min/maxExclusive.
Reported by ahoeltje@extensity.com
(Arnaud - 20030203)
XML: Fixed bug #1180: URIResolver wasn't resolving correctly the relative paths.
Patch submitted by Erik Ostermueller.
(Arnaud - 20030203)
XML: Fixed issue with AttributeDecl#getName not returning an NCName.
Added AttributeDecl#getReferenceName to return the full QName.
Also added ElementDecl#getReferenceName.
(kvisco - 20030129)
XML: Fixed bug #1182: Schema with no targetNamespace is producing
incorrect package information for member variables of enumerated
types. Reported by [bryan@skyauction.com].
(kvisco - 20030124)
XML: Added new options in the CTF XML to specify a binding file and to allow
the processing of several XML Schemas. Regenerate the CTF object model.
(Arnaud - 20030119)
JDO: Fixed bug #1184 Unprotected call to potentially null object
report by Graham Bygrave [Graham.Bygrave@BarclaysGlobal.com]
(Bruce - 20030122)
XML: Improved DateFieldHandler parsing routines. Removed the use
of SimpleDateFormat.
(kvisco - 20030119)
JDO: Added contribution from Thomas Olausson [thomas.olausson@home.se] to
fix DB2 identity columns.
(Bruce - 20030114)
XML: Added some initial support for xsd:list of xsd:QName
(kvisco - 20030113)
XML: Fixed bug 1115 : Arrays marshalled from Vector are unmarshalled as Vectors
(kvisco - 20030113)
XML: Added support for JavaNaming conventions to be configured to be
backward compatible with Castor 0.9.3.9
(kvisco - 20030111)
XML: Fixed bug 1169 : Error 'schema.noBuiltInParent' when constructing a
derivation of a simple type that is a 'list'. Patch provided by
Gilles Gaillard.
(kvisco - 20030111)
XML: Fixed bug 1167 : getElement wasn't always returning after correct element
was found. Patch from Gilles Gaillard.
(kvisco - 20030111)
XML: Fixed bug 976 : enums from imported schemas cause compile error
(kvisco - 20030109)
XML: Fixed bug 1138 : Wrong namespaces in generated code
(kvisco - 20030109)
XML: Fixed bug 1174 : Generated code for primitive fields and bound properties
is incorrect
(kvisco - 20030109)
XML: Fixed enh 1166: Added support for has-method specification in the
mapping file.
(kvisco - 20030108)
XML: Fixed bug 1077 : Bad handling of enumerated attributes from namespaces
different than element
(kvisco - 20030108)
XML: Added support to the SourceGenerator for reading the nspackages property
from the castor.properties instead of only castorbuilder.properties
(kvisco - 20030108)
JDO: Fixed Bug 1022 : Trouble with deleted items in RelationCollection$IteratorImp
(Mickael - 20030102)
JDO: Fixed Bug 1020 : Rollback of a transaction duplicates the contents of a container
(Mickael - 20021231)
JDO: Fixed Bug 985 : High/Low key generator problem in multi DB environment
Applied patch provided by Stephane Verlet [stephane@mminternet.com].
(Mickael - 20021231)
JDO: Fixed Bug 979 : Reuse of RelationCollection
Applied patch provided by Martin Renner [m.renner@exxcellent.de].
(Mickael - 20021230)
JDO: Fixed Bug 1163 : Lock conflict when loading an object present in the cache
(Mickael - 20021227)
XML: Fixed bug 960: Using enumeration in a restriction of <simpleContent> was producing
code that couldn't compile. This lead to modify the behavior of the Source Generator not
to extend classes that are representing a simpleContent restriction.
(Arnaud - 20021223)
XML: Removed mapping.xsd_sg!! With the introduction of the binding file code this
was no longer needed since a binding file can be used. Added mapping-binding.xml
contributed by Rhett Sutphin! Talk about a fast learner, Rhett became an
expert with binding files only a few hours after the feature was checked into CVS!
(kvisco - 20021221)
XML: Fixed bug 1049: the reading and writing of restriction under a simpleContent
element was not handle properly.
(Arnaud - 20021220)
XML: Fixed bug 1139: the minimum allowed size of a list was not set when using
Java 2 collections in the Source Generator.
(Arnaud - 20021220)
XML: Fixed bug 1117: the generated descriptors now refer to Castor classes by using
the fully qualified name. This prevent from naming collision when one is using
Castor class names in an XML Schema
(Arnaud - 20021220)
XML: Fixed bug 1146: generated validation code was not correct for the XML Schema
datatypes 'normalizedString'.
(Arnaud - 20021212)
XML: Fixed bug 1143: element reference, attribute reference, group reference
were not handle correctly when resolving the package in which to generate
the classes.
(Arnaud - 20021212)
XML: Checked in changes to javasource package for supporting inner classes.
These changes include some long-standing contributions from Gary Shea
and Martin Skopp. Much thanks to both for their contributions and
their *extreme* patience with me.
(kvisco - 20021212)
JDO: Fixed Bug 1030 : OQL query with timestamp comparison fail
into lexer, also updated doc
reported by Boris Boucher [boris@vibes.net]
(Mickael - 20021210)
JDO: Fixed Bug 1055 : SapDbQueryExpression has a problem,
reported by Clvis Wichoski
(Mickael - 20021210)
JDO: Fixed Bug 944 : mapping filename not relative to correct directory
(Mickael - 20021210)
JDO: Fixed bug #1111: Loading of LOBs
(Bruce - 20021209)
JDO: Fixed bug #1086: HIGH/LOW key-generator name does not pass validation
(Bruce - 20021206)
Misc: Updated the Ant build descriptor to properly construct
the CLASSPATH for use without the build script, added the
ability to override properties via a file in ${user.home} named
castor-build.properties as well as an echo statement if this file
is found, also added description to all targets for use with
Ant's -projecthelp option. Some of these changes were provided
by Michael Beauregard [michael_beauregard@transcanada.com]
(Bruce - 20021206)
XML: Made some changes to the configuration code. Added LocalConfiguration.java
to handle loading the Configuration. Can now distinguish between jar
defaults and local defaults. More work needs to be done with respect to
Configuration, but this was the first step.
(kvisco - 20021206)
XML: Added support for ValidationContext in TypeValidator and FieldValidator,
Sorry if this causes any issues with people who have written custom
validators, but the ValidationContext will allow future changes without
causing additional heartache.
(kvisco - 20021205)
JDO: Fixed Bug 1109 : Time limited cache is expiring too fast
(Mickael - 20021205)
XML: Fixed bug 1105: wrong validation code generated for xsd:float.
(Arnaud - 20021203)
XML: Fixed bug 1050: use fully qualified imports in the generated sources.
(Arnaud - 20021203)
XML: Fixed bug 1001: wrong wrapper types used in the generated functions.
(Arnaud - 20021203)
XML: Fixed bug 1078: cyclic inheritence in the generated sources.
(Arnaud - 20021203)
XML: Fixed bug 973: name collision with reserved SourceGenerator keywords.
(Arnaud - 20021203)
XML: Fixed bug 1096: Duration was not handling properly milliseconds.
Applied patch provided by Dick Lieber [rlieber@spss.com].
(Arnaud - 20021203)
JDO: Fixed Bug 942 : Transient fields fail to load in mapping
(Mickael - 20021203)
JDO: Fixed Bug 980 : PreparedStatement not closed in SQLEngine.delete
(Mickael - 20021203)
JDO: Fixed Bug 935 : Empty <sql/> elements in mapping.xml file
cause NullPointerException
(Mickael - 20021129)
JDO: Fixed Bug 997 : Exception during db.rollback() when db.update() fails
(Mickael - 20021129)
JDO: Fixed Bug 1119 : All table and field names converted to upper case
when using SAP DB
(Mickael - 20021129)
JDO: Fixed Bug 974 : JDO inheritance and cache conflict
(Mickael - 20021128)
XML: Integrated the Binding File. See bug 882 for more details.
(Arnaud - 20021128)
JDO: Fixed Bug #1046: rollback() destroys lazily loaded collections, thanks
to Martin Renner [m.renner@exxcellent.de].
(Bruce - 20021126)
JDO: Fixed Bug 891 : OQL CALL SQL fails with paren in WHERE clause,
should also fix Bug 1042, added CallSql test case
(Mickael - 20021122)
JDO: Fixed Bug 830 : OQLQueryImpl.finalize() method is unsafe
(Mickael - 20021120)
JDO: Fixed Bug 1114 : stack overflow bug with circular references
(Mickael - 20021119)
XML: Fixed bug 1110 : Regression in 0.9.4 when field type is an interface
(Mickael - 20021114)
JDO: Fixed Bug #1066 - OQL Bug and Patch: Non-ASCII characters in OQL queries
(Mickael - 20021114)
JDO: Fix for TC20 failure with mysql :
Timestamp precision loss after conversion to BigDecimal
(Mickael - 20021114)
XML: Added the '-printStack' command line option for the CTF XML. This option
allows to dump the stack trace on the System.out when an exception occurs
during the tests.
(Arnaud - 20021112)
XML: Some performance improvements in the marshalling/unmarshalling
framework.
(kvisco - 20021103)
XML: Integrated the GeneralizedFieldHanlder, to enable generic
FieldHandler's for a specific class type.
(kvisco - 20021031)
XML: Fixed Schema reader error when an given namespace URI is mapped
to mulitple prefixes.
(kvisco - 20021030)
XML: Fixed NullPointerException when using the ignore extra elements
feature.
(kvisco - 20021022)
XML: Fixed the default namespace regression issue with Schema object model
(kvisco - 20021017)
JDO: Fixed bug #973: Dependent objects deletion order problem.
(Mickael Guessant - 20021028)
JDO: Fixed test_item table in postgresql.sql, id column must be NULL,
caused TC28 to fail.
(Mickael Guessant - 20021028)
JDO: Fixed bug #1082: Container managed connections are not closed properly
(Bruce - 20021024)
XML: Fixed AnyNode writing: the sibling nodes (except for TEXT nodes) are no longer output
when writing an AnyNode. The string value of a AnyNode is now conform to XPath 1.0 specification.
(Arnaud - 20021014)
XML: Added option to generate extra collection methods from the source code
generator. These methods include getter/setter for the actual reference
to the collection. This makes the generated source code work better
with Castor JDO.
(kvisco - 20021013)
XML: Added ability to ignore extra elements upon unmarshalling.
Patch provided by John Weir.
(kvisco - 20021010)
XML: Updated XMLInstance2Schema to support better element/complexType handling
and improved datatype guessing.
(kvisco - 20021008)
XML: Updated XMLInstance2Schema to support attributes. Sorry for the oversight!
(kvisco - 20021008)
XML: Fixed bug 1052: the XML type resolution has been improved to take into account the targetNamespace
if any and the XML types defined in no namespace.
(Arnaud - 20021008)
XML: Fixed bug 1047: when resolving elements/types from an imported XML Schema, Castor will now
look into the XML schemas that are imported in the imported XML Schema.
(Arnaud - 20021004)
XML: Added UnmarshalListener interface provided by Paul Christmann [paul@priorartisans.com]
(Arnaud - 20021003)
XML: Handle 3-digit millisecond in the Time implementation.
(Arnaud - 20021002)
XML: Applied patch by David Cumberland [dcumberl@TRUELINK.com] concerning
DateTimeValidator
(Arnaud - 20020926)
XML: Added ability to disable xsi:type attributes when marshalling.
(kvisco - 20020917)
XML: Fixed a bug in SAX2ANY, when using SAX1 namespaces weren't correctly processed and added
to the AnyNode.
(Arnaud - 20020913)
XML: Added the support for URIResolver. The user can now specify to the Schema Reader
a behavior to resolve relative URIs used in the XML Schema being read. The introduction
of a default URIResolver implementation fixes numerous bugs in paths resolution when using
include or import.
(Arnaud - 20020913)
XML: Added the ability to pass a custom EntityResolver to the Schema Reader.
(Arnaud - 20020913)
XML: Fixed a bug in the resolution of XMLTypes in the Schema Object Model. An exception
was thrown when trying to resolve an XMLType that was not part of the Schema targetNamepace.
(Arnaud - 20020913)
XML: Added validation in the Schema Object Model to ensure that element references are
resolvable.
(Arnaud - 20020913)
XML: Fixed a bug that prevented the processing of an unknown type in the Source Generator.
A NPE was thrown.
(Arnaud - 20020913)
XML: Fixed NullPointerException issue with generated source code when
using bound properties in conjunction with default primitive values.
(kvisco - 20020905)
XML: NOTATION is no longer treated as a primitive type.
(Arnaud - 20020828)
XML: Added validation in the Schema Object Model to ensure that named complexTypes
and named groups are only used as top-level components.
(Arnaud - 20020823)
XML: Updated the JNaming class to use Character#isJavaIdentifierPart and
Character#isJavaIdentifierStart when determining a valid java identifier.
(kvisco - 20020823)
XML: Fixed issue with using add-method in conjunction with Hashtable and
Maps.
(kvisco - 20020822)
XML: Fixed problem with namespace usage and mapping file. If namespace
prefixed attributes existed for the root element, then a prefix was
getting erroneously created for the namespace even if a prefix already
existed for the namespace from the root element. I solved the issue by
moving the code for managing namespaces before the processing attributes.
(kvisco - 20020820)
XML: Fixed issue with using references and collections.
(kvisco - 20020816)
JDO: Cleaned up docs with patches Mark Woon (morpheus@SMI.Stanford.EDU)
and Erwin Bolwidt (erwin@klomp.org)
JDO: Updated PostgreSQL jar file to their latest (CVS) version.
Fixes timestamp bug. (Note: For the DataSouce class, use
org.postgresql.jdbc2.optional.PoolingDataSource instead of
org.postgresql.PostgresqlDataSource)
(Wolpert - 20020812)
XML: Fixed bug 990. Applied patch submitted
by Paul Noenning [Paul.Noennig@AndersenCorp.com]
(Arnaud - 20020809)
XML: Added support for clearing collections upon initial use. This
allows for removing default values, etc. To enable this
option, simply use Unmarshaller#setClearCollections.
(kvisco - 20020809)
XML: Added support for java.math.BigInteger.
(kvisco - 20020808)
XML: Patched issue with auto-naming and auto-complete in mapping file.
(kvisco - 20020808)
XML: Fixed bugs 969, 929, 910, 837
(Arnaud - 20020806)
XML: Fixed NullPointerException when importing a schema with no targetNamespace.
(kvisco - 20020806)
JDO: Updated MaxKeyGenerator so PostgreSQL (and MySQL) use quoted
sequence table/column names. (Patch submitted by user)
(Wolpert - 20020803)
JDO: Add type convertors for java.lang.Long<->java.util.Date. Patch
submitted by Mark Woon (morpheus@SMI.Stanford.EDU)
(Bruce - 20020802)
XML: Fixed issue with using elements as the identity field for HashMaps
and Hashtables.
(kvisco - 20020801)
XML: Enhancements in the SchemaWriter.
(Arnaud - 20020801)
JDO: Improved error reporting for malformed OQL queries.
(Bruce - 20020801)
XML: Better error reporting while reading an XML Schema.
(Arnaud - 20020801)
XML: Fixed issue with unmarshalling Hashtables and Maps when using element
fields as the identity.
(kvisco - 20020801)
XML: Added some initial patches to support unions. Not yet complete, but
better than nothing.
(kvisco - 20020731)
JDO: (doc) Improved JDO documentation by adding a doc on JDO Mapping
and by fixing numerous errors and clarifying statments throughout
many docs
(Bruce)
XML: Fixed bug 987. AnyType was wrongly processed when used in a complexType
restriction.
(Arnaud - 20020730)
JDO: Fixed bug #861 so that RelationCollection iterates correctly over
items marked for deletion. Fix submitted by Todd Rader [trader@saltare.com]
(Bruce - 20020712)
XML: Fix for binary (byte[]) errors when using node="text".
(kvisco - 20020712)
XML: Added Jim Moore's patch to fix an NPE in the MappingLoader and
throw instead a MappingException when the fieldType has not
been specified for array collections.
(kvisco - 20020709)
XML: Synchronized part of the Mapping#getResolver method for
thread-safety issues.
(kvisco - 20020708)
JDO: Fixed bug #995 to add support for multiple occurrences of the AS keyword
in an OQL query. Fix submitted by Shaun Kelly [shaun.kelly@bigpond.com]
(Bruce - 20020626)
JDO: Added SQL Server support to the JDO test. Ports submitted by
Patrick van Kaan [patrick.vankann@fortune-cookie.com]
(Bruce - 20020622)
XML: Report error when namespace URI cannot be resolved during
attribute processing (UnmarshalHandler).
(kvisco - 20020612)
XML: Checked in NullPointerException fix from Zsolt Kovacs for the
XMLInstance2SchemaHandler class. The fix makes sure the buffer
isn't null before we attempt to use it for guessing the type
for the element.
(kvisco - 20020612)
XML: Fixed bug 890
(Arnaud - 20020604)
XML: Fixed xml:lang support in mapping file
(kvisco - 20020603)
XML: Added support for mapping the type-safe enumerations that are
generated by Castor's SourceGenerator.
(kvisco - 20020528)
XML: SAX2 is used by default in the SourceGenerator. Added the sax1 option for
using SAX1
(Arnaud - 20020528)
XML: Fixed bug 896 ClassDescriptor inheritence issue
(kvisco - 20020521)
XML: Enhancements in Schema Reader / Writer
(Arnaud - 20020517)
XML: Added Glenn Nielsen's Patch for loading the Castor configuration
files in the proper order.
(kvisco - 20020429)
XML: Fixed problem with introspection of primitive arrays.
(kvisco - 20020427)
XML: Added support for saving and retrieving namespace node mappings from
the object model. Only applies when using a mapping file.
(kvisco - 20020419)
XML: Fixed bug 916 and other problems in the Validation code related to
generated classes.
(Arnaud - 20020418)
XML: Fixed bug 879: The generated classes now reflect the 'Restriction' inheritence
model for complexType as defined by W3C XML Schema
(Arnaud - 20020405)
XML: Added Unmarshaller#setAllowExtraAttributes method to allow control
over whether or not extra (non-matched) attributes should be flagged
as an error when using mapping files.
(kvisco - 20020325)
XML: Fixed null encoding issue in Configuration.java reported by Thomas Paradies.
(kvisco - 20020325)
XML: Removed unintentional filtering of 'xmlns' attributes.
(Andrew Fawcett 20020318)
XML: Added methods to Marshaller for setting schemaLocation and
nonNamespaceSchemaLocation.
(kvisco - 20020313)
XML: Added some support for SAX 2 in Marshalling Framework.
(kvisco - 20020309)
XML: Refactored the entire container support. A lot of changes have been
made during the Unmarshalling process and a method (canAccept) has
been added to the XMLClassDescriptor interface. These changes fix
bug #884 (and potentially many others)
(Arnaud - 20020306)
XML: Added initial support for Unmarshaller#setReuseObjects.
(kvisco - 20020227)
XML: Allowed to set the encoding of the serializer via the Marshaller
(Arnaud - 20020301)
XML: Fix bug# 886
(Arnaud - 20020219)
XML: Fix namespaces issue in the marhalling process
(Arnaud - 20020211)
ALL: Upgraded Jakarta Ant to version 1.4
(kvisco - 20020205)
ALL: Updated build system to Adaptx, removed XSL:P. Adaptx is the Exolab
version of my old XSL:P processor
(kvisco - 20020205)
XML: Fix bug with Namespaces and QName resolving in the Marshaller, the namespace
URI was not being properly declared.
(kvisco - 20020202)
XML: A number of small fixes to the Schema Object Model and SchemaWriter
(kvisco - 20020201)
XML: Added code to remove the xsi-type attribute when a mapping file is used
(Arnaud - 20020131)
XML: Make sure we marshal namespace prefixes for attributes when necessary
(kvisco - 20020130)
XML: Fix for contructor of Unmarshaller which takes a Mapping object, default
validate value was not getting set properly. (kvisco - 20020130)
XML: Fixed a bug that generated classes for "simpleContent" element
(Arnaud - 20020125)
XML: Added Rick Hogge's patch to the source generator that makes
java.lang.Object fully qualified to prevent errors when an element name
is "object" or "Object". (kvisco - 20020124)
XML: Improved Javadoc support - method names now use the Schema annotations for
their respective fields. (kvisco - 20020117)
XML: Added support for marshalling xsi:type using only Schema name, instead
of Java classname. (kvisco - 20020115)
XML: Added support in the Schema Object Model for 'union'. Union is not
yet integrated with the source generator. (kvisco - 20011217)
XML: Refactored the handling of wildcard in the Schema Object Model and
Source Generator (Arnaud)
XML: Added support in the Schema Object Model for 'remove' methods (Arnaud)
XML: Added support for timeZone in Marshaller and Unmarshaller (Andy Fawcett)
JDO: Fixed CALL SQL select parenthesis bug. (yip - 20020212)
Fix submitted by Glenn Nielsen [glenn@voyager.apg.more.net]
JDO: Fixed bug 870. ResultSet and PreparedStatement is not closed if interested
object is not found. Finally block is added to close the statement and rs.
(yip - 20020208)
Bug reported and solution is suggested by Jeffrey Wescott[jeff@saltare.com])
JDO: Added InstanceFactory. This interface defines custom instance
factory. If custom factory is set, instead of using java reflection,
Castor obtains an instance of data object using the set custom factory,
if needed during loading. (yip - 20020124)
Submitted by Alan Cabrera [adc@multex.com]
XML: Added support to the Schema Object Model for a number of XML Schema
attributes / properties such as elementFormDefault, form,
attributeFormDefault, abstract, id...etc that were previously not
read in from the XML Schema. Validation still needs to be updated,
as well as the source code generator (kvisco - 20011129, 20011205)
XML: Added support for the extremely powerful 'handler' attribute on
the field element for the mapping (kvisco - 20011205)
XML: Patch to XMLMappingLoader to fix dropped multiple id fields. This is a
actually a patch to fix bugs which occur in MappingLoader and an errant
implementation of ClassDescriptor (ClassDescriptorImpl). This fix should
be moved once we have consensus from both JDO + XML teams (kvisco - 20011204).
XML: Support for Identity-Constraints in the Schema Object Model and
SchemaWriter. Not yet supported in SourceGenerator (kvisco) 20011120
XML: Applied Nathan Green's patch to allow "all" option when prompting
to overwrite files during source code generation. (kvisco) 20011113
XML: A number of improvements to SchemaWriter (kvisco) 20011112
XML: Applied Glenn Nielsen's patch to allow double qoutes in default/fixed
schema values (kvisco) 20011111.
XML: Fixed bug that prevented elements that reference each other to generate
classes. It removes the StackOverFlow Exception. (Arnaud)
XML: Added code from Matt Small [msmall@clickability.com] that improves the SchemaWriter support (Arnaud)
XML: Fixed bug in the generated descriptors to correctly generate validation code when collections are used.
(Reported by Dr. Louis Coetzee [lcoetzee@subversion.icomtek.csir.co.za]) (Arnaud)
XML: Added QName support in the marshalling framework (when used via the mapping or via
the Source Code Generator) (Arnaud)
XML: Added special code to prevent creating a default XML name when using the "matches"
attribute for bind-xml element in the mapping file. (kvisco) 20010815
XML: Fixed bug with introspector...first character of field name was not being
decapitalized. This caused a bug in the "auto-complete" feature.
(kvisco) 20010815
XML: Fixed bug with "auto-complete" when specifying an identity field, the field
descriptor was not being set. (kvisco) 20010814
XML: Added support for specifying that a field is a reference using the mapping file.
(kvisco) 20010814
XML: Fixed bug in the generated classes: the attributes of complexTypes which contained
nested groups were wrongly located.
(Reported by Joseph Campolongo [jvc@cascadeworks.com]) (Arnaud)
XML: Fixed bug that prevented string-to-primitive conversion code from being
executed for identity fields (kvisco) 20010808
- Bug reported by Patric Bechtel
XML: Fixed bug which prevented IDREFS from working properly (kvisco) 20010807
- Applied patches sent in from Steve Vaughan
XML: Added code to Source Code Generator to create 'add(index, object)' method for list fields.
(andrew.fawcett@coda.com, Andrew Fawcett)
XML: Fixed bug with 'equals' implementation not being generated for classes representing <xsd:complexType>'s
(andrew.fawcett@coda.com, Andrew Fawcett)
XML: Fixed bug in 'equals' implementation, not calling super.equals(...) when approprite
(andrew.fawcett@coda.com, Andrew Fawcett)
XML: Fixed problem in Schema unmarshalling (when using both xsd:include and xsd:import),
allowing a given schema to be parsed a second time, resulting in duplicate type errors.
(andrew.fawcett@coda.com, Andrew Fawcett)
XML: Added an option (default is off) to expose the names of each attribute and element described in the class descriptor.
Use org.exolab.castor.builder.classdescfieldnames=true in castorbuilder.properties to enable
(andrew.fawcett@coda.com, Andrew Fawcett)
XML: Fix a bug in SimpleTypeFactory.
(Reported by Risheng Lin [rlin@eng.utoledo.edu]) (Arnaud)
XML: Add an option in the Source Generator that allows to use wrapper objects instead of primitives
(Eg java.lang.Double instead of double) (Arnaud)
XML: Fix a bug when handling attibutes in the UnMarshallerHandler (bug reported and
patch submitted by Marcin Chalotowski [Marcin.Chalotowski@3dart.com]) (Arnaud)
JDO: Fixed a old values appears in new result problem.
(reported by Jim Branecki [Jim_Branecki@sparta.com]
and Steven Lee [steven@lee-home.com])
JDO: Added setAutoStore to JDO and DataObjects (necessary for use in EJB environment). (oleg)
JDO: Fixed the rs.next() called more than one problem. (yip)
JDO: Fixed IllegalStateException when TransactionManager calls
afterComplete( Status.ROLLEDBACK ), without calling
beforeComplete() first. According to the JTA specification,
rollback can be one-phase.
(reported by Richard Monson-Haefel [Richard@intalio.com]
and Matthew Jensen [mmj@ceg.net])
JDO: Made the BatchUpdateSQL utility to take small letter "go" as end
tokens of a statements. (yip)
JDO: Added special care for Double/Float type to workaround a oracle's problem. (yip)
JDO: Splitted create() phase into two phases: markCreate() and create().
In the markCreate() phase, the object to be created is walked and all
objects that should be created are marked. Then, the marked object is
created in the order that is determined by getPriority(). After the
creation, object cache that related to other is updated.
(similar changes was made to update())
- The change is introduced to solve several problems related object creation.
(The old apporach try to delay the creation of dependent object to preStore
state, so that the master object is always created first. The master generated
key would be ready when dependent object are created at transaction prepare.)
bug 1: dependent's related object is not automatically created,
even if autStore set true. (with key gen used both side)
bug 2: 1:1 dependent relationship is not always done right, depends on which
side is the foreign key placed. (with key gen used both side)
bug 3: in some tricky suituation, created object cache is not updated. (yip)
JDO: Fixed a bug in the FieldMolder.isStored() method. (yip)
JDO: Fixed the problem with two 1:N relations between the same two tables (reported
by CORMONT Cedric [cedric.cormont@softeam.fr]). The solution is to use aliases
(when needed) in outer joins generated by SQLEngine. (oleg)
JDO: Restricted JDO to eat only ObjectNotFoundException now to workaround
inconsistent reference in database. (yip)
JDO: Fixed a NPE in TransactionContext.load().
(reported by Naveen Sharma [sharmn@sdd.comsat.com])
JDO: Fixed bug in JDBCQueryExpression.getSelect() that previously
was hidden in ancestors. (oleg)
JDO: Fixed a bug that caused PersistenceException("persis.typeMismatch")
to be thrown in ClassMolder.
(Bug reported by (Naveen Sharma [sharmn@sdd.comsat.com]))
JDO: Added type convertor of BigDecimal<-->Short and BigDecimal<-->Byte. (yip)
JDO: Fixed a deadlock problem.
(Reported and submitted by Holger Krug [hkrug@rationalizer.com])
JDO: Treated an SQL generation issue temporarily. When users write an OQL
contains two or more conditions on the same one-to-many relation,
s/he expects OQL to return the union of the two conditions, but it
is returning the intersection now.
(Patch submitted by Rehor Petr [petr.rehor@decros.cz])
JDO: Fixed a StackOverflowException. The Exception was caused by an infinite
loop in getPrority().
(Submitted by Mark Lamb [Mark.Lamb@spirent.com])
JDO: Fixed a problem causing unexpected ObjectModifiedException being thrown
when an object in one side of 1:1 relationship is being added via a long
transaction. (yip)
(Reported by Sharma, Naveen [Naveen.Sharma@lmco.com])
JDO: Fixed the default value not being used for primitives bug. (yip) 20011025
JDO: Fixed the 1:1 dependent object not being created when the it is newly
link, or replaced to the master object in both long and short
transaction. (yip) 20011025
JDO: Added support of read-only field for Castor JDO. Read only can be
enable setting read-only attribute to true inside sql element in
the mapping file. (eg. <field><sql read-only="true".../></field> )
20011029
(Patch submitted by Jakob Braeuchi [jbraeuchi@hotmail.com])
JDO: Enabled sql function in the "Order By" clause of an OQL. 20011029
(Patch submitted by Low Heng Sin [lowhs@comline.com.my])
JDO: Made compilable with javac 1.2.
[reported by BEDNARIK,LASLO laslo_bednarik@hp.com]
JDO: Fixed a problem that causes Castor JDO always requesting writeLock for a
data object with a lazy-loaded collection. (yip) 20011126
(bug reported by Dominik Baranowski [dbaranowski@saltare.com] and
Ned Wolpert [ned.wolpert@knowledgenet.com])
JDO: Fixed a problem that causes <field set-method="..."/> doesn't work.
20011130
(reported by Matthew Baird [matthew_baird@againtech.com]
patch submitted by Jakob Braeuchi [jbraeuchi@hotmail.com])
JDO: Fixed the integrity problem with many-to-many relationship.
(reported by many users...) (yip) 20011130
JDO: Made TxDatbaseMap implementing Serializable.
TxDatabaseMap must implement Serializable.
TxDatabaseMap is a member of JDO. (bug 792) 20011203
(Reported by Guenter Gartner[guenter.gartner@gillardon.de])
JDO: Fixed bug 801(b): bugs in RelationCollection.clear().
(yip) 20011203
(Bug reported by tysonsinger@metatv.com)
JDO: Fixed bug 801(a): bugs in RelationCollection.addAll() 20011203
(Bug reported and fixed by tysonsinger@metatv.com)
JDO: Fixed Bug 579: dirty="ignore" on sql fields in the mapping
file does not work. 20011203
(Bug reported and fix submitted by ryoder@q-markets.com)
JDO: Fixed a potential problem with lazy collection consistency.
If an object is removed from database, and the lazy collection
still link to it at the end of transaction, the cache would
still "think" the object is in the database in the next
transaction.
Although the test can detect that in some case, it is not
recommended to depends on this behavior. Always dis-link it,
before calling db.remove(). (yip) 20011204
JDO: Added sqldate and sqltime as supported field type. (yip) 20011204
JDO: Added timestamp as supported java field type. 20011204
(submitted by Markus Fritz [mfritz@justis.de])
JDO: Added try/catch to clear the _creating flag, which conserves the
internal consistency when exception was thrown. 20011204
(bug reported and fixed by Todd Rader [trader@saltare.com]
and Dominik Baranowski [dbaranowski@saltare.com])
JDO: Fixed a NPE which occurs when removing an data object with empty many-many
relationship. (yip) 20011205
(bug reported Jan Kanzleiter [mailto:idefix@tfh-berlin.de])
JDO: Fixed a problem which occurs when two long-transactional objects
are linked together in a many-many relationship. (yip) 20011205
(bug reported by Toni Charlot [toni@fdplus.com])
JDO: Fixed accessor not found problem for collection. (yip) 20011211
(reported by Patric Bechtel [bechtel@ipcon.de] and
Matthew Baird [matthew.baird@motiva.com])
JDO: (doc) Added FAQs for OQL and data model issues.
JDO: (doc) Corrected the PostgreSQL configuration example.
(Submitted by Todd V. Jonker [tjonker@inpathsol.com])
JDO: (doc) Added a FAQ for pass-thru SQL.
JDO: (test) Added a 2 second sleep in between the creation of the first
and second object. This is needed to make the test case run properly.
Because, some database stored time in less precision, and it causes
the test to fail. (yip)
JDO: (test) Used a new SQL connection in the inner class of the test to
workaround a problem in Solaris. (yip)
JDO: (test) Added test cases for dependent relationship where each of the data object
identity is key-generated. (yip)
JDO: (test) Enhanced error reporting for the Deadlock test case. (yip)
JDO: (test) Added test cases for more TypeConvertor. (yip)
JDO: (test) Added a test for 1:1 dependent relationship. (yip)
JDO: (test) Added a soak test for Castor JDO. (todo: adds build.xml entry) (yip)
JDO: (test) Added a test case for depedent objects with
key-generator used in long transaction. (yip)
XML and JDO: (doc) Fixed most of the javadoc warnings. (yip)
DSML: Fixed a NPE. 20011205
(bug reported and fixed by Gilbert Pilz [gilbert.pilz@e2open.com])
XML: Added fix to CollectionInfoJ2 for unbounded collections. (kvisco)
- reported by Julien Viet
XML: Added nested Exception support for SimpleTypesFactory (kvisco)
XML: Added nested Exception support for FieldHandlerImpl (kvisco)
XML: Fixed CollectionInfoODMG30, applied patch by Bernd Deichmann (kvisco)
XML: Added the auto-complete feature and transient field support to
the mapping file. (Sebastien Gignoux <gignoux@intalio.com>)
XML: Fix a bug that creates infinite loop when cross-importing
(or including) schemas(Arnaud).
XML: Added the support for the facets min/max Ex/Inclusive for the date/time
types and added complete implementation of date/time W3C XML Schema
datatypes (Arnaud).
XML: Added new supports for XML Schema Recommendation datatypes and remove
old references to the Candidate Recommendation document (Arnaud).
XML: Added push behavior for the unmarshaller with SAX producer. Made some
functions public and UnmarshalHandler final.
(Sebastien Gignoux <gignoux@intalio.com>)
XML: Remove the xsi:type when using the generated descriptors.(Arnaud)
XML: Support for the <any> element in the Marshalling Framework.(Arnaud)
XML: Added setRootElement method to Marshaller.java to override default root
element name for document. Usefull when using classes generated via
'type' mapping, as the root element name is not known.
(Andrew Fawcett, andrew.fawcett@coda.com)
XML: Fix the Marshaller to handle correctly Vector by keeping the
xsi:type information (Bug reported by Eric Kaplan
(eric.kaplan@armanta.com) (Arnaud)
XML: Fix the SourceGenerator to handle correctly the 'types' package
when a Date/Time type is used as an attribute.(thanks to
Maria Gray <maria.gray@datalex.ie>,
Christopher P. van Buskirk <Chris.vanBuskirk@vanderbilt.edu> and
Dean Thompson <dthompson@medebiz.net> for their proposed solutions) (Arnaud)
XML: Removed a dependency to xerces jar in Configuration.java
(Patch submitted by Marc-Antoine Parent <Marc-Antoine_Parent@Mitel.COM>
and committed by Sebastien Gignoux <gignoux@intalio.com>)
XML: Fix a bug in the validation framework. (Arnaud)
XML: Supports the <any> element in the Source Generator.(Arnaud)
XML: Support the wildcards <any> and <anyAttribute> in the Schema Object Model.
(Arnaud)
XML: Improved grouping support....now handles maxOccurs > 1. Nested groups
are no longer simply flattened. (kvisco)
XML: Added object container support. Handle element and attributes, as
well as container in container. Object container are object that
exist in the object model, but will not appear directly in the XML
document. There will be no element associated to this object, but
its child will appear in its parent element.
(Sebastien Gignoux <gignoux@intalio.com>)
JDO: Fixed a problem in HypersonicSQL driver in which it creates invalid
statements in case when there are mixture of outer joins and regular
joins. The problem relates to the table aliassing.
(Kesha Sibilev <ksibilev@powernetinc.com>)
JDO: Fixed an ObjectNotPersistentException in ClassMolder.preStore().
This method is trying to obtain write lock on the collection
instance instead of doing that on the actual object.
(Kesha Sibilev <ksibilev@powernetinc.com>)
JDO: Fixed when deleting an object which participates in the many-to-many
relationship the corresponding record in the relation table is not
being deleted problem. (Kesha Sibilev <ksibilev@powernetinc.com>)
JDO: Fixed the addMethod is not cloned for mutliple class loader enviorment
problem. (Ralf Purnhagen <purnhar@gmx.net>)
JDO: Fixed identity name in complex identities not being recongnized problem
by an OQLQuery. (Ted X. Toth <tedx@elegiant.com>)
JDO: Added support for aliases in generated SQL queries.
Before in some cases OQL queries were incorrectly translated into SQL.
(Thorsten Thielen <thorsten@ipcon.de>)
JDO: Shortened the name for aliases in generated SQL queries to
support database that allows limited columns name length.
(Thorsten Thielen <thorsten@ipcon.de>)
JDO: Added support for SQL functions in OQL queries.
(Thorsten Thielen <thorsten@ipcon.de>)
JDO: Fixed a bug which cause "remove(Object)" always return false.
(Steve Vaughan <snmvaughan92@yahoo.com>)
JDO: Fixed a problem that Castor JDO is trying to creates an related object
on the m side of a 1:m relationship when the object should be updated.
(Kim Madsen <kim.madsen@inceptor.com>)
JDO: Added SQL Direct Interface. Syntax:
"CALL SQL <sql expression> AS classname". The fields that are returned
with you sql query must be the same, as the equivalent OQL Query would do.
Tip: you may turn on Castor logging and study the generated SQL
statements. (Thorsten Mauch <mauch@imkenberg.de>)
JDO: Added the overdued <sql many-key="??"/> and <sql many-table="??"/>
attributes into the mapping.dtd file.
(reported by Vladimir Tsichevski <wowa@jet.msk.su>)
JDO: Fixed a AOBException in RelationCollection used by lazy loaoding.
(submitted by Steve Bate <mail@technoetic.com>)
JDO: Fixed a "too many open cursor" errors caused by JDBC statement not
released. (Submitted by Steve Bate [mail@technoetic.com])
JDO: Fixed an IllegalArgumentException being thrown the second time a value
or function query was bound.
(Submitted by Steve Bate [mail@technoetic.com])
JDO: Added IdentityKeyGenerator support for Informix.
(Submitted by David Tinker [david@hemtech.co.za])
JDO: Fixed an ArrayOutOfBoundsException occurs in lazy loaded collection's
iterator. (Submitted by Georg Schneider [h8825037@obelix.wu-wien.ac.at])
JDO: Fixed: Loading with "db-locked" mode is now always load from the
Database. (yip)
JDO: Moved the callback of storing(...) into TransactionContext.java. (yip)
JDO: Added the option for custom CallbackInterceptor. (yip)
JDO: Added an option to let users specify the instance of object to be
loaded into, in the Database.load(...) method. (note, only for
simple object with no persistence relationship) (yip)
JDO: Reduced the number of TimeThread used by Time-limited cache.
JDO: Fixed a bug that cause ObjectDeletedException being thrown at commit
time, for one-many and many-many relationship when an object on the
many side is deleted. (yip)
(reported by many people)
JDO: Fixed a many-many relationship update (long-trasaction) problem. (yip)
JDO: Rewritten a major part of ClassMolder.update(...) to better handle
one-many and many-many relationship with key-generator and update. (yip)
JDO: As part of the rewritten mentioned above, update is now behavior like
create if the TimeStampable.jdoGetTimeStamp return NO_TIMESTAMP if
autoStore is set true. (yip)
JDO: Added a final static variable TimeStampable NO_TIMESTAMP. (yip)
JDO: Added database to transaction association pooling.
This option only affects JDO if transactionManager is set and
a transaction is associated with the thread that call
getDatabase(). If jdo Database pooling is enabled, JDO will
first search in the pool to see if there is already a Database
for the current transaction. If found, it returns the database;
if not, it create a new one, associates it will the transaction
and return the newly created Database. (yip)
JDO: (misc) Added a BatchUpdateSQL utility to helps executing a batch
of sql create statements in the jdo test directory. (yip)
JDO: (misc) Ported test cases and test harness framework from JTF to
JUnit (yip)
JDO: (misc) Javadoc to test cases (yip)
XML: Added fix for collections, reported by Ozgur Balsoy. This bug was introduced
on March 8th, in the version 1.45 of DescriptorSourceFactory. (kvisco)
XML: Added fix for enumerated simpleTypes. When a simpleType restricted another
simpleType, if both types defined an enumertion facet with the same value
Castor wouldn't handle this properly. Bug reported by Stephan Goetter.
(kvisco)
XML: Added fix for generating source code using the element-method. Classes
were no longer extending their abstract type definitions. (kvisco)
XML: Add a command line property for the Source Generator to use the generated files in
the Castor Testing Framework(Arnaud)
XML: Add a property in castorbuilder.properties to generate a clean 'equals' method (Arnaud)
XML: Fix a bug concerning the handling of 'Enumeration' in inner elements (Arnaud)
JDO: Fixed some problems when two key generated related (or dependent) object creating in
the same transaction. (Thomas)
JDO: Relaxed the restriction so that a data object class can now extends one class and
depends another. (Suggested by Rimac, Ivica <ivica.rimac@KOM.tu-darmstadt.de>)
JDO: Fixed NPEs in TransactionContext, and ClassMolder in update(...). (Thomas)
JDO: Edited the New features document for Castor JDO. (Submited by Rick Horowitz <rickhoro@yahoo.com>)
JDO: Updated the oqlQuery tools. (Submited by Thorsten Mauch <mauch@imkenberg.de>)
JDO: Encapsulated and nested runtime exceptions generated while accessing the data object
into DataObjectAccessException. (suggested by Christian Sell <christian.sell@netcologne.de>)
JDO: Fixed a few bugs which some variables are mixed up in ClassMolder.
(submitted by Eldad Zamler<eldad314@netvision.net.il>)
JDO: Fixed NPEs introduced by autoStore. (reported by Steve Vaughan <snmvaughan92@yahoo.com>
and Patric Bechtel <bechtel@ipcon.de>)
JDO: Fixed bug: 1:1-dependent objects with key generator were not created on creation of master object.
(oleg)
JDO: Fixed bug: dependent collections with key generator where updated incorrectly
(reported by Ivica Rimac <ivica.rimac@KOM.tu-darmstadt.de>)
JDO: Added possibility to use in a query condition object references that correspond to sql field.
In this case the object of a persistence capable class should be bound as a parameter. (oleg)
JDO: Fixed bug: SQL types and order of fields in multi-column identities were handled incorrectly
(reported by Geoff Jacobsen <geoffj@casquet.inet.net.nz>)
JDO: Fixed bugs: readonly locking mode didn't work properly in some cases
(Damon Maria <damon@mahu-ika.com>, David J Snowsill <david.snowsill@calibreft.com.au>)
JDO: Fixed bug: conversions defined in a mapping configuration were not applied to OQL query parameters.
(oleg)
JDO: Added support for table names such as "user.tablename".
(Andrew Ballanger <AWBALLAN@smumn.edu>)
JDO: Fixed bug: object modifications were determined incorrectly in some cases.
(David J Snowsill <david.snowsill@calibreft.com.au>, oleg)
XML: Adding a new feature for handling all types of content and not only TEXT content (Arnaud)
XML: Change the read method name for arrays (Arnaud)
(bug reported by thebuledirt@yahoo.com)
XML: Several bug fixes in the SourceGenerator concerning the attribute string value (Arnaud)
XML: Added improved grouping support. Grouping support is not finished,
but is definately improved over Castor 0.8.11. 1st-level choice is
now supported. (kvisco)
XML: Added enumerate() method to generated enumeration types. (kvisco)
XML: Added support for specifying certain properties of the Introspector, such
as whether primitives should be treated as attributes or elements, and
default naming conventions. (kvisco)
XML: Updated mapping.xsd_sg to be compliant with latest XML Schema. (kvisco)
XML: Added support for DOM in Marshaller.java and Unmarshaller.java
(Andrew Fawcett andrew.fawcett@coda.com)
XML: Added setPolymorph method to Marshaller.java. This can be used to force all field values
to be marshalled as their field types rather than their instance types.
(Andrew Fawcett andrew.fawcett@coda.com)
XML: Changed the default behavior of the Xerces Serializer to preserve space
by default.
(Sebastien Gignoux <gignoux@intalio.com>)
XML: Added support for restriction in simpleContent and enhanced complexType support
(Arnaud <blandin@intalio.com>)
XML: Added the command-line option '-nomarshall' which aims at preventing the
generation of the marshalling framework specific methods (marshall, unmarshall, validate)
(Arnaud <blandin@intalio.com>)
XML: Added setNSPrefixAtRoot method. When used in conjunction with setNamespaceMapping this
will insert the namepsace declarations at the root node.
(Andrew Fawcett, andrew.fawcett@coda.com)
XML: Fixed collection handling for introspected class.
(Sebastien Gignoux <gignoux@intalio.com>)
XML: Bug fix for using addXxx methods.
(Fix submitted by Michael Thyen <mthyen@excite.com>)
XML: Bug fix in the handling of 'Map' collection. Now we use the abstract
'Map' interface rather than 'HashMap'.
(Fix submitted by Ron Smith <rsmith7209@yahoo.com>)
XML: Added some logic to avoid unnecessary use of 'xsi:type' when
marshalling. The logic check if Castor is able to find the proper java
class to instantiate from the mapping file information.
(Sebastien Gignoux <gignoux@intalio.com>)
XML: Solved a performance bug for unmarshalling of primitive type. We don't
try anymore to generate a Class Descriptor for primitive type as we know
that not only it fails but it is deadly slow (due to getMethods()
call). Now, unmarhsalling speed is nearly only bounded by the speed of
the parser.
(Sebastien Gignoux <gignoux@intalio.com>)
XML & JDO:
Check that an XML mapping file do not declare more identity attributes
for a given class than there are field elementsdefined for that
class.
(Patch submitted by Gabriel Richard Pack <gpack@electroneconomy.com>)
XML & JDO:
Regenerated data objects in the org.exolab.castor.mapping.xml package,
using an updated version of schema (Nov 2000).
XML & JDO:
Now the return type of get-method must be a super-class of or equal to
the class declared in mapping.xml (was: sub-class).
Note, that now "arraylist" can be used as a value of "collection"
attribute in mapping.xml
JDO: Bug fix when castor closed Connection during db.close() (before the end of
transaction) and the got new Connection during beforeCompletion(),
which remains open after the end of transaction.
(Solution submitted by Terry Child <tmchild@gmx.net>)
JDO: Castor JDO should now behave shamelessly in a multi classloader context.
This is especially relevant when used in a BMP/CMP environment where the
EJB container might assign a ClassLoader instance per set of Beans, or
might attach a different classloader for each new transaction.
(Sebastien Sahuc <ssahuc@intalio.com>)
JDO: Added an AutoStore option to JDO. Method of setAutoStore and isAutoStore
are added into the jdo.Database interface. If autoStore is set, Castor
will try to create or update** all reachable object if it is not
exist in the transaction, and store all reachable modified object at the
commit time. If autoStore is not set, Castor will only create/update/store
dependent object, and related objects must be created/update explicitly.
(* update is used for long transaction only, all modified object
created/loaded from the short transaction will be store properly
at commit time)
JDO: Added "trigger" mode for SEQUENCE key generator.
(Vitaly Shishakov <vitaly.shishakov@novalumen.com>)
JDO: Added support for MySQL auto_increment columns in IDENTITY key generator
(Oleg Nitz, thanks to Alain RAVET <aravet@cirb.irisnet.be> for idea
and to George Stewart <georgestewartiv@yahoo.com> for help).
JDO: Improved support for BLOB and CLOB values. Now you can get them as
java.io.InputStream and java.sql.Clob, respectively, see "types.html"
for details (oleg).
JDO: Solved problem of NULL dirty checking with Oracle (oleg).
JDO: Added support for BIGINT sql type in key generators (oleg).
JDO: Bug fix in the handling of classloader in the mapping loader (reported
by brian rogers <brian@freya.bianca.com>).
JDO: Added "serializable" as a supported field type. Require BLOB support in the
database. (Thomas Yip <yip@intalio.com>)
JDO: Merged JDO branch, "castorone", into the main branch.
JDO: Merged: Store cycle during transaction "prepare" state is split into
preStore and store cycles. With the new addition cycle, dependent object
using key-generator is stored properly. It also avoid unnecessary update
SQL statements execution. (Thomas Yip <yip@intalio.com>)
JDO: Merged: Added markModification in TransactionContext. It enable a
more flexible way to mark an object dirty. (Thomas Yip <yip@intalio.com>)
JDO: Merged: RemoveRelated is added in LockEngine. It automatically removes the
reference of the deleted object in other related object. It protect
cache consistency and avoid some ObjectNotFoundException due to
users' errors. (Thomas Yip <yip@intalio.com>)
JDO: Merged: Added Multiple Primary Keys support. (Thomas Yip <yip@intalio.com>)
JDO: Merged: Added Many-to-Many relationship support. (Thomas Yip <yip@intalio.com>)
JDO: Merged: Added Lazy loading for "collection" support. (Thomas Yip <yip@intalio.com>)
JDO: Merged: Improved dependent object support. (Thomas Yip <yip@intalio.com>)
JDO: Merged: Improved the in-memory locking architecture and stablity. (Thomas Yip <yip@intalio.com>)
JDO: Merged: Cleaned up excessive ExceptionImpl classes. (Thomas Yip <yip@intalio.com>)
JDO: Merged: Support of Object[] as a collection type is temporarily removed.
(Thomas Yip <yip@intalio.com>)
JDO: Merged: Support of custom ClassDescriptor for JDO side is no longer supported.
(Thomas Yip <yip@intalio.com>)
DAX: Merged: Tempoarily removed DAX. To be reworked and merged into JDO
(as new type of data-store). (Thomas Yip <yip@intalio.com>)
DSML: Add a more detailed policies :
* NewAttrOnly, which implies that new attributes are created according
to the DSML, but attributes that already have a value in the ldap are
not updated;
* UpdateOnly, which mean that DSML attributes that do not already exist
in the Ldap are not created.
Submitted by Marc-Antoine Parent <Marc-Antoine_Parent@Mitel.COM>
DSML: An ASCII string encoding bug is fixed.
Submiited by Marc-Antoine Parent <Marc-Antoine_Parent@Mitel.COM>
XML: Updated Schema syntax and some of the Schema Object Model to support
the W3C XML Schema Candidate Release. (kvisco)
XML: Allow the use of uninitialized collection. Castor will instiate a new
collection of the proper type when necessary. (seb)
XML: Added #setResolver method to Marshaller, thanks to George Stewart for
pointing out to me that I neglected to add this method. (kvisco)
XML: Changed name of xml element in the mapping.dtd to bind-xml. This change
won't effect any existing mappings yet, because I've added backward
compatibility support. (kvisco)
JDO: For HIGH/LOW key generator the paramater "global" has been added, it gives possibility
to generate globally unique keys (Oleg Nitz).
JDO: SAP DB driver, improved support for MySQL (Oleg Nitz)
JDO: Added possibility to close OQL queries in order to release resources (Oleg Nitz)
XML: Made the collection name in the mapping file NOT case sensitive. (Seb)
XML: Added new validation flag for the marshalling framework in castor.properties
Changed the parser validation property to og.exolab.castor.parser.validation
(Arnaud)
XML: Added fix to Marshaller#isPrimitive to support BigDecimal, submitted
by Don Kleppinger. (kvisco)
XML: Added "-nodesc" flag to source generater to disable generation of
class descriptors. Suggested by George Stewart. (kvisco)
XML: Fixed a bug in the unmarshalling of array of primitive type when using mapping.
(Seb <gignoux@intalio.com>)
XML: Added feature to castorbuilder.properties to allow specifying a super
class of generated types (kvisco)
JDO: SEQUENCE key generator for Interbase (contributed by Nic Wise <nicw@xerxes.co.nz>).
JDO: MySQL driver (contributed by Leonardo Souza Mario Bueno <leonardo@itera.com.br>).
JDO: Annoying type conversion problems solved:
- integer SQL type for Oracle now can be used for dependent objects
identities - before this caused type conversion error;
- timestamp SQL type can be used with Sybase - before dirty checking
failed;
- Database.load() now accepts identity value of the field type,
type conversion is performed correctly - before it was needed
to use the SQL type for Database.load(), but the field type
for OQLQuery.bind(). (Oleg Nitz)
JDO: Interbase driver (contributed by Terry Child <tmchild@gmx.net>).
JDO: Added UUID key generator.
(contributed by Thomas Fach <thomas.fach@publica.de>)
JDO: jdoBeforeCreate() callback method has been added to Persistent
interface. It is called during db.create() just before creating
object in the persistent storage (Oleg Nitz).
JDO: InstantDB driver (contributed by I. Burak Ozyurt <bozyurt@san.rr.com>).
JDO: Replacing of extended object in the cache on load of extending object
implemented. jdoLoad signature changed. Now in jdoLoad you can request
reloading the object instance as an instance of an extending class.
You need some "type" field in the extended class, which determines
the correct extending class, see example in
src\examples\myapp\Product.java. (Oleg Nitz)
JDO: Now IdentityKeyGenerator works with Hypersonic SQL identities
(idea by Mark Delanoy <mdelanoy@niku.com>)
JDO: Fixed bugs (contributed by Bill Reynolds <bill@leastsquares.com>)
- same OID for parent class instance and subclass instance
with the same identities causes cache corruption
- it is possible for a subclassed object to be reported as
non-persistable even if it has a legal mapping
- if you're using a class with the identity key generators and
no member fields, you get bad sql generated
JDO: Added support for LIMIT clause in OQL queries, currently for
PostrgeSQL only (contributed by Alexey Snisarenko <alex@plesk.com>)
JDO: Added JDO.setClassLoader(). (Oleg Nitz <on@ibis.odessa.ua>)
JDO: Fixed problem with Float/BigDecimal and Double/BigDecimal
type conversions. (Oleg Nitz <on@ibis.odessa.ua>)
JDO: Implemented algorithm of "bounded" dirty checking for long
transactions, it uses local timestamps and is works only
if the object is still in the cache at the end of the transaction.
See interface TimeStampable and Database.update().
(Oleg Nitz <on@ibis.odessa.ua>)
JDO: Changed HIGH/LOW key generator implementation: now holds lock
on the record in the sequence table until the end of the transaction
and doesn't use updatable ResultSets. (Oleg Nitz <on@ibis.odessa.ua>)
Fixed a gap in HIGH/LOW key generator implementation: with databases
that don't support "SELECT FOR UPDATE" (like Hypersonic SQL and
InstantDB) it was possible to get the same key values in two concurrent
transactions (Reported by George Stewart <georgestewartiv@yahoo.com>)
Now works in a separate connection, and commits changes to the sequence
table immediately.
JDO: Temporary fix to ClassLoader problem in EJB environment: application
classes are loaded using context classloader of the current thread.
(Oleg Nitz <on@ibis.odessa.ua>)
Misc: JDK 1.1 compatibility is back. (Oleg Nitz <on@ibis.odessa.ua>)
XML: Support for Bound Properties
XML: Added support for Pattern Facet
- currently works for string, integer, and long
(kvisco)
XML: Updated the Schema Object model to support the new Grouping syntax
- Groups are still not supported by the source code generator.
(kvisco)
XML: Updated Unmarshaller to support "empty" strings (kvisco)
XML: Added support for direct public field access for the Marshalling
Framework when no accessor methods exist. (kvisco)
XML: Fixed Marshaller#setMarshalAsDocument so that XML fragment marshalling
works again. This used to work, but changes to the serializers had
prevented this from working properly. Reported by Phil Grida. (kvisco)
XML: Fixed endless recursion bug when processing recursive element
declarations, reported by Chris Schaefer (kvisco).
XML: Added George Stewarts changes to give mappings higher priority than
generated descriptors
XML: Added Patrick Higgins changes to the javasource package to fix
support for abstract methods (kvisco)
XML: Added support for in-lines SimpleTypes (anonymous) for
attribute declarations (kvisco)
XML: Added support for in-lined SimpleTypes (anonymous) for
element declarations. (kvisco)
XML: Added Luis Arias upgrade for the maxOccurs attribute of elements
for the April xML Schema draft (kvisco)
XML: Added support for top-level annotations (kvisco)
XML: Made some changes in Unmarshalling code to handle "null" primitives.
Based on suggestions from Fabrice Gomez. (kvisco)
XML: Fixed a bug when Unmarshalling/Marshalling primitive Object wrappers
using dynamic-introspection. (kvisco)
XML: Changed some case-sensitive issues with the below mentioned Schema
syntax upgrade (kvisco)
XML: Update of the XML Schema syntax to the April 7th draft
(Remy Maucherat <remm@apache.org>)
The following things in the April draft are supported :
- datatype -> simpleType
- type -> complexType
- the "source" attribute has been replaced by "base"
- the "fixed" attribute in an attribute element now is
part of the "use" attribute
- the "default" attribute, which is used to specify the default
value of an attribute, now is "value"
- the "minOccurs" attribute of an attribute element has been removed,
the attribute "use" has to be used instead. "use" can have the
following values : default, optional, required, fixed and
prohibited
- Info element is now Documentation
- maxOccurs = "*" is replaced by maxOccurs="unbounded"
(Andrew Fawcett)
XML: Java 2 types compatibility (Patrick Higgins)
XML: <include> element support (Andrew Fawcett)
XML: decimal type support (Andrew Fawcett)
XML: Support xsi:type from XML Schema for Instances
(Remy Maucherat <remm@apache.org>)
XML: Added support for the Unmarshaller to automatically determine the Class of the
root element, based on a given Mapping, or ClassDescriptorResolver
XML: Added support for the "has" method for primitives in the generated source
XML: Added support for specifying the destination output directory for the
generated source code
XML: Added support for fixed attributes, this currently works for string
or integer values
JDO: Fixed bug: NULL value in database was read as 0 for Java wrappers
of primitive types (Long, Integer, etc.), now they are read as "null".
(Oleg Nitz <on@ibis.odessa.ua>)
JDO: Changed the inner SELECT syntax in MaxKeyGenerator to make it work
with Hypersonic SQL.
(Contributed by Santiago Arriaga <santiago@catnet.com.mx>)
JDO: Hypersonic SQL driver.
(Contributed by Santiago Arriaga <santiago.arriaga@catnet.com.mx>)
JDO: Changed KeyGeneratorFactory interface for better perfomance:
now the target primary key SQL type is passed to the key generator,
and no type conversions are performed after the key is generated.
(Oleg Nitz <on@ibis.odessa.ua>)
JDO: Added support for attributes of application type and for nested
attributes. Assume that you have an attribute "balance" of
applicatation type "Balance" which has methods "getBigDecimal"
and "setBigDecimal", then you can write in mapping.xml
<field name="balance.bigDecimal"...
and Castor will get and set the attribute value as
getBalance().getBigDecimal() and getBalance().setBigDecimal(value).
Note, that getBalance() may be null, in this case when setting
a non-null value Castor will first do setBalance(new Balance()),
and then getBalance().setBigDecimal(value).
Another example of usage of the this feature is attribute "address"
with nested attributes "country", "zipCode", etc.
These attributes also may be of application type or nested, e.g.
<field name="address.country.string"...
(Oleg Nitz <on@ibis.odessa.ua>)
JDO: Small fix: now fields in mapping.xml may have no "sql" sub-element,
e.g. the field may be only for XML marshalling, other fields
may be persisted through JDO. (Oleg Nitz <on@ibis.odessa.ua>)
JDO: "CALL" OQL queries now work with Oracle stored functions
returning REF CURSOR (Oleg Nitz <on@ibis.odessa.ua>)
and PostgreSQL stored functions returning instance
(contributed by Rostislav Beloff <ros@domainforfree.com>)
JDO: Added type convertors BigDecimal <-> Boolean
(contributed by Markus Fritz <mfritz@justis.de>)
JDO: Fixes multiple request of same object with DBLocked
(Oleg Nitz and Markus Fritz)
JDO: Changes to Persistent interface enable developer to use database
operations inside jdoStore, jdoCreate, jdoRemove.
(Oleg Nitz <on@ibis.odessa.ua>)
JDO: Cache control at JDO configuration and mapping file specification -
no-cache option, cache count limit, cache time limit, LRU removal
deamon (Thomas Yip <yip@intalio.com>)
JDO: Bug fix: for created objects fetch() returned oid instead of object
(contributed by Chris Stevenson <chris@ssabsa.sa.gov.au>)
JDO: SQL Date types handling is improved.
(Oleg Nitz <on@ibis.odessa.ua>)
JDO: Bug fix: small bugs w/ BETWEEN in parser...reported by Vladmir Sekissov.
(<nissim@panix.com>)
JDO: fix string conversion to surround with ' and escape internal ' fix for
bug with like. (<nissim@panix.com>)
JDO: Informix JDBC driver. (Contributed by Santiago Arriaga
<santiago.arriaga@catnet.com.mx>)
JDO: SEQUENCE key generator now works with Oracle. It has a special
RETURNING mode for Oracle8i which is more efficient because
obtains the identity during INSERT, without any additional SQL queries.
(Oleg Nitz <on@ibis.odessa.ua>)
JDO: Added three paramaterized type convertors: Date<->Integer,
Date<->BigDecimal and Date<->String. The latter uses the SimpleDateFormat
patterns (e.g. char[MMM d, yyyy]). The others uses similar
but shortened patterns (e.g. numeric[YMDhmsS], which is equivalent
to "yyyyMMddhhmmssSSS" SimpleDateFormat pattern).
(Oleg Nitz <on@ibis.odessa.ua>)
JDO: Fixes to handling of dependent objects create/delete/modify during
transaction commit. (Oleg Nitz <on@ibis.odessa.ua>)
JDO: Added convertor from byte to short/integer. (Contributed by Harindranath P. R. Nair
<hari.nair@alopa.com>)
XML: Identity field will now use XML name provided in mapping file.
XML: Marshaller will now accept both primitive and non-primitive types and apply the
proper conversion; no dropped in convertor used, so Date/byte conversion should
work as expected; added test case for type handling of XML. (Bug reported by
Eitan Suez <eitan@uptodata.com>)
Misc: Fixed security bug when running as an Applet. (Reported by Remus Pereni
<remus@nolimits.ro>).
Misc: Added support for Java 1.2 Collection by running the source generator with the
option '-types j2'. Vectors are used with 'j1' and ODMG 3.0 DArray with 'odmg'.
XML: Added support in the Marshaller to specify whether or not to marshal
as an XML document, or just an XML fragment (default). Currently
the only difference is the XML declaration is printed when marshalling
as a document. I will add support for specifying the DOCTYPE. Of course
since a SAX 1.0 DocumentHandler doesn't allow this, DOCTYPE and
XML declarations will only be printed when a Writer is used.
XML: Added support in the unmarshaller for better inheritence checking.
If a FieldDescriptor is not found for an element, an attempt to
obtain ClassDescriptor will occur for the given element. If found,
another check will be performed to find a FieldDescriptor that
describes a field which is a superclass of type described by the
class descriptor. (see src/tests/xml/Inheritence.java)
JDO: Added support for paramaterized type convertors. Currently supported is boolean
to char convertor using T/F character values (e.g. char.01 or char.TF). More
convertors and parameter specification will be added in 0.8.7. (Oleg Nitz
<on@ibis.odessa.ua>)
JDO: Fixed bug when related object is null and SQL_OTHER type is passed to JDBC
driver; now properly passes type of identity field. (Reported by
Eitan Suez <eitan@uptodata.com>).
JDO: Fixed bug with dirty checking that caused lock to not be acquired and object
to be deleted if modified, and now properly reporting modified value of object.
JDO: Fixed the way in which null fields are handled, so has/delete methods are called
if available, default value is used otherwise, setNull/wasNull are used on the
JDBC record.
JDO: Changed callback sequence. jdoRemove is now called on deleted objects,
unsetDatabase on objects that become transient (including those removes).
setDatabase is called whenever the object becomes persistent (that is,
used in a transaction) and passes the database to support lazy loading.
JDO: Fixed SQLTypes to pick up proper SQL type form field of type java.util.Date.
Fixed SQLEngine to use SQL type in some calls to setObject.
(Contributed by Donald Ball <balld@webslingerz.com>)
JDO: Added quoting to column and table names to support white spaces and keywords
(Only Postgres, Sybase and SQL Server).
Mapping: Added a match attribute for the xml element, this is used for allowing
better inheritence support. Setting this match attribute will restrict,
or extend the xml names matched by a given XMLFieldDescriptor.
Mapping: Added resetValue() method to field handler. This generally resets a field to
it's default value or empties a collection field.
Mapping: Date type no longer defaults to new date() when field is null, field is no
longer set to default when null. (Reported by Lincoln Spiteri
<Lincoln.Spiteri@mobisle.com>)
Mapping: Fixed mapping loader to complain if get/set methods are not found. Both are
required to be present, unless a collection field is used which only requires
a get method. (Reported by Lincoln Spiteri <Lincoln.Spiteri@mobisle.com>)
Mapping: Added convertor between String and character. (Reported by Donald Ball
<balld@webslingerz.com>)
Mapping: To fix problem with compiled class descriptors for XML and mapping file for
JDO not working together, mapping loading will not attempt to load class
descriptors. A permanent fix will be included in 0.9 or 1.0.
(Patiently reported by Andrew Ikon <aikon@niku.com>).
Mapping: Fixed collection handler to work with arrays of any object type (e.g. strings).
JDO: Remove enumerate collection type. Only get method is required to support
java.util collections, get/set methods to support arrays. Extended the
CollectionHandler interface with size() method to assist in validation.
JDO: Revised the CacheEngine towards dependency support, adding FIFO list to
determine order of object removal, simplifying the prepare stage. Objects
will now be removed from the database in the same order they were removed
by calling Database.remove().
JDO: Fixes to outer query expressions:
- JDBCQueryExpression fixed and tested with Access (Christopher
Elkins <celkins@scardini.com>)
- OracleQueryExpression fixed not tested with Oracle
(Sebastien Sahuc <ssahuc@imediation.com>)
JDO: Now using new OQL parser by default. Added support for is_defined/
is_undefined (IS NULL), BETWEEN and DISTINCT. (Nissim
<nissim@panix.com>)
JDO: Added convertor between java.sql.Date and java.util.Date
(reported by <Lincoln.Spiteri@mobisle.com>).
JDO: Improved type convertion for key generators. MAX key generator now
should work with PostgreSQL. (Oleg Nitz <on@ibis.odessa.ua>)
JDO: Added support for stored procedures in OQLQuery. Now it is possible to
create queries of the form "CALL sp_something($) AS myapp.Product",
where sp_something is a stored procedure returning one or more
ResultSets with the same sequence of fields as Castor-generated SELECT
for the OQL query "SELECT p FROM myapp.Product p" (for objects without
relations the sequence is: identity, then all other fields in the same
order as in mapping.xml). (Oleg Nitz <on@ibis.odessa.ua>)
XML: Support for ODMG 3.0 DArray collection in the XML source code generator.
When running the source code generator with the FieldInfoFactoryODMG30
collection fields will use org.odmg.DArray as the collection type for
interoperability with OODBMS using the ODMG 3.0.
(Contributed by Frank Thelen <frank.thelen@poet.de>)
XML: Added some namespace support to the XML Schema reader. It currently doesn't
properly handle namespace scoping as you go down the tree, so if you are
changing your namespace declarations for some reason on sub-elements it
probably won't work properly and you'll need to wait until Monday when I
finish it up.
XML: Fixed problem when using attributes that are of enumerated datatypes,
the types subpackage was not getting imported (reported by markd@lutris.com)
XML: Fixed problem when using enumerated datatypes with enumeration values
that contained Java keywords (reported by markd@lutris.com)
Misc: Support for Java 1.2 collections: Collection, Set, Map. Requires Java 1.2
to compile, but using reflection can be made to work on Java 1.1.
XML: Fixed a ClassLoader issue with the ClassDescriptorResolver
XML: Added validation back into the generator sources
XML: Added some changes from Frank Thelen to allow subclassing FieldInfoFactory
XML: Fixed bug that occured when an enumeration uses uppercase values
XML: Fixed bug with using datatype
JDO: Where clause now supports:
- unary operators: +, -, abs, not
- binary operators: +, -, *, /, mod, ||, LIKE, >, >=, <, <=, =, !=, and,
- parenthesis: passed through to SQL as in OQL
- numbered parameters including user specified type support
(Nissim <nissim@panix.com>)
JDO: Fixed bug in Database when used as sychronized resource in a J2EE environment.
Calling close() will not rollback the transaction until the J2EE server has
completed two-phase commit and notified it. Database must be registerd with
a JTA transaction manager using the setTransactionManager option.
JDO: Fixed bug in key generator when using non-primitive value (e.g. Integer, String).
Previously SQLEngine create was never called, now it is called and object properly
recorded in transaction.
Mapping: Fixed bug that caused exception with inheritance, now inheritance works
correctly if classes are specified in proper order in the mapping file.
(Oleg Nitz <on@ibis.odessa.ua>)
Tests: Updated test cases, now includes test cases for key generators.
(Oleg Nitz <on@ibis.odessa.ua>, Arkin <arkin@exoffice.com>)
JDO: New OQL query engine. Not used by default, see new methods in OQLQueryImpl
and package org.exolab.castor.jdo.oql.
JDO: Added support for null fields by calling the relevant setNull() method
when setting a null field. Does not apply to query parameters yet, does
not apply to identity fields.
JDO: Added key generators support. Implemented four algorithms:
"MAX" - generic "MAX(pk) + 1" algorithm;
"HIGH/LOW" - generic "HIGH/LOW" algorithm (extendible);
"IDENTITY" - "SELECT @@identity" for Sybase and SQL Server;
"SEQUENCE" - "SELECT nextval('..._seq')" for Oracle and PosgreSQL;
JDO: Added package org.exolab.castor.jdo.drivers which includes RDBMS specific
factories, query expressions and key generators. Added factories for DB2,
and SQL Server.
Misc: Added support for hasXXX()/deleteXXX() methods to determine if a value
exists when the value is a primitive (thus, cannot be null). Used by both
JDO and XML.
Misc: Fixed null pointer exception with collection handler. Deprecated
checkValidity on field handler (new validation code from XML will come
shortly).
JDO: Added and tested outer joins.
Persist: Added getIdentity() method to TransactionContext().
Misc: Modified the test harness to run from an XML test file. Added test case
for type handling (only null fields at the moment) and outer joins.
JDO: Added experimental update() method to Database interface.
JDO: Fixed some minor glitches in support for exclusive and db-locked
access, documented the available access modes.
JDO: Fixed synchronization support, disabled checkpoint method.
Fixed bugs in handling of default field values.
JDO: Fixed circular exception problem in ObjectLock.release.
(Contributed by Jason Weistein <jasonw@reticular.com>)
Misc: Documented the locking options in Castor and concurrency support.
Added the three locking mode to all the test cases.
XML: Fixed long->object conversion which suffered from a cut and paste bug
from the integer type.
XML: Added back inheritence support inside XMLClassDescriptor,
which was in MarshalInfo, but removed during the upgrade.
XML: Fixed bug with creating default XML name in XMLClassDescriptorImpl
XML: Fixed bug with unmarshalling primitive String types.
-- reported by Remy Maucherat and Kevin Burton
XML: Fixed bug with namespace support during marshalling of primitive
and immutable types
XML: Added back namespace support, which was temporarily removed during
the upgrade
JDO: Added Locked mode to provide locking at the database level, as
opposed to Exclusive mode which provides locking at the cache
level. Added support for loading/querying with a given access mode.
JDO: Improved concurrency for shared mode by eliminating write locks when
modified field is not marked as dirty.
JDO: Added isOpen method to database. Deprecated checkpoint.
JDO: Added preliminary support for controlling cache size and removing
objects from cache.
JDO: Fixed bug in bind( String) method of OQLQuery.
JDO: Fixed bug with modified exception not removing copy from cache.
JDO: Fixed bug with reusing queries.
Misc: Upgraded test cases to run inside JTF as a test harness.
XML: support for IDREF/ID has been added back in
XML: fixed circular reference bug
- This was an indirect bug caused by a bug
in org.exolab.castor.util.Stack
XML: fixed bug in method naming when type is "ID"
XML: Updated the Source code generator to work with new Framework
- Note I currently removed validation support, this will be
back ASAP
- There is a known bug with using "binary" type...I'll have
this fixed ASAP also
XML: We are now one step closer to using the mapping files with
Castor XML. A lot of changes have gone into sharing the "descriptor"
framework between Castor XML and Castor JDO...I can't enumerate all
the changes in this log, but here are a few:
- MarshalInfo and MarshalDescriptor have been changed to
XMLClassDescriptor, and XMLFieldDescriptor respectively, and the
interfaces have changed so be careful
- We added the XMLFieldHandler
- Changed MarshalInfoResolver to ClassDescriptorResolver
JDO: Placed the ODMG API in the org.exolab.castor.jdo package,
to be included in the JavaDocs and to enable the introduction
of Castor (RDBMS) specific features.
JDO: Moved transaction handling into the Database interface, queries
are now created from the Database object, JDO servers at the
implementation factory.
JDO: Added preliminary support for many-many relations, improved
support for one-many relations, fixed bug in isModified with
relations.
JDO: Added support for pluggable SQL engines (PersistenceFactory),
listed in the Castor properties file and referenced from the
JDO configuration file, allowing each database configuration
file to select the most suitable engine.
JDO: Extended JDO configuration file to include engine name, plus
minor modifications to element and attribute names in DTD/Schema,
and documentation of the configuration file.
JDO: Upgraded to use QueryExpression to construct SQL query statements
in database specific syntax.
JDO: Implemented dirty checking on objects loaded with a shared lock.
Dirty checking performed on fields within UPDATE statement requiring
a single SQL operation to update/check dirtyness.
SPI: Added QueryExpression and KeyGenerator to the SPI. QueryExpression
is generated from PersistenceFactory. Added way to load factories
from the Castor properties file.
Persist: No longer supports identity changes.
Persist: Rollback of transaction no longer reverts object to their previous
state due to lock race condition that hampers efficiency. Eliminating
this feature improves concurrency with optimistic locks.
Misc: Documentation distribution includes API JavaDocs and JavaDocs for
all Java classes. Tarball/zip include just the API JavaDocs.
Web site has been revised accordingly and some links moved around.
Misc: Updated build.xml file now includes documentation in tarball and
zip, builds both API JavaDocs and all classes JavaDocs, and does
not include package.html files in JARs.
This will generate a set of source files from the the XML Schema foo-schema.xsd and place them in the package com.xyz.
To compile the generated classes, simply run javac or your favorite compiler:
Created class will have marshal and unmarshal methods which are used to go back and forth between XML and an Object instance.
The source code generator has a number of different options which may be set. Some of these are done using the command line and others are done using a properties file located by default at "org/exolab/castor/builder/castorbuilder.properties".
There's more than one way of specifying the input for the Castor code generator. At least one input source must be specified.
The source code generator has the ability to use the following types of collections when generating source code:
You can also write your own FieldInfoFactory to handle specific collection types. All you have to do is to pass in the fully qualified name of that FieldInfoFactory as follows:
No, Castor JDO doesn't comply with the SUN's JDO specification.
Although Castor JDO carries very similar goals as SUN's JDO, it has been developed independently from the JSR.
Although it is not impossible to shape (perhaps "hammer" is a more descriptive verb) Castor JDO into the SUN's JDO specification, there are several major technical differences which make it unfavorable to do so. Castor is RDBMS centric. Each persistence object loaded by Castor is locked. Locks in Castor are observable, meaning that locks may not be granted because of timeout or deadlock. On the other hand, the SUN's JDO hides details about locks.
Internally, Castor JDO maintains a single copy of lock (and cache) for each active persistence object for all transaction. SUN's JDO specification implicitly requires a copy of cache per object per transaction. SUN's JDO also implicitly requires a bytecode modifier which Castor doesn't require.
Castor also provides other features, such as key generators, long transaction support and OQL query which cannot be found in SUN's JSR.
The relation between JDO and EJB Container-Managed Persistence is more complicated than simply saying, "one is better than the other".
An Entity Bean may manage persistence itself - the EJB specification calls this Bean Managed Persistence (BMP). Alternatively, the Entity Bean may rely on an EJB container to manage all peersistence automatically - the EJB specification calls this Container Managed Persistence (CMP). When implementing BMP, an Entity Bean may use Castor JDO as its persistence mechanism, or it may use others methods, such as dealing with JDBC directly. During CMP, an EJB Container vendor may implement their CMP on top of Castor JDO. In such an implementation, Castor JDO will be used to persist the Entity Bean.
If a developer would like to take advantage of an EJB's life-cycle management, security, the "write once deploy anywhere" promise and other distributed business application facilities, then EJB will be the right choice. Otherwise, the fact that Castor is simple, is Open Source (you can always include Castor in your application or product), has much less overhead, provides more design freedom, and is integrated with Castor XML may be enough of a reason to choose Castor JDO.
No. The decision of putting XML and JDO together is NOT intended to make XML marshalling transactional. Instead, the integration is done to help developers of a typical client-server situation whereby an application server receives incoming XML messages, process the messages and replies to the client.
With Castor, incoming XML messages can be unmarshaled into data objects. Required information can be obtained from a database using JDO in form of data objects. With this approach, all data manipulation can be done in an object-oriented way. Changes to JDO data objects can be committed transactionally, and result data objects can be marshaled into XML and returned to the client.
No, Castor does not provide an OQL query facility on a XML file. If querying is important for you, you should consider using a DBMS to store your data instead of using XML files, especially if querying performance is a concern.
Another alternative is parse an XML Document directly and use XPath to retrieve Nodes and/or NodeSets from an XML Document. Other open source tools which provide this functionality are:
Download the full SVN snapshot and look into the src/tests/jdo directory.
It cannot be used with Castor, because it doesn't allow more than one open ResultSet at the same time. Either use JDBC driver of type > 1, or use some other JDBC-ODBC bridge without such a restriction (for example, from Easysoft).
You should initialize the Collection yourself:
In general, no. If you need some behavior that is not directly supported by Castor, you can implement interface org.exolab.castor.jdo.Persistent. In order to use dirty checking for long transaction you should implement interface org.exolab.castor.jdo.TimeStampable. If you need an example of use of these interfaces, see Persistent.java and TestPersistent.java among Castor JDO tests.
First of all, let's agree upon terminology. We distinguish dependent and independent objects:
However, with Castor 0.8.x you cannot describe explicitly the kind of object. Instead, the following rule applies: if you have one-to-many relation, and each side of the relation refers to another (Collection attribute on "one" side, simple attribute on "many" side), then "many" side is a dependent object. All other objects are independent. In particular, related objects via one-to-one relation are not created/removed automatically.
With Castor 0.9 dependent objects should be described via "depends" attribute of "class" element in mapping configuration file.
If you wish some independent object was created and/or removed automatically on operations on other independent object, you may use interface Persistent to code the desired behavior.
No, Castor JDO doesn't have any built-in JDBC resource pooling. However the framework can transparently use any resource pooling facilities provided through DataSource implementation or -even better- through JDNI. In fact we even recommend people to use some Connection and PreparedStatement pool with Castor as this can increase Castor's performance 3-5 fold.
For example the following set of statements:
will be executed in much less time with the resource pooling because it
will avoid creating a new physical JDBC connection at every execution.
With Oracle, instead of specifying the usual JDBC driver you can use a DataSource that specifically provides some Connection caching/pooling.
Thus if your jdo config file looks like :
then it can be changed into (for example):
When Castor is used inside a Container such as an EJB container (within BMP or Session Bean), then the Container usually provides the JDBC resource through the JNDI ENC, which implicitely includes pooling facilities.
Probably castor.jar file is in jre/lib/ext directory. In this case
you should call:
jdo.setClassLoader(getClass().getClassLoader());
before jdo.getDatabase().
In this case as well as in many others you can get more information with the help of logging. Call:
jdo.setLogWriter(Logger.getSystemLogger());
and seek in the output for warnings and errors.
You should not add/remove dependent objects directly. In order to add/remove the dependent object you should just add/remove it from the collection in the master object and call db.commit()
Dependent objects cannot be created/removed explicitly. It's created automatically when it is added to a master object, and removed automatically when it de-linked/dereferenced from a master object.
Otherwise, we will be encounter into problem where a dependent object created explicitly but removed implicitly (delinked from a master object), or vice versa. It can also lead to other problems that are harder to detect.
It is recommended to replace literals with parameters and to set them via OQLQuery.bind(), for example:
$2 AND married=$3");
query.bind("John %");
query.bind((new SimpleDateFormat("yyyy-MM-dd"))
.parse("1960-01-01"));
query.bind(false);
]]>
Your JDBC driver is not JDBC 2.0 compliant, upgrade it or find another one.
Typcially a relationship between two objects is either one-way (aka uni-directional) or two-way (aka bi-directional). Officially, Castor currently only supports bi-directional relationships. For example, if an Order object contains a reference to a LineItem object, the LineItem object must contain a reference to the Order object. However, this requirement is not enforced in all situations.
This is a very complex problem to solve. So until Castor is expanded the support uni-directional relationships, the best policy is to implement the bi-directionalality for all relationships. This will ensure proper functionality.
This is a very common occurrence in an object model and is known as a self-referenential relationship. Unfortunately, Castor does not currently support self-referential relationships. An example of such a relationship occurs when a Folder object contains a reference to another Folder object. Castor does not currently support this. However, there are ways around this limitation.
One way is to manage this type of relationship manually. For example, let's say that a parent object FolderA needs to hold references to child objects FolderB, FolderC and FolderD. The Folder object contains not only a property to hold its own id, but also a property to hold its parent id (we'll call this parentId). The parentId property is used to determine if there is a relationship to another Folder object. If parentId is null, there is no relationship. If parentId is populated, there is a relationship and the object tree can be walked by comparing the object id to the parentId. When the two properties are equal, you're at the top of the tree.
Another say to solve this problem is to make use of an intermediary object. For example, a Folder object contains a Reference object in lieu of the actual Folder object. The Reference object is somewhat of a proxy object whereby it only contains enough information to identify the object to which the Reference object refers. Then the Folder object can be easily instantiated via the information contained in the Reference object.
The dirty checking engine will throw an ObjectModifiedException when the values in the cache and in the database are different. This can happen when someone else changed the database content, but also when type mapping is not reversible.
For example, if a java timestamp (java.util.Date) is stored as a DATE, the time part is lost and the dirty checking will fail. Oracle cannot tell the difference between an empty String and a null value: if an attribute value is an empty String, dirty checking will also fail. Some precision loss sometimes occur with floating point numbers.
To avoid this, always use reversible mapping conversions. If this is not possible, mark the fields with dirty="ignore" in the mapping file.
When using Weblogic Portal 4.0 with Oracle I am receiving the following error:
According to
Weblogic Release Notes,
this error can remedied by setting a Weblogic environment variable.
Most probably the object that is being updated has more than 100 related
objects of one class and the cache size for this class is not enough.
You should either increase the size of the cache or change the cache type
to time-limited (the default cache type is count-limited, the default
size is 100), for example:
As of release 0.9.5.3, you cannot. When using a cache of type 'none' with your 'Timestampable' objects, a MappingException is thrown when performing long transactions. Currently, Castor requires a (performance) cache of type other than 'none' to be used with classes that implement the 'TimeStampable' interface. In other words, if you want to use long transactions, please make sure that you use one of these cache types: 'unlimited', 'count-limited' or 'time-limited'.
The next entry has some more information about a potential cause of confusion in the context of long transactions and a cache type other than 'unlimited'.
With long transactions, sometimes update() throws a PersistenceException. As of release 0.9.5.3, Castor requires a (performance) cache (of type other than 'none') to be used with classes that implement the 'TimeStampable' interface.
Please note that if you are using a cache type other than 'unlimited', it is possible that objects expire from the cache. This case will be highlighted to you by a PersistenceException being thrown.
In this cases, please consider switching to cache type 'unlimited' (if possible) or increase the size of the cache according to your needs when using 'count-limited' (which has a default capacity of 100).
Yes. It is available from the Castor website: Advanced JDO --> OQL
We are currently working on Phase 3.
Not yet
Yes or no. Castor OQL supports implicit joins. And, in most case, you simply don't need explicit join.
Consider the following example,
100
]]>
It is simply equivalent to the following OQL
100
]]>
Yes. Just put "CALL SQL" keywords in front of your SQL statement. For example,
But remember that the order of the fields listed must match what is defined in the mapping file.
No, Castor OQL doesn't support struct. For example, the following
query CANNOT be done:
A query using the 'LIKE' expression includes the use of the SQL
wildcard '%'. The wildcard must be included in the bind()
statement:
OQLQuery oql = castorDb.getOQLQuery( "SELECT p FROM Product p WHERE p.name LIKE $1" );
oql.bind( "%widget%" );
Yes. However, the full expression is a bit different using the LIST keyword.
The following example provides a demonstration:
If identifiers other than numbers are used, those identifiers must be
quoted:
To include NULL values in the 'IN' list, use the 'nil' keyword:
It is even possible to include bind values in the 'IN' lists using the following syntax:
Unfortunately, the answer is no. We're aware that many users need this feature so it is a very high priority in our todo list.
If foreign key is the primary key, as a workaround you may consider using the 'extends' relationship.
Unfortunately, the answer is no.
In version 0.8.11, we tried to enable polymorphic collection by introducing the notation of Object Reloading. Object Reloading delegates the determination of the class to a data object. However, it is proved that reloading can only be done before any instance of the target object is returned to user, and we have no way to determine that. As a result, we removed the support in version 0.9.x.
In the near future, we are going to use a new mechanism to provide extends. The new mechanism loads a table with an SQL statement that outer-joins all of the extending tables with the base. The existence of an extended table row can be used to determine the class of a data object. Notice that all extended table rows of the same entity should always be stored in the same data-store.
In the further future, we also want to let users to define a discriminator column (or determinance field). Basing on the value of discriminator columns in the base table, the bridge layer fetches the additional information and returns the combined entity with the appropriate list of entity classes.
Yes, if the two tables share the same identity, you can specify one data object to "extends" the other. When the extended data object is loaded, its table (specified in ]]> will be joined with all the tables of its super classes'.
Another solution (in my opinion more flexible) is having two set of methods in the main object. One for Castor JDO and another for application.
Consider the following example:
Yes, as long as the deleted object is the same instance as the one being recreated.
Dependent object is actually a concept from the object-oriented database world. A dependent object's lifetime depends on its master object. So, create/delete/update of the master object will trigger the proper actions, newly linked dependent object will be automatically created and de-referenced dependent object will be removed.
The concept was also used in the earlier CMP 2.0 draft, although it is later removed.
No
Let's use object loading as an example.
When an application invoke db.load, the underneath TransactionContext is invoked. If the object with the requested identity exists in the TransactionContext, previously loaded object in the TransactionContext is returned. Otherwise, TransactionContext creates a new instance of the interested type and invokes LockEngine to "fill" the object.
LockEngine acquires a lock of the object, and it makes sure ClassMolder has a thread-safe environment when it invokes ClassMolder. In ClassMolder, if the interested set of fields representing the object is not existed in the cache yet, SQLEngine will be invoked and the set of fields from the underneath data store will be returned. ClassMolder binds the loaded or cached fields into the new instance. ClassMolder requests the TransactionContext to load the related and the dependent objects. Eventually, the object is returned after all of the relationships are resolved.
The process of commit has several states. The first state is preStore. In preStore state, objects existing in the TransactionContext are checked for modification one by one, including dependent and related objects. De-referenced dependent objects are marked as delete-able, and reachable dependent objects are added into TransactionContext. An object is marked "dirty" if it is modified. Also, if any modification should cause any related or dependent to be dirty, the related or dependent object is marked as dirty as well.
After the preStore state, all dirty object is properly stored. And, all marked delete object will be removed. Then, the connection is committed. If succeed, all cache with be updated. Finally, all lock is released.
Yes, via javax.transaction.Synchronization interface.
For Castor to work with global transactions, Castor must be configured to use global transaction demarcation in its main configuration file:
...
]]>
When retrieving a Database instance via
the Database implementation will authomatically be registered with the transaction manager, as it implements javax.jta.Synchronization interface. Subsequently, the transaction manager communicates with Castor via the beforeCompletion() and afterCompletion() calls.
No
Yes, starting from PostgreSQL 7.1, where outer joins support has been added.
Yes, starting from MySQL version 3.23, where transaction support has been added. Note: if you use Mark Matthews MySQL JDBC driver, then you need version 2.0.3 or higher.
For now only with PostgreSQL 7.1 and SAP DB you get a full set of Castor features. Other Open Source databases don't support select with write lock, so db-locked locking mode doesn't work properly (it works in the same way as exclusive locking mode).
All other Castor features are supported with MySQL, Interbase, InstantDB and Hypersonic SQL.
MySQL in it's current releases (4.0.x and 4.1.x) does not store fractions of a second in fields of type DATETIME that are mapped to java.sql.TimeStamp fields. As a result, Castor will throw ObjectModifiedExceptions during commits as Castor internally maintains fractions of a seconds.
Instead, Please use a column type that can be mapped to a long value, as Castor internally handles conversion between java.util.Date and long values with the required precision.
In MySQL, fields of type 'Timestamp' exhibit special behaviour wih regards to NULLs. When inserting a "NULL" into such a field, it actually inserts the current date and time. This causes problems for Castor's caching mechanism since Castor internally believes the field is still NULL. If you subsequently perform an update on the entry whilst it is still in the cache, an ObjectModifiedException will be thrown, because Castor believes that the database record has changed in the meantime.
The workaround is to use a DATETIME field instead of TIMESTAMP.
As with many other open source products, MySQL seems to be changing slightly from version to version. There seems to be a problem with concurrency in MySQL 4.1.5 that can be resolved by upgrading to 4.1.7 or higher.
At Castor we frequently use Connector/J 3.0.16, 3.1.13 and nowadays 5.1.6 to execute our test farmework. If you use one of this versions of Connector/J you should be on the safe side. If you are hit by any problems using one of these versions, please let us know.
As of Oracle release 10g, the problem of Castor to handle BLOBs with a size greater than 2kB and CLOBs with a size greater than 4 kB correctly has been resolved. With the 10 release of Oracle's JDBC driver, both driver types (type 2 and type 4) can be used. With earlier releases, only the OCI driver (type 2) seems to work.
The 10g release of the Oracle JDBC Driver can be downloaded here.
Please see this message from the mailing list. It includes an adapter class that will provide this functionality. (Thanks John!)
Yes, you can. By default, Castor uses JDBC proxy classes (wrapping java.sql.Connection and java.sql.PreparedStatement) that capture the core SQL statements as generated by Castor and the user-supplied parameters at execution time of the various persistence operations, and outputs them to the standard logger used by Castor. By default, these output statements are not visible, as the log level is set to level 'info'. To see these SQL statements, please increase the log level to level 'debug' in log4j.xml.
As of release 0.9.7, a new propertyorg.exolab.castor.persist.useProxies
has been added to castor.properties to allow configuration of the JDBC proxy
classes mentioned above. If enabled, JDBC proxy classes will be used for logging SQL
statements. When turned off, no logging statements will be generated at all.
Let us convert one of the classes from the JDO examples to use lazy-loading.
In the example model, every Product belongs to one ProductGroup. This is reflected in the conventional mapping as below. Here's the mapping for Product:
Product definition
]]> Let us now make the relationship between Product and ProductGroup use lazy loading. The relevant field in Product can be re-written like so:
<field name="group" type="myapp.ProductGroup" lazy="true">
<sql name="group_id" />
<bind-xml name="group" node="element" />
</field>
There have been one change only. We have placed the attribute lazy="true" in the field element. Note that no change is required in the ProductDetail mapping.
Please note that Castor does not support full serialization of lazy-loaded objects at this time. Rather than serializing just the information required to re-build the underlying proxy implementation during deserialization, Castor will materialize (read: load from the persistence store) all objects before serialization. As this can lead to a lot of database accesses, please use this feature carefully. A full working solution will be provided with the next release.
Let us convert one of the classes from the JDO examples to use lazy-loading.
In the example model, one Product can contain many ProductDetails. This
is reflected in the conventional mapping as below. First, the mapping for
Product:
Now let us examine ProductDetail. Note, the relationship is mapped
bi-directionally as must be all relationships
when using Castor JDO.
Let us now make the relationship between Product and ProductDetail use
lazy loading. We need only change the way that the relationship to
ProductDetail is specified in the mapping of Product. The relevant field
in Product can be re-written like so:
There have been two changes.
Note that no change is required in the ProductDetail mapping.
To use lazy loading you must also change the persistent class that will hold the related objects. At the very highest level, you need to provide a set method that accepts a java.util.Collection for the field in question. This is demonstrated by changing the JDO examples below.
In the original Product class we have the following code:
Let us now make the necessary changes to set up lazy loading. As stated
above we now require a special set method for the related ProductDetails
(stored originally as a java.util.Vector) that accepts a
java.util.Collection as an argument. This mandates that we must
also use a java.util.Collection to hold our ProductDetails. If
this is not added, you will receive the errors above.
Castor JDO provides a property in castor.properties for adjusting the size of the JDBC driver's buffer for reading LOBs (BLOBs and CLOBs) from the database. The propery is named org.exolab.castor.jdo.lobBufferSize and its default is 5120 bytes (5k). The size of this buffer can be tuned for larger LOBs, but is dependent upon the JDBC driver implementation being used and what it supports.
Due to a product limitation, AUTO_INCREMENT sequences in HSQL begin with 0 rather 1, as is the case with most other RDBMS. As a result of this, long transactions will not work for the object with the identity 0, and a ObjectModifiedException will be thrown.
To avoid this issue, we recommend inserting a temp object into the database in question, and removing thereafter so that no object with identity 0 is stored.
Some applications need to change the database connection or switch between different mapping files on the fly. Because Castor caches database configurations per name, you would have to register a new JDO configuration using a distinct name for any of the different configurations.
Instead you can call
// Reset database registry
org.exolab.castor.jdo.engine.DatabaseRegistry.clear();
As explained at the introduction to Castor JDO, Castor has support for many advanced features such as caching. The below sections detail the features related to caching in Castor JDO, as their understanding is required to use Castor JDO in a performant and secure way.
In general, performance caches enhance the application performance by reducing the number of read operations against the persistence storage, by storing and reusing the last read or committed values of the object. Performance caches do not affect the behavior of short transactions or locking. It only affects persistence objects that have been released from any transactional context.
Starting from Castor 0.8.6, a performance cache implementation has been added. At a technical level, Castor maintains separate (performance) caches for each object type specified in the JDO mapping provided, allowing users to specify - for each object type individually - the type and capacity of the cache.
By default, the following cache types are available:
As some of these cache providers allow for allow you to use it in a distributed mode, this allows Castor JDO to be used in a clustered (multi-JVM) environment. Please see the section below for short summary of this feature.
Per definition, all build-in performance caches are write-through, because all changes to objects as part of a transaction should be persisted into the cache at commit time without delay.
For problems related to the use of performance caches, please consult with the relevant entries in the JDO F.A.Q..
As it stands currently, performance caches also serve a dual purpose as dirty checking caches for long-transactions. This limitation implies that the object's availability in the performance cache determines the allowed time span of a long transaction.
This might become an issue when performance caches of type 'count-limited' or 'time-limited' are being used, where objects will eventually be disposed. If an application tries to update an object that has been disposed from the dirty checking cache, an ObjectModifedException will be thrown.
The DTD declaration is as follows:
With release 1.0 of Castor the DTD has changed but it is backward compatible to the old one and allows to enable debugging of cache access for a specific class as well as passing individual configuration parameters to each cache instance. Only count-limited and time-limited of the current build-in cache types support parameters. Parameter names are case sensitive and are silently ignored if they are unknown to a cache type.
It need to be noted that there are 3 parameter names that are reserved for internal use. If you specify a parameter with one of the names: type, name or debug their value will silently be overwritten with another one used internally.
A count-limited least-recently-used cache (LRU) for 500 objects can be specified by:
or
If both, the capacity attribute and parameter with name="capacity" is specified, the parameter value takes precedence over the attribute value.
A time-limited first-in-first-out cache (FIFO) that expires objects after 15 minutes can be specified by:
or
If both, the capacity attribute and parameter with name="ttl" is specified, the parameter value takes precedence over the attribute value.
The debug attribute can be used to enable debugging for objects of a single class. In addition to setting this attribut to true you also need to set logging level of org.castor.cache.Cache to debug.
The cache types fifo and lru are based on a set of articles in the O'Reilly Network by William Grosso, to implement a simplified and 1.3-compatible implementation of a Hashbelt algorithm.
Hashbelts are simple, in principle. Instead of walking all objects and finding out when they're supposed to expire, use a "conveyor belt" approach. At any particular point in time, objects going into the cache go into the front of the conveyor belt. After a certain amount of time or when the size limit of a container has been reached, move the conveyor belt - put a new, empty container at the front of the conveyor belt to catch new objects, and the one that drops off of the end of the conveyor belt is, by definition, ready for garbage collection.
As seen in his system, you can use a set of pluggable strategies to implement the actual hashbelt bits. A container strategy allows you to change out the implementation of the container itself - from simple hashtable-based implementations, up through more complex uses of soft referenced or hashset-based implementations, depending on what you need and what you want it to be used for. A pluggable "expire behavior" handler allows you to determine what action is taken on something which drops off of the bottom of the conveyor belt.
In difference to all other cache types the fifo and lru cache types offer various configuration options. Both of them have 6 parameters to configure their behaviour.
A fifo cache with default values explained above is specified by:
A lru cache with capacity=300 and ttl=300 is defined by:
or better by:
An example of a customized configuration of a fifo cache is:
All of the cache providers added with release 0.9.9 are distributed caches per se or can be configured to operate in such a mode. This effectively allows Castor JDO to be used in a clustered J2EE (multi-JVM) environment, where Castor JDO runs on each of the cluster instances, and where cache state is automatically snychronized between these instances.
In such an environment, Castor JDO wil make use of the underlying cache provider to replicate/distribute the content of a specific cache between the various JDOManager instances. Through the distribution mechanism of the cache provider, a client of a Castor JDO instance on one JVM will see any updates made to domain objects performed against any other JVM/JDO instance.
The following class mapping, for example, ...
defines that for all objects of type com.xyz.MyOtherObject Tangosol's Coherence cache provider should be used.
The following class mapping, for example, ...
defines that for all objects of type com.xyz.MyOtherObject the Gigaspaces cache provider should be used. As Gigspaces supports various cache and clsuer modes, this cache provider allows product-specific configuration as shown below:
As of release 0.9.6, Castor allows for the addition of user-defined cache implementations. Whilst Castor provides a set of pre-built cache providers, offering a variety of different cache algorithms, special needs still might require the application developer to implement a custom cache algorithm. Castor facilitates such need by making available standardized interfaces and an easy to understand recipe for integrating a custom cache provider with Castor.
As explained in
The main component of this package is the interface
Below is a summary of the steps required to build a custom cache provider and register it with Castor JDO:
Please create a class that implements the interface
To assist users in this task, a
Please add a class that imnplements the
To assist users in this task, a
The file castor.properties holds a property org.castor.cache.Factories that enlists the available cache types through their related CacheFactory instances.
To add your custom cache implementation, please append the fully-qualified class name to this list as shown below:
Sometimes it is necessary to interact with Castor's (performance) caches to e.g. (selectively) clear a Castor cache of its content, or inquire about whether a particular object instance (as identified by its identity) is cached already.
For this purpose a
This instance can subsequently be used to selectively clear the Castor performance cache using one of the following methods:
To inquire whether an object has already been cached, please use the following method:
Please note that once you have closed the Database instance from which you
have obtained the CacheManager, the CacheManager cannot be used anymore and
will throw a
This is a collection of HOW-TOs. The Castor project is actively seeking additional HOW-TO contributors to expand this collection. For information on how to do that, please see 'How to write a How-to'. Note that document titles in light grey identify documents that do not exist yet and are thus in search of an author.
To leverage Castor's core strength - support for enterprise-level XML data binding functionality - many web service framework vendors have started to offer integration of their respective products and XML data binding frameworks in general and Castor in particular. This allows users of web service frameworks to leverage the strengths of both worlds, making it easier to meet the requirements of mission-critical enterprise-level web service offerings.
The following table enlists web service frameworks, which offer support for integrating Castor as XML data binding framework, and offers direct pointers to the relevant documentation.
If we have missed any offerings, please feel free to let us know at one of the available mailing lists.
This document provides information about run-time and compile-time dependencies to 3rd-party frameworks/tools. Following this information, you'll be able to download all required JARs and configure your devlopment/run-time environment according to your needs.
We strogly encourage you, though, to consider using Maven 2 for your build management (process). Information of how to use Castor with Maven 2 is provided here.
As many other frameworks, Castor internally makes use of various existing frameworks and products to implement its functionality. As such, in order to function properly, Castor requires that these tools are available at run-time.
The following table(s) enlists 3rd-party products required at run-time, though many of these JARs are required only if the feature associated with that JAR is used at all.
Please check this page for details about the use of XML parsers with Castor and its requirements.
You'll require the following (optional) JARs, if you plan to use XML validation based on regular expressions:
Please note that the version numbers given specify the minimal version Castor requires. As such, please feel free to use any higher release numbers at your convenience. If any issues arise as a result of switching towards a higher release number, please report any such issues through the mailing lists, or raise a Jira issue.
The Castor XML schema support internally uses Castor XML for processing the XML schemas to be processed, and thus has the same dependencies as enlisted above.
The Castor XML code generator internally uses Castor XML and Castor XML schema support for processing the XML schemas to be processed, and thus has the joined dependencies of those two packages.
In addition to the dependencies for the Castor XML code generator, the Castor XML code generator will require additional dependencies as enlisted below:
These dependencies are optional as the use of Velocity-based templates for XML code generation is optional with release 1.2 and higher. Once you enable this mode, all dependencies given turn required.
Please refer to here for details on these code generation modes.
The Ant task definition for the Castor XML code generator internally uses the Castor XML code generator, and thus has the same dependencies as enlisted above.
In addition to the dependencies for the Castor XML code generator, the Ant task definition for the Castor XML code generator will require additional dependencies as enlisted below:
Castor JDO internally uses Castor XML and Castor XML schema support for processing the XML mapping file and thus has the same dependencies as enlisted above.
As such, in addition to the dependencies for Castor XML, Castor JDO will require additional dependencies as enlisted below:
The JDO examples use Apache Derby and depend on the JDBC driver provided with the examples archive. This driver is only required for running the samples and is not required otherwise, especially if you use a different database server.
As such, in addition to the dependencies for Castor JDO, the Castor JDO samples will require additional dependencies as enlisted below:
Castor DSML has a dependency on Apache Xerces to provide the XML serializer package for XML document production.
Castor DSML has two implementations, one that uses JNDI and one that uses the Mozilla Directory SDK. Applications that use the JNDI package ( org.exolab.castor.dsml.jndi ) are required to include jndi.jar or any alternative JAR that includes the JNDI 1.2 API. Applications that use the Mozilla Directory SDK ( org.exolab.castor.dsml.mozilla ) are required to include ldapjdk.jar or any alternative JAR that includes version 4.0 of the Mozilla Directory SDK.
We recommend using the Mozilla Directory SDK as the JNDI LDAP service provider and have had positive experiences using it with OpenLDAP. The JNDI LDAP service provider is included in the ldapsp.jar.
As such, in addition to the dependencies for Castor XML, Castor DSML will require additional dependencies as enlisted below:
In addition to the run-time dependencies given above, developing with and in Castor will require additional dependencies as enlisted below:
Castor JDO supports two type of environments, client applications and J2EE servers. Client applications are responsible for configuring the database connection and managing transactions explicitly. J2EE applications use JNDI to obtain a pre-configured database connection, and use UserTransaction or container managed transactions (CMT) to manage transactions. If you have been using JDBC in these two environments, you will be readily familiar with the two models and the differences between them.
Client applications are responsible for defining the JDO configuration, and managing
the transaction explicitly. The database is by default configured through a separate
XML file which links to the mapping file. Alternatively, it can be configured using the
utility class
In the example code I refer to the JDO configuration file as jdo-conf.xml, but any name can be used. See Castor JDO Configuration for more information.
As of release 0.9.6, a new JDOManager class is provided, that replaces the former JDO class. Any new features will be implemented against the new JDOManager class only.
As with its predecessor,
The
The following code fragment creates an instance of JDOManager for a database 'mybd', opens a database, performs a transaction, and closes the database - as it will typically appear in client applications (for brevity, we have ommitted any required exception handling):
For an example showing how to set up a database configuration on the fly without the need of a preconfigured XML configuration file) see JdoConfFactory.
J2EE applications depend on the J2EE container (Servlet, EJB, etc) to configure the database connection and use JNDI to look it up. This model allows the application deployer to configure the database properties from a central place, and gives the J2EE container the ability to manage distributed transactions across multiple data sources.
Instead of constructing a
The following code fragment uses JNDI to lookup a database, and uses the JTA UserTransaction interface to manage the transaction:
If the transaction is managed by the container, a common case with EJB beans and in particular entity beans, there is no need to begin/commit the transaction explicitly. Instead the application server takes care of enlisting the database in the ongoing transaction and executes commit/rollback at the proper time.
The following code snippet relies on the container to manage the transaction
All JDO operations occur within the context of a transaction. JDO works by loading data from the database into an object in memory, allowing the application to modify the object, and then storing the object's new state when the transaction commits. All objects can be in one of two states: transient or persistent.
Transient: Any object whose state will not be saved to the database when the transaction commits. Changes to transient objects will not be reflected in the database.
Persistent: Any object whose state will be saved to the database when the transaction commits. Changes to persistent objects will be reflected in the database.
An object becomes persistent in one of two ways: it is the result of a query,
(and the query is not performed in read-only mode) or it is added to the database
using
In a client application, use
If a persistent object was modified during the transaction, at commit time the modifications are stored back to the database. If the transaction rolls back, no modifications will be made to the database. Once the transaction completes, the object is once again transient. To use the same object in two different transactions, you must query it again.
An object is transient or persistent from the view point of the database to which
the transaction belongs. An object is generally persistent in a single database,
and calling
OQL queries are used to lookup and query objects from the database. OQL queries are similar to SQL queries, but use object names instead of SQL names and do not require join clauses. For example, if the object being loaded is of type TestObject, the OQL query will load FROM TestObject, whether the actual table name in the database is test, test_object, or any other name. If a join is required to load related objects, Castor will automatically perform the join.
The following code snippet uses an OQL query to load all the objects in a given group. Note that product and group are related objects, the JDBC query involves a join:
The following code snippet uses the previous query to obtain products, mark down their price by 25%, and store them back to the database (in this case using a client application transaction):
As illustrated above, a query is executed in three steps. First a query object is
created from the database using an OQL statement. If there are any parameters, the
second step involves binding these parameters. Numbered parameters are bound using
the order specified in their names. (e.g. first $1, after that $2, and so on...)
The third step involves executing the query and obtaining a result set of type
A query can be created once and executed multiple times. Each time it is executed the bound parameters are lost, and must be supplied a second time. The result of a query can be used while the query is being executed a second time.
There is also a special form of query that gives a possibility to call stored procedures:
oql = db.getOQLQuery("CALL sp_something($) AS myapp.Product");
Here sp_something is a stored procedure returning one or more ResultSets with the same sequence of fields as Castor-generated SELECT for the OQL query "SELECT p FROM myapp.Product p" (for objects without relations the sequence is: identity, then all other fields in the same order as in mapping.xml).
The method
The following code snippet creates a new product with a group that was previously queried:
The method
The following code snippet deletes the previously created Product instance:
There's no special method offering on the
The following code snippet loads a previously created Product instance, changes its description property and commits the transaction.
Castor JDO and Castor XML can be combined to perform transactional database operations that use XML as the form of input and output. The following code snippet uses a combination of persistent and transient objects to describe a financial operation.
This example retrieves two account objects and moves an amount from one account to the other. The transfer is described using a transient object (i.e. no record in the database), which is then used to generate an XML document describing the transfer. An extra step (not shown here), uses XSLT to transform the XML document into an HTML page.
The XML produced by the above code might look like:
Definition (wikipedia.org)
Castor is made up of (independent) modules as follows:
XML data binding framework to bind XML artefacts to Java objects and vice versa.
Code generator that generates Java source code from XML Schema information.
Java persistence framework to bind Java objects to RDBMS tables.
Castor JDO is not the same-as or compatible with Sun's JDO. We have a different approach to handling data object to RDBMS mappings. Please see the JDO FAQ for more information.
Generates DDL statements from JDO mapping files.
Various artefacts to support build management systems.
Castor is currently integrated with the following frameworks or has support for being integrated:
See the status page for a more complete feature list and for more information.
Sometimes we need to deal with a data format that Castor doesn't
support out-of-the-box, such as an unsupported Date/Time
representation, or we want to wrap and unwrap fields in Wrapper
objects to get the desired XML output without changing our object
model. To handle these cases Castor allows specifying a custom
When a writing a FieldHandler handler we need to provide implementations of the various methods specified in the FieldHandler interface. The main two methods are the getValue and setValue methods which will basically handle all our conversion code. The other methods provide ways to create a new instance of the field's value or reset the field value.
Let's take a look at how to convert a date in the format YYYY-MM-DD using
a custom FieldHandler. We want to marshal the following XML input file:
% java Test
unmarshalling root instance:
Root#getDate : Mon May 10 00:00:00 CDT 2004
After running our test program we can see that Castor invoked our
custom FieldHandler and we got our properly formatted date in our
Root.class.
A
The same FieldHandler we used above can be written as a GeneralizedFieldHandler
as such:
Notice that we never reference the Root class in our GeneralizedFieldHandler. This allows us to use the same exact FieldHandler for any field that requires this type of conversion.
In some situations, the GeneralizedFieldHandler might not provide sufficient flexibility. Suppose your xml document uses more than one date format. You could solve this by creating a GeneralizedFieldHandler subclass per date format, but that smells.
A ConfigurableFieldHandler is a FieldHandler that can be configured in the mapping file
with any kind and any number of parameters. You can simply configure two (or more)
instances of the same ConfigurableFieldHandler class with different date format patterns.
Here's a mapping file that uses a ConfigurableFieldHandler to marshal and unmarshal the
date field, similar to the preceding examples:
The field handler instance is referenced by the field element, using the handler attribute.
Here's the ConfigurableFieldHandler implementation:
As a convenience, org.exolab.castor.mapping.AbstractFieldHandler already implements ConfigurableFieldHandler. However, the setConfiguration method is not doing anything. Any subclass of AbstractFieldHandler only has to override this method to leverage the configuration capabilities. Since AbstractFieldHandler and its subclass GeneralizedFieldHandler are useful abstract classes, you'd probably want to use them anyway. It eliminates the need to implement the ConfigurableFieldHandler interface yourself.
A number of classes such as type-safe enum style classes have no constructor, but instead have some sort of static factory method used for converting a string value into an instance of the class. With a custom FieldHandler we can allow Castor to work nicely with these types of classes.
public static {Type} valueOf(String)
Even though Castor XML supports the "valueOf" method type-safe enum style classes, we'll show you how to write a custom handler for these classes anyway since it's useful for any type of class regardless of the name of the factory method.
Let's look at how to write a handler for the following type-safe enum style class,
which was actually generated by Castor XML (javadoc removed for brevity):
That's all there really is to it. Now we just need to hook this up to our mapping file and run a sample test.
If we have a root class Foo as such:
Our mapping file would be the following:
setCollectionIteration(false);
If you're going to be using custom field handlers for collection fields with a GeneralizedFieldHandler using versions of Castor prior to 0.9.6, then you'll need to handle the collection iteration yourself in the convertUponGet method.
If you're not using a GeneralizedFieldHandler then you'll need to handle the collection iteration yourself in the FieldHandler#getValue() method.
An alternative to using the command line as shown in the previous section, the Castor XML schema generator Ant task can be used to call the XML schema generator for XML schema generation. The only requirement is that the castor-<version>-anttasks.jar must be on the CLASSPATH.
Please find below the complete list of parameters that can be set on the Castor XML schema generator.
Alternatively to specifying the file property, it is possible to work with a nested <FileSet> element or with the dir property.
Below is an example of how to use this task from within an Ant target definition named 'castor:schema:gen':
Apache Cocoon is a web publishing framework built around the concepts of separation of concerns and component-based web development.
As part of this framework, Cocoon provides a component, the CastorTransformer, that marshalls an object hierarchy (for which a mapping file or a class descriptor hierarchy exists) to XML and inserts it as a stream of SAX events into a Cocoon pipeline.
Further information on the integration of Apche Cocoon and Castor can be found here.
Let's imagine the listed derivative department of an investment bank wants to display details of a derivative holding to the client. With the use of some 'magic', the information required to render this information is already stored in the (Http)Request object, where it is bound to an attribute with the name 'position'.
The following code fragment (stored in a separate XML file named position.xml)
will instruct the CastorTransformer to look for an object (hierarchy) bound to a (Http)Request attribute with the name 'position', and marshall its current state to XML.
As with all components in Cocoon, before the CastorTransformer can be used, it needs to be defined, i.e. its existence needs to be communicated to Cocoon. This is generally achieved by adding the relevant entries to the <component> section of the sitemap.
As with all transformers, the CastorTransformer definition
needs to go into the
This definition registers the CastorTransformer with Cocoon under the logical name 'castor', which will be used in pipeline declarations to specify that this very transformer shall be used.
To use the CastorTransformer within a pipeline to insert the XML representation of an arbitrary object hierarchy into the pipeline, please specify a pipeline entry similar to the following pipeline definition:
This instructs Cocoon to
The Castor Test Framework for JDO (CTF-JDO) is a thin wrapper around JUnit, the well known Java unit test framework. CTF-JDO provides the ability to execute tests based on an XML configuration file. This is very powerful when faced with a large number of tests, because it allows the execution of only certain tests out of that large pool of tests. Also, this feature can save an immense amount of time in the software development process because no code need be cut to execute a different set of tests. Upon complete execution of the suite of tests listed in the XML configuration file, the results are reported to the terminal.
For more information on writing unit tests with JUnit, please see this quick introduction article.
In the Castor directory is a test script that accepts arguments and passes them along to the TestSuite in CTF-JDO. Executing the test script (test.[sh|bat])with the argument '-info' yields a full list of the test cases available for execution.
The following is a quick start guide to running the tests that come with Castor:
Incidentally, if more feedback is needed from the tests as they're being run, execute the test script with the argument '-verbose'. This will cause the CTF-JDO to output more information about what is actually taking place while tests are executing.
Writing test cases is a very important, yet often misunderstood task. Unit tests are pieces of code that exercise different scenarios of a piece of software. Test cases are made up of groups of unit tests. Writing test cases for specific uses of Castor is vital. Submitting test cases assists the Castor developers in verifying bugs and/or patches. Whenever a user submits a request to the mail list stating that Castor is not working in their situation, someone must analyze the user's description or, if it's submitted, the user's code, and then create a test case for that situation. This is very time consuming and sometimes quite difficult to achieve. Submitting test cases with a complete description of the problem saves everyone a tremendous amount of time and expedites the entire process.
Understanding why unit tests are so important is the first step to addressing this issue. It may seem counterintuitive, but writing unit tests will actually save development time.
Writing test cases using the CTF-JDO can be difficult to figure out, at first. The following steps will assist you in writing your own:
The easiest way to write a test for your situation is to copy one of the existing tests in the src/tests/jdo directory and change it to suit your needs. Each test implements a certain set of methods. The list of methods is as follows:
Simply change setUp(), runTest(), and tearDown() to suit your needs. Then proceed to write any number of testXXX() methods to test your situation. Just place the name of each testXXX() method (in the proper order) in the runTest() method.
<harness name="Instance Creation Tests">
<category name="Misc" class="jdo.JDOCategory">
<jdo database-name="mytestcases" configuration="my_test_cases.xml" />
<case class="myapp.TestOne" />
<case class="myapp.TestTwo" />
<case class="myapp.TestThree" />
...
</category>
</harness>
This XML would need to be placed in its own file. For the sake of
this example, we'll call the file myapp_tests.xml.
Not yet created.
Castor uses a configuration file for environmental properties that are shared across all the Castor sub systems. The configuration file is specified as a Java properties file with the name castor.properties.
The Castor JAR includes a default configuration file. A configuration file in the Java library directory (e.g. /jdk1.2/lib) can be used to override the default configuration file with system-wide properties. In addition, a configuration file can be placed in the classpath and will override both the system wide properties and Castor-default configuration.
When running the provided examples, Castor will use the configuration file located in the examples directory which specifies additional debugging information as well as pretty printing of all produced XML documents.
The following properties are currently supported in the configuration file:
# THE CASTOR PROPERTIES FILE
# This file specifies values for Castor run-time which may be configured
# by the user.
# $Id: conf-lib.xml 8107 2009-02-28 00:12:40Z rjoachim $
# This section defines Backwards compatibility switches.
#
# Hashtable/Map default mapping.
# For backward compatibility with 0.9.5.2 and earlier.
#
#org.exolab.castor.xml.saveMapKeys=false
# Defines the default XML parser to be used by Castor.
# The parser must implement org.xml.sax.Parser.
#
org.exolab.castor.parser=org.apache.xerces.parsers.SAXParser
# Defines the (default) XML serializer factory to use by Castor, which must
# implement org.exolab.castor.xml.SerializerFactory;
# Default is org.exolab.castor.xml.XercesXMLSerializerFactory
org.exolab.castor.xml.serializer.factory=org.exolab.castor.xml.XercesXMLSerializerFactory
# Defines the NodeType for use with Java primitive types (int, long, boolean,
# etc). This value is only used by the Introspector. Valid values are either
# "attribute" or "element". By default, all primitives are marshaled as
# attributes. Uncomment the following line to change the NodeType to element.
#
#org.exolab.castor.xml.introspector.primitive.nodetype=element
# Defines the Naming "style" or conventions to use when creating XML names
# from Java class or field names.
# Valid values are as follows:
# -----------------------------------------------------------------
# lower (default) | All names are lowercase with hyphens
# | separating words.
# |
# | Example: personInfo = person-info
# -----------------------------------------------------------------
# mixed | All names are mixed case, with Uppercase
# | character as the first letter of a new word.
# |
# | Example: personInfo = personInfo
# | Example: FooBar = fooBar
# -----------------------------------------------------------------
# {Any ClassName} | Any Class which implements
# | org.exolab.castor.xml.XMLNaming
# -----------------------------------------------------------------
#
# By default, all names are treated as the "lower" option. To preserve the
# Java mixed-case conventions, uncomment the following line.
#
#org.exolab.castor.xml.naming=mixed
###############################
# REGULAR EXPRESSION EVALUATORS
#
# Defines the Regular Expression Evaluator to be used by Castor.
# The evaluator must implement org.exolab.castor.util.RegExpEvaluator.
#
# Uncomment the following to basically suppress Regular expressions evaluation:
#org.exolab.castor.regexp=org.exolab.castor.xml.util.AlwaysTrueRegExpEvaluator
#
# An implementation which uses the Jakarta RegExp library:
#org.exolab.castor.regexp=org.exolab.castor.util.JakartaRegExpEvaluator
#
# An implementation which uses the Jakarta ORO library:
org.exolab.castor.regexp=org.exolab.castor.util.JakartaOroEvaluator
# True if all documents should be indented on output by default.
# Defaults to false.
#
#org.exolab.castor.indent=true
# True if xml documents should be validated by the SAX Parser
# Defaults to false.
#
org.exolab.castor.parser.validation=false
# True for parser to support Namespaces.
# Defaults to false.
#
org.exolab.castor.parser.namespaces=false
# True if all documents should be validated by the marshaling framework
# Defaults to true.
#
org.exolab.castor.marshalling.validation=true
# Comma separated list of SAX 2 features that should be enabled for the
# default parser.
#
#org.exolab.castor.sax.features=
# Comma separated list of SAX 2 features that should be disabled for the
# default parser.
#
#org.exolab.castor.sax.features-to-disable
# True if debugging output should be generated.
# Defaults to false.
#
org.exolab.castor.debug=false
# 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
# List of collection handlers for Java 1.1 and Java 1.2 run-times:
#
org.exolab.castor.mapping.collections=\
org.exolab.castor.mapping.loader.J1CollectionHandlers,\
org.exolab.castor.mapping.loader.J2CollectionHandlers
# List of persistence factories for the supported database servers:
#
org.castor.cpa.persistence.sql.driver.factories=\
org.castor.cpa.persistence.sql.driver.OracleFactory,\
org.castor.cpa.persistence.sql.driver.PostgreSQLFactory,\
org.castor.cpa.persistence.sql.driver.SybaseFactory,\
org.castor.cpa.persistence.sql.driver.SQLServerFactory,\
org.castor.cpa.persistence.sql.driver.DB2Factory,\
org.castor.cpa.persistence.sql.driver.InformixFactory,\
org.castor.cpa.persistence.sql.driver.HsqlFactory,\
org.castor.cpa.persistence.sql.driver.InstantDBFactory,\
org.castor.cpa.persistence.sql.driver.InterbaseFactory,\
org.castor.cpa.persistence.sql.driver.MySQLFactory,\
org.castor.cpa.persistence.sql.driver.SapDbFactory,\
org.castor.cpa.persistence.sql.driver.GenericFactory,\
org.castor.cpa.persistence.sql.driver.DerbyFactory,\
org.castor.cpa.persistence.sql.driver.PointbaseFactory,\
org.castor.cpa.persistence.sql.driver.ProgressFactory
# List of key generator factories:
#
org.castor.cpa.persistence.sql.keygen.factories=\
org.castor.cpa.persistence.sql.keygen.MaxKeyGeneratorFactory,\
org.castor.cpa.persistence.sql.keygen.HighLowKeyGeneratorFactory,\
org.castor.cpa.persistence.sql.keygen.IdentityKeyGeneratorFactory,\
org.castor.cpa.persistence.sql.keygen.SequenceKeyGeneratorFactory,\
org.castor.cpa.persistence.sql.keygen.UUIDKeyGeneratorFactory
# Collection handlers for the source code generator:
#
org.exolab.castor.builder.type.j2=\
org.exolab.castor.builder.FieldInfoFactoryJ2
org.exolab.castor.builder.type.j1=\
org.exolab.castor.builder.FieldInfoFactory
org.exolab.castor.builder.type.odmg=\
org.exolab.castor.builder.FieldInfoFactoryODMG30
# Configures the default time zone to apply to dates/times fetched from
# database fields (if not already part of the data). Specify same format as
# in java.util.TimeZone.getTimeZone, or the empty string to use the computer's
# local time zone. Please see http://de.wikipedia.org/wiki/Zeitzone for
# detailed information about time zones.
#
org.exolab.castor.jdo.defaultTimeZone=
#org.exolab.castor.jdo.defaultTimeZone=GMT-8:00
# List of TxSynchronizeable implementations:
#
#org.exolab.castor.persist.TxSynchronizable=
# Sets the buffer size in bytes for fetching LOBs (this is dependent upon
# the JDBC driver implementation). The value below == 5k.
#
org.exolab.castor.jdo.lobBufferSize=5120
# True if database configuration should be initalization
# when loading it (default: true).
#
#org.exolab.castor.jdo.DatabaseInitializeAtLoad=true
# True if proxy classes should be used for JDBC connections and prepared statements.
# Defaults to true.
#
org.castor.cpa.persistence.sql.connection.proxies=false
# MappingLoader implementations:
#
org.castor.mapping.loaderFactories=\
org.castor.mapping.JDOMappingLoaderFactory,\
org.castor.mapping.XMLMappingLoaderFactory
# Cache implementations:
#
org.castor.cache.Factories=\
org.castor.cache.simple.NoCacheFactory,\
org.castor.cache.simple.TimeLimitedFactory,\
org.castor.cache.simple.CountLimitedFactory,\
org.castor.cache.simple.UnlimitedFactory,\
org.castor.cache.distributed.FKCacheFactory,\
org.castor.cache.distributed.JcsCacheFactory,\
org.castor.cache.distributed.JCacheFactory,\
org.castor.cache.distributed.CoherenceCacheFactory,\
org.castor.cache.distributed.OsCacheFactory,\
org.castor.cache.hashbelt.FIFOHashbeltFactory,\
org.castor.cache.hashbelt.LRUHashbeltFactory,\
org.castor.cache.distributed.EHCacheFactory,\
org.castor.cache.distributed.GigaspacesCacheFactory
# TransactionManagerFactory implementations:
#
org.castor.transactionmanager.Factories=\
org.castor.transactionmanager.WebSphereTransactionManagerFactory,\
org.castor.transactionmanager.WebSphere5TransactionManagerFactory,\
org.castor.transactionmanager.WebSphere51TransactionManagerFactory,\
org.castor.transactionmanager.LocalTransactionManagerFactory,\
org.castor.transactionmanager.JNDIENCTransactionManagerFactory,\
org.castor.transactionmanager.JOTMTransactionManagerFactory
# Selects whether the TransactionManager should be initialized at registration,
# or lazily when requested for the first time.
# Defaults to false.
#
org.castor.transactionmanager.InitializeAtRegistration=false
# Instructs Castor JDO to use the JDBC 3.0-specific features to obtain
# the generated value of an identity column.
# Defaults to false.
#
org.castor.jdo.use.jdbc30=false
# Specifies whether to use ANSI-compliant SQL for MS SQL Server.
# Defaults to false.
#
org.exolab.castor.jdo.sqlserver.ansi-compliant=false
# Specifyies whether the ClassDescriptorResolver should (automatically) search
# for and consult with package mapping files (.castor.xml) to retrieve class
# descriptor information; on by default.
# Defaults to true.
#
#org.exolab.castor.xml.loadPackageMappings=false
# Type convertors
#
org.castor.cpa.persistence.TypeConvertors=\
org.castor.cpa.persistence.convertor.BigDecimalToBoolean,\
org.castor.cpa.persistence.convertor.BigDecimalToByte,\
org.castor.cpa.persistence.convertor.BigDecimalToDate,\
org.castor.cpa.persistence.convertor.BigDecimalToDouble,\
org.castor.cpa.persistence.convertor.BigDecimalToFloat,\
org.castor.cpa.persistence.convertor.BigDecimalToInteger,\
org.castor.cpa.persistence.convertor.BigDecimalToLong,\
org.castor.cpa.persistence.convertor.BigDecimalToShort,\
org.castor.cpa.persistence.convertor.BooleanToBigDecimal,\
org.castor.cpa.persistence.convertor.BooleanToInteger,\
org.castor.cpa.persistence.convertor.BooleanToShort,\
org.castor.cpa.persistence.convertor.BooleanToString,\
org.castor.cpa.persistence.convertor.ByteArrayToInputStream,\
org.castor.cpa.persistence.convertor.ByteArrayToSerializable,\
org.castor.cpa.persistence.convertor.ByteArrayToString,\
org.castor.cpa.persistence.convertor.ByteToBigDecimal,\
org.castor.cpa.persistence.convertor.ByteToInteger,\
org.castor.cpa.persistence.convertor.ByteToShort,\
org.castor.cpa.persistence.convertor.CastorDateToDate,\
org.castor.cpa.persistence.convertor.CastorDateToSqlDate,\
org.castor.cpa.persistence.convertor.CastorDurationToLong,\
org.castor.cpa.persistence.convertor.CharArrayToSqlClob,\
org.castor.cpa.persistence.convertor.CharArrayToString,\
org.castor.cpa.persistence.convertor.DateToBigDecimal,\
org.castor.cpa.persistence.convertor.DateToCastorDate,\
org.castor.cpa.persistence.convertor.DateToDouble,\
org.castor.cpa.persistence.convertor.DateToInteger,\
org.castor.cpa.persistence.convertor.DateToLong,\
org.castor.cpa.persistence.convertor.DateToSqlDate,\
org.castor.cpa.persistence.convertor.DateToSqlTime,\
org.castor.cpa.persistence.convertor.DateToSqlTimestamp,\
org.castor.cpa.persistence.convertor.DateToString,\
org.castor.cpa.persistence.convertor.DoubleToBigDecimal,\
org.castor.cpa.persistence.convertor.DoubleToDate,\
org.castor.cpa.persistence.convertor.DoubleToFloat,\
org.castor.cpa.persistence.convertor.DoubleToInteger,\
org.castor.cpa.persistence.convertor.DoubleToLong,\
org.castor.cpa.persistence.convertor.FloatToBigDecimal,\
org.castor.cpa.persistence.convertor.FloatToDouble,\
org.castor.cpa.persistence.convertor.FloatToInteger,\
org.castor.cpa.persistence.convertor.FloatToLong,\
org.castor.cpa.persistence.convertor.InputStreamToByteArray,\
org.castor.cpa.persistence.convertor.InputStreamToSerializable,\
org.castor.cpa.persistence.convertor.IntegerToBigDecimal,\
org.castor.cpa.persistence.convertor.IntegerToBoolean,\
org.castor.cpa.persistence.convertor.IntegerToByte,\
org.castor.cpa.persistence.convertor.IntegerToDate,\
org.castor.cpa.persistence.convertor.IntegerToDouble,\
org.castor.cpa.persistence.convertor.IntegerToFloat,\
org.castor.cpa.persistence.convertor.IntegerToLong,\
org.castor.cpa.persistence.convertor.IntegerToShort,\
org.castor.cpa.persistence.convertor.LongToBigDecimal,\
org.castor.cpa.persistence.convertor.LongToCastorDuration,\
org.castor.cpa.persistence.convertor.LongToDate,\
org.castor.cpa.persistence.convertor.LongToDouble,\
org.castor.cpa.persistence.convertor.LongToFloat,\
org.castor.cpa.persistence.convertor.LongToInteger,\
org.castor.cpa.persistence.convertor.LongToShort,\
org.castor.cpa.persistence.convertor.ObjectToString,\
org.castor.cpa.persistence.convertor.SerializableToByteArray,\
org.castor.cpa.persistence.convertor.SerializableToInputStream,\
org.castor.cpa.persistence.convertor.ShortToBigDecimal,\
org.castor.cpa.persistence.convertor.ShortToBoolean,\
org.castor.cpa.persistence.convertor.ShortToByte,\
org.castor.cpa.persistence.convertor.ShortToInteger,\
org.castor.cpa.persistence.convertor.ShortToLong,\
org.castor.cpa.persistence.convertor.SqlClobToCharArray,\
org.castor.cpa.persistence.convertor.SqlClobToString,\
org.castor.cpa.persistence.convertor.SqlDateToCastorDate,\
org.castor.cpa.persistence.convertor.SqlDateToDate,\
org.castor.cpa.persistence.convertor.SqlTimestampToDate,\
org.castor.cpa.persistence.convertor.SqlTimestampToString,\
org.castor.cpa.persistence.convertor.SqlTimeToDate,\
org.castor.cpa.persistence.convertor.StringToBigDecimal,\
org.castor.cpa.persistence.convertor.StringToBoolean,\
org.castor.cpa.persistence.convertor.StringToByteArray,\
org.castor.cpa.persistence.convertor.StringToCharacter,\
org.castor.cpa.persistence.convertor.StringToCharArray,\
org.castor.cpa.persistence.convertor.StringToDate,\
org.castor.cpa.persistence.convertor.StringToDouble,\
org.castor.cpa.persistence.convertor.StringToFloat,\
org.castor.cpa.persistence.convertor.StringToInteger,\
org.castor.cpa.persistence.convertor.StringToLong,\
org.castor.cpa.persistence.convertor.StringToShort,\
org.castor.cpa.persistence.convertor.StringToSqlClob,\
org.castor.cpa.persistence.convertor.StringToSqlTimestamp
Castor in the press...
IBM developerWorks (2007/2008)
Brett McLaughlin has published an article series on (XML) data binding with Castor at IBM's developerWorks.
IBM developerWorks (October 2003)
Elias Torres, Brian D Goodman and Kevin Gibbs explain in their article how to integrate Castor with Apache Axis to process Document Style Web Services. ReadCastor Cures Your Data Binding Ills (developer.com, March 2003)
Thomas Hammell discusses both Castor XML and Castor J/DO as he walks the reader through a real world XML and RDB data binding example. ReadIBM developerWorks (January 2003)
Dennis Sonoski concludes its data-binding serie on developerWorks by taking a look at the performance of the different data-binding frameworks. ReadIBM developerWorks (January 2003)
Dennis Sonoski continues his series on the data binding approach by giving a global overview of 5 data binding frameworks including Castor and JAXB. ReadO/R Mapping with Castor JDO in the Real World (December 2002)
David Colwell discusses the pros and cons of his experience with Castor JDO as well as some feeback about how he worked around some of its limitations. ReadO'Reilly ONJava (October 2002)
Jeff Lowery provides an introduction to the Castor JDO framework. ReadIBM developerWorks (August 2002)
Castor JDO lead Bruce Snyder gives an overview of Castor JDO and introduces the reader to the basics of working with the JDO framework. ReadO'Reilly XML.com (July 2002)
Niel Bornstein drafts a introduction to the .Net Data-Binding framework and to Castor. This introduction compares both approaches. ReadIBM developerWorks (April 2002)
Enterprise Java expert Dennis Sosnoski introduces data binding and discusses what makes it so appealing. He illustrates the article using Castor. ReadJavaworld (April 2002)
Jacek Kruszelnicki discusses the pros and cons of Sun JDO and Castor JDO. ReadJavaworld (December 2001)
Sam Brodkin shed light on the Data-binding world using JAXB and Castor XML. ReadO'Reilly Onjava.com (October 2001)
Dion Almaer gives a good introduction to Castor XML. ReadCastor in the literature...
XML Application Developer's Guide by BORLAND (2001)
Borland is using Castor among the XML features present in JBuilder 6. This book contains a chapter on data-binding using Castor inside JBuilder 6. DownloadProfessional XML (2nd Edition) Chapter 15 (June 2001)
A chapter written by Keith Visco about Castor XML. Available for Download at Wrox: DownloadCastor in conferences...
Atlanta Java Software Symposium (November 2002) - New
Eitan Suez, of UptoData, Inc. - A great Castor evangelist in his own right, gave the following excellent presentation on Castor XML and JDO at the Atlanta Java Software Symposium, among other notable conferences. Download - presentationXML One Amsterdam (September 2001)
Andrew Fawcett, of CODA - our main evangelist, gave a presentation on implementing XML data binding solutions using web-services with Castor at the XML One conference in Amsterdam, September 2001. DownloadXML One London (March 2001)
Andrew Fawcett, of CODA, gave a presentation on XML data binding with Castor at the XML One conference in London, March 2001. DownloadO'Reilly Java Conference (March 2000)
The first public presentation on Castor was done at the O'Reilly Java Conference in March 2000. It's a little dated, but still serves as a decent overview of what Castor is all about. View the presentation.castorcodeexample
A minitutorial for using Castor JDO with MySQL. ReadCASTOR Tutorial
A small Castor XML tutorial. ReadTutorial: Schema databinding with Castor
A tutorial explaining how to use JBuilder's XML databinding features using XML schema and Castor XML to generate Java classes. ReadThe Town Of Castor
The Town Of Castor resides in East Central Alberta, Canada. Readl^ XjC Ї?b8D ; castor-1.3.2.orig/src/doc/ora-mar-2k/text.gif 0000644 0000000 0000000 00000003235 11544322135 015517 0 ustar GIF89a ! , +3 3));$$911)J)R1R1Z1Z9Z9c9c!BZ!Bc!Bk)Bc)Jk!Js)Js)Rs1Jc9Rk1Rs9Rs9Zs9Z{P B! J! J) B1R) Z) Z1 Z1R9D**N''L//J1!J9)@88J77R))_##^//S44P<<\99c1 k9 c9s9 e22a<
Castor XML