Castor 1.3.3 RC1 - Reference documentation

1.3.3 RC1

Copies of this document may be made for your own use and for distribution to others, provided that you do not charge any fee for such copies and further provided that each copy contains this Copyright Notice, whether distributed in print or electronically.

1. Castor XML - XML data binding
1.1. XML framework
1.1.1. Introduction
1.1.2. Castor XML - The XML data binding framework
1.1.2.1. Introspection mode
1.1.2.2. Mapping mode
1.1.2.3. Descriptor mode
1.1.3. Sources and destinations
1.1.4. XMLContext - A consolidated way to bootstrap Castor
1.1.5. Using existing Classes/Objects
1.1.6. Class Descriptors
1.2. XML Mapping
1.2.1. Introduction
1.2.2. Overview
1.2.2.1. Marshalling Behavior
1.2.2.2. Unmarshalling Behavior
1.2.3. The Mapping File
1.2.3.1. Sample domain objects
1.2.3.2. The <mapping> element
1.2.3.3. The <class> element
1.2.3.4. The <map-to> element
1.2.3.5. The <field> element
1.2.3.6. Description of the content
1.2.3.7. The <bind-xml> element
1.2.4. Usage Pattern
1.2.5. xsi:type
1.2.6. Location attribute
1.2.7. Tips
1.2.7.1. Automatically create a mapping file
1.2.7.2. Create your own FieldHandler
1.2.7.3. Mapping constructor arguments (since 0.9.5)
1.2.7.4. Preventing Castor from checking for a default constructor (since 0.9.5)
1.2.7.5. Type safe enumeration mapping (since 0.9.5)
1.3. Configuring Castor XML (Un)Marshaller
1.3.1. Introduction
1.3.2. Configuring the Marshaller
1.3.3. Configuring the Unmarshaller
1.4. Usage of Castor and XML parsers
1.4.1. SAX/DOM
1.4.2. StAX
1.5. XML configuration file
1.5.1. News
1.5.2. Introduction
1.5.3. Accessing the properties from within code
1.6. Castor XML - Tips & Tricks
1.6.1. Logging and Tracing
1.6.2. Indentation
1.6.3. XML:Marshal validation
1.6.4. NoClassDefFoundError
1.6.5. Mapping: auto-complete
1.6.6. Create method
1.6.7. MarshalListener and UnmarshalListener
1.7. Castor XML: Writing Custom FieldHandlers
1.7.1. Introduction
1.7.2. Writing a simple FieldHandler
1.7.3. Writing a GeneralizedFieldHandler
1.7.4. Use ConfigurableFieldHandler for more flexibility
1.7.5. Reuse a ConfigurableFieldHandler for more than one field definition
1.7.6. No Constructor, No Problem!
1.7.7. Collections and FieldHandlers
1.8. Best practice
1.8.1. General
1.8.1.1. Source Generator
1.8.2. Performance Considerations
1.8.2.1. General
1.8.2.2. Use of XMLContext - With and without a mapping file
1.8.2.3. Use of Marshaller/Unmarshaller
1.9. Castor XML - HOW-TO's
1.9.1. Introduction
1.9.2. Documentation
1.9.3. Contribution
1.9.4. Mapping
1.9.5. Validation
1.9.6. Source generation
1.9.7. Others
1.10. XML FAQ
1.10.1. General
1.10.1.1. How do I set the encoding?
1.10.1.2. I'm getting an error about 'xml' prefix already declared?
1.10.1.3. Why is my 'get' method called twice?
1.10.1.4. How can I speed up marshalling/unmarshalling performance?
1.10.1.5. How do I ignore elements during unmarshalling?
1.10.1.6. Where does Castor search for the castor.properties file?
1.10.1.7. Can I programmatically change the properties found in the castor.properties file?
1.10.2. Introspection
1.10.2.1. Can private methods be introspected?
1.10.3. Mapping
1.10.3.1. My mapping file seems to have no effect!
1.10.3.2. Are there any tools to automatically create a mapping file?
1.10.3.3. How do I specify a namespace in the mapping file?
1.10.3.4. How do I prevent a field from being marshaled?
1.10.4. Marshalling
1.10.4.1. The XML is marshalled on one line, how do I force line-breaks?
1.10.4.2. What is the order of the marshalled XML elements?
1.10.5. Source code generation
1.10.5.1. Can I use a DTD with the source generator?
1.10.5.2. My XML output looks incorrect, what could be wrong?
1.10.5.3. The generated source code has incorrect or missing imports for imported schema types
1.10.5.4. How can I make the generated source code more JDO friendly?
1.10.6. Miscellaneous
1.10.6.1. Is there a way to automatically create an XML Schema from an XML instance?
1.10.6.2. How to enable XML validation with Castor XML
1.10.6.3. Why is mapping ignored when using a FieldHandlerFactory
1.10.7. Serialization
1.10.7.1. Is it true that the use of Castor XML mandates Apache Xerces as XML parser?
1.10.7.2. Do I still have to download Xerces when using Castor XML with Java 5.0?
2. XML code generation
2.1. Why Castor XML code generator - Motivation
2.2. Introduction
2.2.1. News
2.2.1.1. Source generation & Java 5.0
2.2.2. Introduction
2.2.3. Invoking the XML code generator
2.2.4. XML Schema
2.3. Properties
2.3.1. Overview
2.3.2. Customization - Lookup mechanism
2.3.3. Detailed descriptions
2.3.3.1. org.exolab.castor.builder.javaVersion
2.3.3.2. org.exolab.castor.builder.javaVersion
2.3.3.3. org.exolab.castor.builder.boundproperties
2.3.3.4. org.exolab.castor.builder.javaclassmapping
2.3.3.5. org.exolab.castor.builder.superclass
2.3.3.6. org.exolab.castor.builder.nspackages
2.3.3.7. org.exolab.castor.builder.equalsmethod
2.3.3.8. org.exolab.castor.builder.useCycleBreaker
2.3.3.9. org.exolab.castor.builder.primitivetowrapper
2.3.3.10. org.exolab.castor.builder.automaticConflictResolution
2.3.3.11. org.exolab.castor.builder.extraCollectionMethods
2.3.3.12. org.exolab.castor.builder.jclassPrinterFactories
2.3.3.13. org.exolab.castor.builder.extraDocumentationMethods
2.4. Custom bindings
2.4.1. Binding File
2.4.1.1. <binding> element
2.4.1.2. <include> element
2.4.1.3. <package> element
2.4.1.4. <namingXML> element
2.4.1.5. <componentBinding> element
2.4.1.6. <java-class>
2.4.1.7. <member> element
2.4.1.8. <contentMember> element
2.4.1.9. <enumBinding> element
2.4.1.10. Not implemented yet
2.4.2. Class generation conflicts
2.4.2.1. Collision reporting
2.4.2.2. Automatic collision resolution
2.5. Invoking the XML code generator
2.5.1. Ant task definition
2.5.1.1. Specifying the source for generation
2.5.1.2. Parameters
2.5.1.3. Examples
2.5.2. Maven 2 plugin
2.5.2.1. Configuration
2.5.2.2. Integration into build life-cycle
2.5.2.3. Example
2.5.3. Command line
2.5.3.1. First steps
2.5.3.2. Source Generator - command line options
2.6. XML schema support
2.6.1. Supported XML Schema Built-in Datatypes
2.6.1.1. Primitive Datatypes
2.6.1.2. Derived Datatypes
2.6.2. Supported XML Schema Structures
2.6.2.1. Groups
2.6.2.2. Wildcard
2.7. Examples
2.7.1. The invoice XML schema
2.7.1.1. The schema file
2.7.1.2. Running the XML code generator
2.7.1.3. The generated code
2.7.2. Non-trivial real world example
2.7.2.1. The Supply Chain XSD
2.7.2.2. Binding file? -- IT IS REQUIRED!
3. Castor JDO
3.1. Castor JDO - An introduction
3.1.1. What is Castor JDO
3.1.2. Features
3.2. Castor JDO - First steps
3.2.1. Introduction
3.2.2. Sample domain objects
3.2.3. Using Castor JDO for the first time
3.2.4. JDO configuration
3.3. Using Castor JDO
3.3.1. Opening A JDO Database
3.3.1.1. Stand-alone application
3.3.1.2. J2EE Application
3.3.2. Using A JDO Database to perform persistence operations
3.3.2.1. Transient And Persistent Objects
3.3.2.2. Running an OQL Query
3.3.2.3. Creating a persistent object
3.3.2.4. Removing a persistent object
3.3.2.5. Updating a persistent object
3.3.3. Using JDO And XML
3.4. Castor JDO - Configuration
3.4.1. The Castor configuration file
3.4.1.1. Transaction demarcation
3.4.1.2. Sample Configuration File
3.4.1.3. Prepared statement pooling
3.4.1.4. Sample configurations for various databases
3.4.2. JDOConfFactory - A programmatic way of configuring Castor JDO
3.4.3. References
3.4.3.1. The JDO Configuration DTD
3.5. Type Support
3.5.1. Types
3.5.1.1. Castor XML
3.5.1.2. Castor JDO
3.5.1.3. Castor DAX
3.5.2. The Field Mapping
3.5.3. SQL Dates and Default Timezones
3.5.4. SQL Type Conversion
3.5.5. Parameterized Type Convertors
3.5.6. BLOB and CLOB Types
3.6. Castor JDO Mapping
3.6.1. News
3.6.2. Introduction
3.6.3. The Mapping File
3.6.3.1. The <mapping> element
3.6.3.2. The <class> element
3.6.3.3. The <map-to> element
3.6.3.4. The <field> element
3.6.3.5. The <sql> element
3.7. Castor JDO FAQ
3.7.1. Castor's relation to other specifications
3.7.1.1. Does Castor JDO comply with the SUN JSR-000012 specification?
3.7.1.2. Is Castor JDO better than EJB CMP?
3.7.2. XML related questions
3.7.2.1. Is it possible to make XML marshalling transactionally using Castor?
3.7.2.2. Is it possible to do queries on a XML file using Castor?
3.7.3. Technical questions
3.7.3.1. Where can I find some examples to start with?
3.7.3.2. I have encountered problems using Sun JDBC-ODBC bridge with Castor...
3.7.3.3. My get-method for the Collection of dependent objects returns null. Why?
3.7.3.4. Should my JDO classes implement some special interface?
3.7.3.5. Can Castor automatically create/remove related objects?
3.7.3.6. Is Castor JDO using any connection pooling mechanism to improve the overall performance?
3.7.3.7. I am getting ClassNotFoundException for my JDO class, but it is in the class path. Why?
3.7.3.8. I am getting exception 'the class ... is not persistence capable...'. Why?
3.7.3.9. I call db.remove() on the dependent object and commit, but this doesn't work...
3.7.3.10. How should I represent string/date/boolean literals in OQL query?
3.7.3.11. I get 'java.lang.AbstractMethodError: getBigDecimal' for numeric fields. Why?
3.7.3.12. Does Castor support both one-way and two-way relationships?
3.7.3.13. I have an object that holds a relation to itself. Does Castor support this?
3.7.3.14. Why do I get an ObjectModifiedException when trying to commit a transaction?
3.7.3.15. I'm receiving a java.sql.SQLException: ORA-01461
3.7.4. Castor and performance caches
3.7.4.1. Sometimes long transaction fails: on update() it is thrown ObjectModifiedException. Why?
3.7.4.2. Can I use the cache-type='none' with long transactions?
3.7.4.3. What is causing a PersistenceException with long transactions and how do I fix it?
3.7.5. OQL
3.7.5.1. Is there any document available for Castor OQL?
3.7.5.2. The OQL document describes several phases of development. Which is the current phase?
3.7.5.3. Does Castor OQL support sub-queries?
3.7.5.4. I cannot get Castor OQL to join two objects for me. Is it supported?
3.7.5.5. Can I write a pass-thru OQL?
3.7.5.6. Does Castor OQL support struct?
3.7.5.7. How do I structure a query using the 'LIKE' expression?
3.7.5.8. Does Castor support the SQL 'IN' expression?
3.7.6. Features requests
3.7.6.1. Can a foreign key be part of multiple primary keys?
3.7.6.2. Is polymorphic collection supported?
3.7.7. Data model issues
3.7.7.1. Is it possible to map an object to more than one tables?
3.7.7.2. Can an object with the same identity be re-created after being removed in the same transaction?
3.7.7.3. What is a dependent object?
3.7.7.4. Can a data object involved in many-to-many relationship be dependent?
3.7.8. Castor JDO design
3.7.8.1. How does Castor JDO work anyway?
3.7.8.2. Does Castor support two-phase commits? How is this implemented?
3.7.8.3. Does Castor support nested transaction?
3.7.9. Working with open source databases
3.7.9.1. Does Castor support PosgreSQL?
3.7.9.2. Does Castor support MySQL?
3.7.9.3. Which Open Source database is supported better?
3.7.10. RDBMS-specific issues
3.7.10.1. MySQL
3.7.10.2. Oracle
3.7.11. Castor & Logging
3.7.11.1. How can I integrate Castor's logging with a logging infrastructure using Log4J?
3.7.11.2. Can I see what SQL statement Castor issues to the database as a result of an operation?
3.7.11.3. How can I disable the use of JDBC proxy classes?
3.7.12. Lazy Loading related questions
3.7.12.1. How do I configure the JDO mapping to use the lazy loading feature for 1:1 relations?
3.7.12.2. Lazy loading for 1:1 relations and serialization
3.7.12.3. How do I configure the JDO mapping to use the lazy loading feature for 1:m and M:N relations?
3.7.12.4. I have modified my mapping to use lazy loading. Now I get the error 'no method to set value for field: com.xyz.ClassB in class: ClassMolder com.xyz.ClassA' or 'org.exolab.castor.jdo.DataObjectAccessException: no method to set value for field: com.xyz.ClassB in class: ClassMolder com.xyz.ClassA'. What am I doing wrong?
3.7.13. Tuning for LOBs
3.7.14. Database-specific issues
3.7.14.1. HSQL and identity key generators
3.7.15. Changing database configurations
3.8. Castor JDO code samples
3.8.1. Introduction
3.8.1.1. Java class files
3.8.1.2. DDL
3.8.1.3. Object Mappings
3.8.1.4. Relations
3.8.1.5. Extend relation & polymorphism
3.8.1.6. OQL samples
3.9. Castor JDO - How To's
3.9.1. Introduction
3.9.2. Documentation
3.9.2.1. How to author a HOW-TO document
3.9.2.2. How to author an FAQ entry
3.9.2.3. How to author a code snippet
3.9.2.4. How to author core documentation
3.9.3. Contribution
3.9.3.1. How to setup Castor project in eclipse
3.9.3.2. How to run Castor JDO's database independend unit tests
3.9.3.3. How to run Castor JDO's test suite
3.9.3.4. How to run Castor JDO's performance tests
3.9.3.5. Submitting a bug report
3.9.3.6. How to prepare a patch
3.9.3.7. How to Contribute a Patch via Jira
3.9.4. OQL
3.9.4.1. How to use a LIMIT clause with OQL
3.9.5. Core features
3.9.5.1. How to use a (performance) cache with Castor
3.9.5.2. How to map typesafe enumerations with Castor
3.9.5.3. How to use Castor JDO's connection proxies
3.9.6. Cascading
3.9.6.1. How to use cascading operations
3.9.6.2. How to cascade creation
3.9.6.3. How to cascade deletion
3.9.6.4. How to cascade update
3.9.7. Caches
3.9.7.1. How to use Castor in a J2EE cluster
3.9.8. Connection pooling
3.9.8.1. How to use Jakarta's DBCP for connection pooling
3.9.9. Use of Castor in J2EE applications
3.9.9.1. How to use Castor with(in) distributed J2EE transactions
3.9.10. Database specifica
3.9.10.1. How to connect to a Apache Derby instance in network server mode
3.10. Castor JDO - Tips & Tricks
3.10.1. Logging and Tracing
3.10.2. Access Mode
3.10.3. Inheritence
3.10.4. Views of Same Object
3.10.5. Upgrading Locks
3.10.6. NoClassDefFoundError
3.10.7. Create method
3.11. Castor JDO - Advanced features
3.11.1. Introduction
3.11.2. Caching
3.11.3. Dependent and related relationships
3.11.4. Different cardinalities of relationship
3.11.5. Lazy Loading
3.11.5.1. 1:1 relations
3.11.5.2. 1:M and M:N relations
3.11.6. Multiple columns primary keys
3.11.7. Callback interface for persistent operations
3.12. Running the self-executable Castor JDO examples
3.12.1. Download the castor-$RELEASE-examples.zip archive
3.12.2. Unpack the ZIP file
3.12.3. Running the Castor JDO samples
3.12.4. What happens
3.12.5. Hints
4. Advanced JDO
4.1. Castor JDO - Caching
4.1.1. Introduction
4.1.2. Caching and long transactions
4.1.3. Configuration
4.1.4. fifo and lru cache providers
4.1.5. Caching and clustered environments
4.1.6. Custom cache provider
4.1.6.1. Cache implementation
4.1.6.2. CacheFactory implementation
4.1.6.3. Configuration
4.1.7. CacheManager - monitoring and clearing caches
4.2. OQL to SQL translator
4.2.1. News
4.2.2. Status
4.2.3. Introduction
4.2.4. Overview
4.2.5. Syntax
4.2.6. Type and validity checking
4.2.7. SQL Generation
4.2.8. OQL FAQ
4.2.9. Summary
4.2.10. Examples
4.2.10.1. Java class files
4.2.10.2. Limit Clause
4.3. Transaction And Locking Modes
4.3.1. The JDO Model
4.3.2. Locking Modes
4.3.2.1. Access mode: Shared
4.3.2.2. Access mode: Exclusive
4.3.2.3. Access mode: Database Locked
4.3.2.4. Read-only Queries
4.3.3. Visibility of Changes
4.4. Castor Persistence Architecture
4.4.1. Layered Achitecture
4.4.2. Persistence API
4.4.2.1. Transactions
4.4.2.2. OIDs and Locks
4.4.2.3. Cache Engine
4.4.2.4. Pessimistic/Optimistic Locking
4.4.2.5. Relations
4.4.2.6. QueryResults
4.4.3. Service Providers (SPI)
4.4.3.1. Persistence
4.4.3.2. PersistenceQuery
4.4.4. Enterprise JavaBeans CMP
4.5. Castor JDO Key Generator Support
4.5.1. Introduction
4.5.2. MAX key generator
4.5.3. HIGH-LOW key generator
4.5.4. UUID key generator
4.5.5. IDENTITY key generator
4.5.6. SEQUENCE key generator
4.6. Castor JDO Long Transactions Support
4.6.1. Introduction
4.6.2. Bounded dirty checking
4.6.3. Long transactions that do not depend on cache
4.7. Nested Attributes
4.7.1. Introduction
4.7.2. Application types
4.7.3. Compound types
4.8. Using Pooled Database Connections
4.8.1. News
4.8.2. Pooling Agents
4.8.3. Standard Database Connections
4.8.4. Pooling and JDBC DataSources
4.8.4.1. PostgreSQL 7.3 and later
4.8.4.2. Oracle
4.8.4.3. mySQL
4.8.5. Configuring JDBC DataSources in Tomcat to be used with Castor
4.8.6. Jakarta Commons DBCP - BasicDataSource
4.8.6.1. Prepared statement pooling
4.9. Blobs in PostgreSQL
4.9.1. OID Support
4.9.2. OID Example
4.10. Castor JDO - Best practice
4.10.1. Introduction
4.10.2. General suggestions
4.10.3. Further optimization
5. Castor JDO - Integration with Spring ORM
5.1. Usage
5.1.1. Getting started using Maven 2
5.1.2. Project dependencies
5.2. A high-level overview
5.2.1. Sample domain objects
5.2.2. Using Castor JDO manually
5.2.3. Using Castor JDO with Spring ORM - Without CastorTemplate
5.2.4. Using Castor JDO with Spring ORM - With CastorTemplate
5.2.5. Using Castor JDO with Spring ORM - With CastorDaoSupport
5.3. Data access through Castor JDO with the Spring framework
5.3.1. Resource management
5.3.2. JDOManager setup in a Spring container
5.3.3. The CastorTemplate
5.3.4. Implementing Spring-based DAOs without callbacks
5.3.5. Programmatic transaction demarcation
5.3.6. Declarative transaction demarcation
5.3.7. Transaction management strategies
5.4. Build instructions
5.4.1. Prerequisites
5.4.2. Building the Spring ORM module
6. Castor JDO - Support for the JPA specification
6.1. JPA annotations - Motivation
6.2. Prerequisites and outline
6.3. Limitations and Basic Information
6.3.1. persistence.xml
6.3.2. JPA access type and the placing of JPA annotations
6.3.3. Primary Keys
6.3.4. Inheritance, mapped superclasses, etc.
6.3.5. Relations
6.4. An outline of JPA-Annotations
6.5. Usage of JPA annotations - Configuration
6.5.1. HOW-TO persist a single class (@Entity, @Table, @Id)
6.5.2. HOW-TO persist a 1:1 relation (@OneToOne)
6.5.3. Persist one to many relation (@OnetoMany)
6.5.4. HOW-TO create and use a named query (@NamedQuery)
6.5.5. HOW-TO create and use multiple named queries (@NamedQueries)
6.5.6. HOW-TO create and use a named native query (@NamedNativeQuery)
6.5.7. HOW-TO create and use multiple named native queries (@NamedNativeQueries)
6.5.8. HOW-TO use persistence callbacks
6.5.9. HOW-TO use @Enumerated
6.5.10. HOW-TO use @Temporal
6.5.11. HOW-TO use @Lob
6.6. Integration with Spring ORM for Castor JDO
6.6.1. A typical sample
6.6.2. Adding a JDOClassDescriptorResolver configuration
6.6.3. JPA Callbacks
6.7. Castor JPA Extensions
6.7.1. @Cache and @CacheProperty
7. XML code generation - Extensions
7.1. XML code generation extensions - Motivation
7.1.1. JDO extensions for the Castor XML code generator
7.1.1.1. JDO extensions - Motivation
7.1.1.2. Limitations
7.1.1.3. Prerequisites
7.1.1.4. Configuring the XML code generator
7.1.1.5. The JDO annotations for XML schemas
7.1.1.6. Using the generated (domain) classes with Castor JDO
7.1.2. SOLRJ extensions for the Castor XML code generator
7.1.2.1. SOLRJ extensions - Motivation
7.1.2.2. Prerequisites
7.1.2.3. The SOLRJ annotations for XML schemas
7.1.2.4. Using the generated domain classes with SOLR
   Next
 The Castor community Chapter 1. Castor XML - XML data binding