Castor 1.3 - Reference documentation

Authors

Werner Guttmann (PartnerIndoqa)

Castor 1.3

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.5. XML configuration file

1.5.1. News
1.5.2. Introduction
1.5.3. Accessing the properties from within code
1.5.4. Current configuration file

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. No Constructor, No Problem!
1.7.6. 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. SimpleType Enumerations
2.3.3.3. Bound Properties
2.3.3.4. Class Creation/Mapping
2.3.3.5. Setting a super class
2.3.3.6. Mapping XML namespaces to Java packages
2.3.3.7. Generate equals()/hashCode() method
2.3.3.8. Maps java primitive types to wrapper object
2.3.3.9. Automatic class name conflict resolution
2.3.3.10. Extra collection methods
2.3.3.11. Class printing
2.3.3.12. Extra documentation methods

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. JDO extensions for the Castor XML code generator

3.2. JDO extensions - Motivation

3.3. Limitations

3.4. Prerequisites

3.4.1. Sample XML schemas
3.4.2. Sample DDL statements

3.5. The schema elements

3.5.1. <table> element
3.5.2. <column> element
3.5.3. <one-to-one> element
3.5.4. <one-to-many> element

3.6. Descriptor classes - Technical background

3.7. Integration with existing code generation tools

3.7.1. Command line
3.7.2. Ant task
3.7.3. Maven plugin for Castor

		Next
	The Castor community	Chapter 1. Castor XML - XML data binding

ttribute

5.4. XRef Samples

5.5. The Second Chapter

5.6. The Third Chapter

		Next
	The Castor community	Chapter 1. Introduction