ExoLab     OpenEJB     OpenJMS     OpenORB     Castor     Tyrex     
 

Main
  Home
  Download
  API
  Schema
  Mailing Lists
  CVS

XML
  Using XML
  Source Generator
  Schema Support
  XML Mapping

JDO
  Using JDO
  New features
  JDO Config
  Types
  FAQs
  Presentation

Advanced JDO
  OQL
  Trans. & Locks
  Design
  KeyGen
  Long Trans.
  Nested Attrs.

More
  Presentations
  The Examples
  Configuration
  Tips & Tricks
  Full JavaDoc

About
  License
  Contributors
  Status, Todo
  Changelog
  Library
  Contact

  



The Source Code Generator

Reference: The Source Builder API

For a more detailled version of the Source Generator documentation, download the Source Generator User Document(PDF).

Introduction
Source Generator Options
Command Line Options
   Collection Types
Advanced Options
   Bound Properties
   Class Creation/Mapping
   The 'element' method
   The 'type' method
   Setting a super class
   Generate equals() method
XML Schema

Introduction

Castor's source code generator creates a set of Java classes which represent an object model for an XML Schema (W3C XML Schema, 200001024 Candidate Recommendation)1, as well as the necessary Class Descriptors used by the marshalling framework to obtain information about the generated classes. Currently the generated source files will need to be compiled. We will be adding an Ant taskdef eventually to handle this automatically.

Example:

java org.exolab.castor.builder.SourceGenerator -i foo-schema.xsd -package com.xyz

This will generate a set of source files from the the XML Schema, foo-schema.xsd, and place them in the com/xyz/* package.

To compile the generated classes simply run javac, or your favorite compiler:

javac com/xyz/*.java

Created class will have marshal and unmarshal methods which are used to go back and forth between XML and an Object instance.

Source Generator Options

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.

Command Line Options

OptionArgsDescriptionOptional?
ifilenameThe input XML Schema fileRequired
packagepackage-nameThe package for the generated sourceOptional
destpathThe destination in which to put the generated sourceOptional
line-separatorunix | mac | win Sets the line separator style for the desired platform. This is useful if you are generating source on one platform, but will be compiling/modifying on another platform. Optional
typestype-factorySets which type factory to use. This is useful if you you want JDK 1.2 collections instead of JDK 1.1 (see Collection types) Optional
h
Shows the help/usage screenOptional
f
Forces the source generator to supress all non-fatal errors, such as overwriting of pre-existing files. Optional
nodesc
Do not generate the class descriptors Optional
nomarshall
Do not generate the marshalling framework methods (marshall, unmarshall, validate) Optional
test
Generate the specific methods used by the Castor Marshalling Framework Optional

Collection Types

The source code generator has the ability to use the following types of collections when generating source code:

-Java 1.1 (default): java.util.Vector
-Java 1.2: use the option types -j2, collection type is java.util.Collection
-ODMG 3.0: use the option types -odmg, collection tyoe is odmg.DArray

Advanced Options

Bound Properties

Since version: 0.8.9

Bound properties are "properties" of a class, which when updated the class will send out a java.beans.PropertyChangeEvent to all registered java.beans.PropertyChangeListeners.

To enable bound properties uncomment the appropriate line in the "org/exolab/castor/builder/castorbuilder.properties" file:


    # To enable bound properties uncomment the following line. Please
    # note that currently *all* fields will be treated as bound properties
    # when enabled. This will change in the future when we introduce
    # fine grained control over each class and it's properties.
    #
    #org.exolab.castor.builder.boundproperties=true
                  

When enabled, all properties will be treated as bound properties. For each class that is generated a setPropertyChangeListener method is created as follows:


    /**
     * Registers a PropertyChangeListener with this class.
     * @param pcl The PropertyChangeListener to register.
    **/
    
    public void addPropertyChangeListener(java.beans.PropertyChangeListener pcl)
    {
        propertyChangeListeners.addElement(pcl);
    } //-- void addPropertyChangeListener(java.beans.PropertyChangeListener)
                 
Whenever a property of the class is changed, a PropertyChangeEvent will be sent to all registered listeners. The property name, the old value, and the new value will be set in the PropertyChangeEvent.

Note: To prevent unnecessary overhead, if the property is a collection, the old value will be null.

Class Creation/Mapping

Since version: 0.8.9

The source generator can treat the XML Schema structures such as complexType and element in two main ways. The first, and currently default method is called the "element" method. The other is called the "type" method.

The 'element' method

The "element" method creates classes for all elements whose type is a complexType. Abstract classes are created for all top-level complexTypes. Any elements whose type is a top-level type will have a new class create that extends the abstract class which was generated for that top-level complexType.

Classes are not created for elements whose type is a simpleType.

The 'type' method

The "type" method creates classes for all top-level complexTypes, or elements that contain an "anonymous" (in-lined) complexType.

Classes will not be generated for elements whose type is a top-level type.

More information on this is forth coming.

To change the "method" of class creation simple edit the castorbuilder.properties file:

    # Java class mapping of 's and 's
    #
    #org.exolab.castor.builder.javaclassmapping=element
             

Setting a super class

Since version: 0.8.10

The source generator enables the user to set a super class to all the generated classes (of course class descriptors are not concerned by this option)

To set up the super class, edit the castorbuilder.properties file :

    # This property allows one to specify the super class of *all*
    # generated classes
    #
    #org.exolab.castor.builder.superclass=com.xyz.BaseObject
            

Generate equals() method

Since version: 0.9.1

The Source Generator can override the 'equals()' method for the generated objects.

Note: hashcode() is not currently overriden.

To generate the equals() method , edit the castorbuilder.properties file :

	# Set to true if you want to generate the equals method
	# for each generated class.
	# false by default
	#org.exolab.castor.builder.equalsmethod=true

            

XML Schema

The input file to the source code generator is an XML Schema2. The current supported version is the W3C XML Schema Candidate Recommendation1. For more information about XML Schema Support, check the XML Schema page


1Castor 0.9.0 uses XML Schema Candidate Recommendation 20001024

2XML Schema is a W3C Working Draft
 
   
  
   
 


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