Index: /home/ekuns/workspace/castor-1/src/doc/sourcegen.xml =================================================================== --- /home/ekuns/workspace/castor-1/src/doc/sourcegen.xml (revision 6550) +++ /home/ekuns/workspace/castor-1/src/doc/sourcegen.xml (working copy) @@ -1,6 +1,5 @@ - - - + + The Source Code Generator @@ -7,8 +6,8 @@ Keith Visco Arnaud Blandin - Describes how to use the Source Code Generator, and what - is currently supported. + Describes how to use the Source Code Generator, and what features and + options are currently supported. Draft @@ -17,7 +16,10 @@ Using the Source Code Generator
-

API Reference: The Source Builder API

+

+ API Reference: The Source + Builder API +

@@ -22,222 +24,289 @@
-
- -

Since release 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 - artefacts: - -

    -
  • Use of parameterized collections, e.g. ArrayList<String>.
    • -
  • Use of @Override annotations with the generated methods - that require it.
    • -
  • Use of @SupressWarnings with "unused" method parameters - on the generated methods that needed it.
    • -
  • Added "enum" to the list of reserved keywords.
    • -

- -

To enable this feature (off by default), please uncomment the - following property in your custom castorbuilder.properties - file:

- - - # This property specifies whether the sources generated - # should comply with java 1.4 or 5.0; defaults to 1.4 - org.exolab.castor.builder.javaVersion=5.0 - - -
+
+ +

+ Since release 1.0.2, the Castor source generator 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: +

+ +
    +
  • + Use of parameterized collections, e.g. + ArrayList<String>. +
    • +
  • + Use of @Override annotations with the generated methods + that require it. +
    • +
  • + Use of @SuppressWarnings with "unused" method parameters + on the generated methods that needed it. +
    • +
  • Added "enum" to the list of reserved keywords.
    • +
+ +

+ To enable this feature (off by default), please add or uncomment + the following property in your custom + castorbuilder.properties file: +

+ + +# Specifies whether the sources generated should be source compatible with +# Java 1.4 or Java 5. Legal values are "1.4" and "5.0". When "5.0" is +# selected, generated source will use Java 5 features such as generics and +# annotations. +# Defaults to "1.4". +# +org.exolab.castor.builder.javaVersion=5.0 + + +
- +
+

+ Castor's Source Code Generator creates a set of Java classes which + represent an object model for an XML Schema (W3C XML Schema 1.0 Second + Edition, Recommendation)1, as well as the necessary Class + Descriptors used by the marshaling + framework to obtain information about the generated classes. +

-

Castor's Source Code Generator creates - a set of Java classes - which represent an object model for an XML Schema - (W3C XML Schema, 20010502 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. - -

+ + The generated source files will need to be compiled. A later + release may add an Ant taskdef to handle this automatically. + - + java org.exolab.castor.builder.SourceGeneratorMain -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 package + com.xyz. +

+ +

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

-

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

+

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

+
+
-

To compile the generated classes simply run javac, or your favorite compiler: + + For additional information about the Source Generator and its options, + you can download the Source + Generator User Document (PDF). Please note that the use of a + binding file is not dicussed in that document. + - javac com/xyz/*.java +

+ 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".

-

Created class will have marshal and unmarshal methods which are used to go back +

- and forth between XML and an Object instance.

+ + + Option + Args + Description + Optional? + + + i + filename + The input XML Schema file + Required + + + package + package-name + The package for the generated source + Optional + + + dest + path + + The destination directory in which to create the generated source + + Optional + + + line-separator + unix | 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 + + + types + type-factory + + Sets which type factory to use. This is useful if you want JDK + 1.2 collections instead of JDK 1.1 or if you want to pass in your + own FieldInfoFactory (see Collection + types). + + Optional + + + h +
+ Shows the help/usage information. + Optional + + + f +
+ + Forces the source generator to suppress all non-fatal errors, + such as overwriting pre-existing files. + Optional + + + nodesc +
+ Do not generate the class descriptors + Optional + + + nomarshall +
+ + Do not generate the marshaling framework methods (marshal, + unmarshal, validate) + Optional + + + testable +
+ + Generate the extra methods used by the CTF (Castor Testing + Framework) + + Optional + + + sax1 +
+ + Generate marshaling methods that use the SAX1 framework + (default is false). + + Optional + + + binding-file + The binding file name. + + Configures the use of a Binding File to allow finely-grained + control of the generated classes + + Optional + + + generateImportedSchemas +
+ + Generates sources for imported XML Schemas in addition to the + schema provided on the command line (default is false). + + Optional + + + case-insensitive +
+ + The generated classes will use a case insensitive method for + looking up enumerated type values. + + Optional + + + verbose +
+ Enables extra diagnostic output from the source generator + Optional + + + fail +
+ + Instructs the source generator to fail on the first error. When + you are trying to figure out what is failing during source + generation, this option will help. + + Optional + + -
+
-
+

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

- For additional information about the Source Generator and options, you can - download the Source Generator User - Document(PDF). Please note that the usage of the binding file is - not dicussed in that document. + + + Type + Value + Default + + + Java 1.1 + default + java.util.Vector + + + Java 1.2 + -type j2 + java.util.Collection + + + ODMG 3.0 + -types odmg + odmg.DArray + + -

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 at - "org/exolab/castor/builder/castorbuilder.properties".

+

+ 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: +

-
- - - - Option - Args - Description - Optional? - - - i - filename - The input XML Schema file - Required - - - package - package-name - The package for the generated source - Optional - - - dest - path - The destination in which to put the generated source - Optional - - - line-separator - unix | 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 - - - types - type-factory - Sets which type factory to use. This is useful if you want JDK 1.2 - collections instead of JDK 1.1 or if you want to pass in your own - FieldInfoFactory (see Collection types). - - Optional - - - h -
- Shows the help/usage screen. - Optional - - - 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 - - - testable -
- Generate the specific methods used by the Castor Marshalling Framework - Optional - - - sax1
- Generate marshalling methods that are using SAX1 framework (default is false). - Optional - - - binding-fileThe binding file name. - Allows the setting of a Binding File to allow a fine-grained control - the classes generated - Optional - - - generateImportedSchemas -
- Generates automatically sources for imported XML Schemas (default is false). - Optional - - - case-insensitive
- The generated classes will use a case insensitive method for looking up - enumerated type values. - Optional - - + -types com.personal.MyCoolFactory -
- -

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

- - - - Type - Value - Default - - - Java 1.1 - default - java.util.Vector - - - Java 1.2 - -type j2 - java.util.Collection - - - ODMG 3.0 - -types odmg - odmg.DArray - - - -

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:

- - -types com.personal.MyCoolFactory - -
+
-
+
@@ -243,25 +312,31 @@
-

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

- +

+ The input file for the source code generator is an XML + Schema2. The currently supported version is the + W3C XML Schema 1.0, Second Edition Recommendation1. + For more information about XML Schema Support, check the + XML Schema page +

-
- 1Castor 0.9.4.1 uses XML Schema Recommendation 20010502 +
+ + 1Castor supports the + XML Schema 1.0 Second + Edition Recommendation - 2XML Schema is a W3C Recommendation + 2XML Schema is a W3C + Recommendation - 3XPath is a W3C Recommendation + 3XPath is a W3C + Recommendation -
+
@@ -266,4 +341,3 @@ - Index: /home/ekuns/workspace/castor-1/src/doc/srcgen-binding.xml =================================================================== --- /home/ekuns/workspace/castor-1/src/doc/srcgen-binding.xml (revision 6550) +++ /home/ekuns/workspace/castor-1/src/doc/srcgen-binding.xml (working copy) @@ -1,9 +1,8 @@ - - - + + - Castor XML - Code generator bindings + Castor XML -- Code generator bindings Werner Guttmann Describes the binding file available with the Castor XML code generator. @@ -13,11 +12,14 @@ - Castor XML - Code generator bindings + Castor XML -- Code generator bindings
-

Blah

+

+ This section defines the Castor XML binding file and describes, with + examples, how to use it. +

@@ -22,21 +24,41 @@
-

It may appear that the default binding used to generate the Java Object Model from an XML schema doesn't - meet one's expectation. For instance, the default binding won't deal with naming collision problems that can appear since XML Schema allows - an element declaration and a complexType definition to both share the same name. From a Java standpoint, it will result in the creation of - two classes with the same qualified name: the second class generated will simply overwrite the first one. - Another example is when one user wants to change the default datatype binding provided by Castor or to add validation rules by implementing his own validator - and passing it to the SourceGenerator.

+ +

+ The default binding used to generate the Java Object Model from an XML + schema may not meet your expectations. For instance, the default + binding doesn't deal with naming collisions that can appear because + XML Schema allows an element declaration and a complexType definition + to use the same name. The source generator will attempt to create two + Java classes with the same qualified name. However, the second class + generated will simply overwrite the first one. +

+ +

+ Another example of where the default source generator binding may not + meet your expectations is when you want to change the default datatype + binding provided by Castor or when you want to add validation rules by + implementing your own validator and passing it to the Source Generator. +

-

The Binding declaration is an XML based language that allows the user to define such control on the generated classes. - The aim of this section is to provide an overview of the binding file as well as a definition of the several XML components used to define this binding file. - A more in-depth presentation will be available soon in the - Source Generator User Document(PDF).

+

+ The Binding declaration is an XML-based language that allows the user + to control and tweak details about source generation for the generated + classes. The aim of this section is to provide an overview of the + binding file and a definition of the several XML components used to + define this binding file. +

+ +

+ A more in-depth presentation will be available soon in the + Source Generator User Document + (PDF). +

- -<binding + (include*, package*, @@ -45,70 +67,127 @@ attributeBinding, complexTypeBinding, groupBinding) -</binding> -

The binding element is the root element and contains the binding information. The attribute defaultBindingType controls the - Class creation type

- - Be careful when using defaultBindingType attribute - as it will override the binding type specified in the - castorbuilder.properties file. - +]]> + +

+ The binding element is the root element and contains the binding + information. The attribute defaultBindingType controls + the Class creation type. +

+ + + + + Be careful when using defaultBindingType attribute as it + will override the binding type specified in the + castorbuilder.properties file. + +
- + <include URI = xsd:anyURI/> -
    -
  • URI:The URI of the binding file to include.
    • -
-

This element allows one to include the binding declaration defined in another file. This allows re-usability of Binding files defined for various - XML Schemas.

+ +
    +
  • URI:The URI of the binding file to include.
    • +
+ +

+ This element allows you to include a binding declaration defined in + another file. This allows reuse of Binding files defined for various + XML Schemas. +

- -<package> + name = xsd:string (namespace|schemaLocation) = xsd:string> -</package> -
    -
  • name:A fully qualified java package name.
    • -
  • namespace:An XML namespace that will be mapped to the package name defined by the name element.
    • -
  • schemaLocation:A URL that locates the schema to be mapped to the package name defined by the name element.
    • -
-

The targetNamespace attribute of an XML Schema identifies the namespace in which the XML language is defined. Such language namespace is defined - in the java language as package declaration. The <package/> element allows you to define the mapping between an XML namespace and a Java package. - Moreover XML Schema allows you to factorize the definition of an XML Schema identified by a unique namespace by including several XML Schemas to build - one XML Schema using the <xsd:include/> element (Please make sure you understand the difference between <xsd:include/> and <xsd:import/>). - <xsd:include/> relies on the URI of the included XML schema and it can be needed to keep the structure hierarchy defined in XML Schema in the Java - package generated. Thus the binding file allows to define the mapping between a schemaLocation attribute and a Java package.

+]]> + +
    +
  • + name:A fully qualified java package name. +
    • +
  • + namespace:An XML namespace that will be mapped to the + package name defined by the name element. +
    • +
  • + schemaLocation:A URL that locates the schema to be + mapped to the package name defined by the name element. +
    • +
+ +

+ The targetNamespace attribute of an XML Schema identifies + the namespace in which the XML schema elements are defined. This + language namespace is defined in the generated Java source as a + package declaration. The <package/> element allows you to define + the mapping between an XML namespace and a Java package. +

+ +

+ Moreover, XML Schema allows you to factor the definition of an XML + Schema identified by a unique namespace by including several XML + Schemas instances to build one XML Schema using the + <xsd:include/> element. Please make sure you understand + the difference between <xsd:include/> and + <xsd:import/>. <xsd:include/> relies on the + URI of the included XML schema. This element allows you to keep the + structure hierarchy defined in XML Schema in a single generated Java + package. Thus the binding file allows you to define the mapping + between a schemaLocation attribute and a Java package. +

-
- -<namingXML> +
+ (elementName,complexTypeName,modelGroupName) -</namingXML> + -<elementName|complexTypeName|modelGroupName> + (prefix?, suffix?) = xsd:string -</elementName|complexTypeName|modelGroupName> -
    -
  • prefix:The prefix to add to the names of the generated classes.
    • -
  • suffix:The suffix to append to the the names of the generated classes
    • -
-

One of the aim of the binding file is to avoid naming collisions. Indeed XML Schema allows elements and complexTypes to share the same name which - results in name collisions when generated the sources. Defining a binding for every element and complexType that share the same name is sometimes not - a convenient solution (for instance the BPML XML Schema or the UDDI v2.0 XML Schema use the same names for top-level complexTypes and top-level elements). - The aim of the <naming/> XML element is to define a prefix and a suffix for the names of the classes generated for an element, - a complexType or a model group definition.
- Note:It is not possible to control the names of the classes generated to represent nested model groups (all, choice, sequence).

+]]> + +
    +
  • + prefix:The prefix to add to the names of the generated classes. +
    • +
  • + suffix:The suffix to append to the the names of the generated classes. +
    • +
+ +

+ One of the aim of the binding file is to avoid naming collisions. + Indeed, XML Schema allows elements and complexTypes to share the + same name, resulting in name collisions when generating sources. + Defining a binding for each element and complexType that share the + same name is not always a convenient solution (for instance the BPML + XML Schema and the UDDI v2.0 XML Schema use the same names for + top-level complexTypes and top-level elements). The aim of the + <naming/> XML element is to define a prefix and a suffix for the + names of the classes generated for an element, a complexType or a + model group definition. +

+ +

+ Note:It is not possible to control the names of the classes + generated to represent nested model groups (all, choice, + and sequence). +

-
- -<elementBinding|attributeBinding|complexTypeBinding|groupBinding +
+ ((java-class|interface|member), elementBinding*, @@ -115,20 +194,42 @@ attributeBinding*, complexTypeBinding*, groupBinding*) -</elementBinding|attributeBinding|complexTypeBinding|groupBinding> -
    -
  • name:The name of the XML schema component for which we are defining a binding.
    • -
- -

These elements are the tenets of the binding file since they contain the binding definition for an XML Schema element, attribute, complexType - and modelGroup definition. The first child element (<java-class/>, <interface> or <member>) will determine the type of binding one is defining. - Please note that defining a <java-class> binding on an XML Schema attribute will have absolutely no effect.

-

The binding file being written from an XML Schema point of view; there are two distinct ways to define the XML Schema component for which we are - defining a binding. First we can define it throught the name attribute.

-

The value of the name attribute uniquely identifies the XML Schema Component. It can refer to the top-level component using the NCName of that component or - it can use a location language based on XPath3. - The grammar of that language can be defined by the following BNF:

- 
+]]>
+
+        
    
+          
  • 
+            name:The name of the XML schema component for which we
+            are defining a binding.
+          
    • 
+        

+
+        

+          These elements are the tenets of the binding file since they contain
+          the binding definition for an XML Schema element, attribute,
+          complexType and modelGroup definition. The first child element
+          (<java-class/>, <interface> or
+          <member>) will determine the type of binding one is
+          defining. Please note that defining a <java-class>
+          binding on an XML Schema attribute will have absolutely no effect.
+        

+
+        

+          The binding file is written from an XML Schema point of view; there
+          are two distinct ways to define the XML Schema component for which
+          we are defining a binding. First we can define it through the
+          name attribute.
+        

+
+        

+          The value of the name attribute uniquely identifies the XML Schema
+          Component. It can refer to the top-level component using the NCName
+          of that component or it can use a location language based on
+          XPath3.  The
+          grammar of that language can be defined by the following
+          BNF:
+        

+
+        
             [1]Path         ::= LocationPath('/'LocationPath)*
             [2]LocationPath ::= (Complex|ModelGroup|Attribute|Element|Enumeration)
             [3]Complex      ::= 'complexType:'(NCName|'anonymous')
@@ -136,47 +237,53 @@
             [5]Attribute    ::= '@'NCName
             [6]Element      ::= NCName
             [7]Enumeration  ::= 'enumType':(NCName|'anonymous')
-         

-         
-         
The second option to identify a XML Schema Component is to embed its 
-            binding definition inside its parent binding definition.

-            
-         
For instance, the following binding definition will be equivalent and will 
-            identify the element 'foo' defined in the top-level complexType 
-            'fooType'.

+
- -<elementBinding name="complexType:fooType/foo> - <member name="MyFoo" handler="mypackage.myHandler"/> -</elementBinding> +

+ The second option to identify an XML Schema Component is to embed + its binding definition inside its parent binding definition. +

+ +

+ For instance, the following binding definitions are equivalent and + identify the element 'foo' defined in the top-level + complexType 'fooType'. +

+ + + + + + + + +]]> -<complexTypeBinding name="fooType"> - <elementBinding name="foo> - <member name="MyFoo" handler="mypackage.myHandler"/> - </elementBinding> -<complexTypeBinding> +
-
- -

As shown above in the grammar, for the component types - 'Complex' and 'Enumeration', it is possible to specify that - a component binding should affect an anonymous type - definition. To qualify such an anonymous type definition - as part of the 'name' attribute of a component - binding, please use the type name qualifier 'anonymous' - as shown below.

- - +

+ As shown above in the grammar for the component types 'Complex' and + 'Enumeration', it is possible to specify that a component binding + should affect an anonymous type definition. To qualify such an + anonymous type definition as part of the 'name' attribute + of a component binding, please use the type name qualifier + 'anonymous' as shown below. +

+ + + <elementBinding name="complexType:fooType/foo/enumType:anonymous"> <member name="MyFoo" handler="mypackage.myHandler"/> </elementBinding> - -
-
-
- -<java-class +
+
+ +
+ + bound? = xsd:boolean (implements*,extends?) -</java-class> - -

This element defines all the options for the class to be generated, including - common properties such as class name, package name, etc.

- -
    -
  • name:The name of the class that will be generated.
    • -
  • package:The package of the class to be generated. if set, this option overrides the mapping defined in the <package/> element.
    • -
  • final:If true, the generated class will be final.
    • -
  • abstract:If true, the generated class will be abstract.
    • -
  • equals:If true, the generated class will implement the equals method.
    • -
  • bound:If true, the generated class will implement the bound properties.
    • -
+]]> + +

+ This element defines all the options for the class to be generated, + including common properties such as class name, package name, and + so on. +

+ +
    +
  • name:The name of the class that will be generated.
    • +
  • package:The package of the class to be generated. if set, + this option overrides the mapping defined in the + <package/> element.
    • +
  • final:If true, the generated class will be final.
    • +
  • abstract:If true, the generated class will be + abstract.
    • +
  • equals:If true, the generated class will implement the + equals() and hashCode() method.
    • +
  • bound:If true, the generated class will implement bound + properties, allowing property change notification.
    • +
+ +

+ For instance, the following binding definition instructs the source + generator to generate a class CustomTest for a global + element named 'test', replacing the default class name Test + with CustomTest. +

+ + + + ]]> -

For instance, the following binding definition instructs the source generator - to generate a class CustomTest for a global element named 'test', replacing - the default class name Test with CustomTest.

+

+ In addition to the properties listed above, it is possible to define + that the class generated will extend a class given and/or implement + one or more interfaces. +

- - <elementBinding name="/test"> - <java-class name="CustomTest" final="true"/> - </elementBinding> - -

In addition to above properties, it is possible to define that the class generated - will extend a class given and/or implement one or more interfaces.

- -

For instance, the following binding definition instructs the source generator - to generate a class TestWithInterface that implements the interface - org.castor.sample.SomeInterface in addition to - java.io.Serializable.

+

+ For instance, the following binding definition instructs the source + generator to generate a class TestWithInterface that + implements the interface org.castor.sample.SomeInterface in + addition to java.io.Serializable. +

- - <elementBinding name="/test"> - <java-class name="TestWithInterface"> - <implements>org.castor.sample.SomeInterface</implements> - </java-class> - </elementBinding> - -

The subsequent binding definition instructs the source generator - to generate a class TestWithExtendsAndInterface that implements the interface - org.castor.sample.SomeInterface in addition to - java.io.Serializable, and extends from (a possible) abstract base class - SomeAbstractBaseClass.

+ + + org.castor.sample.SomeInterface + + ]]> - - <elementBinding name="/test"> - <java-class name="TestWithExtendsAndInterface"> - <extends>org.castor.sample.SomeAbstractBaseClass</extends> - <implements>org.castor.sample.SomeInterface</implements> - </java-class> - </elementBinding> +

+ The subsequent binding definition instructs the source generator to + generate a class TestWithExtendsAndInterface that + implements the interface org.castor.sample.SomeInterface in + addition to java.io.Serializable, and extends from a + (probably abstract) base class SomeAbstractBaseClass. +

-

The generated class SomeAbstractBaseClass will have a class signature - identical to ...

- - + + + org.castor.sample.SomeAbstractBaseClass + org.castor.sample.SomeInterface + + ]]> + +

+ The generated class SomeAbstractBaseClass will have a class + signature as shown below: +

+ + ... public class TestWithExtendsAndInterface @@ -246,14 +373,13 @@ extends SomeAbstractBaseClass implements SomeInterface, java.io.Serializable { ... - - -
+ + +
+
-
- - + <member name? = xsd:string java-type? = xsd:string @@ -262,92 +388,106 @@ collection? = (array|vector|arraylist|hashtable|collection|odmg|set|map|sortedset) validator? = xsd:string/> -

This element represents the binding for class member. It allows the definition - of its name and java type as well as an implementation of FieldHandler - to help the Marshalling framework in handling that member. Defining a validator is also - possible. The names given for the validator and the fieldHandler must be fully qualified.

- -
    -
  • name:The name of the class member that will be generated.
    • -
  • java-type:the fully qualified name of the java type.
    • -
  • wrapper:If true, a wrapper object will be generated in case the java - type is a java primitive.
    • -
  • handler:The fully qualified name of the FieldHandler to use.
    • -
  • collection:If the schema component can occur more than once then this - attribute allows to specify the collection to use to represent the - component in Java.
    • -
  • validator:The fully qualified name of the FieldValidator to use.
    • -
- -

For instance, the following binding definition ...

- - - <elementBinding name="/root/members"> - <member collection="set"/> - </elementBinding> - -

instructs the source generator - to generate - within a class Root - a Java member named members, - using the collection type java.util.Set instead of the default - java.util.List as follows:

+

+ This element represents the binding for class member. It allows the + definition of its name and java type as well as an implementation of + FieldHandler to help the Marshaling framework in handling that + member. Defining a validator is also possible. The names given for + the validator and the fieldHandler must be fully qualified. +

+ +
    +
  • name:The name of the class member that will be + generated.
    • +
  • java-type:the fully qualified name of the java type.
    • +
  • wrapper:If true, a wrapper object will be generated in + case the Java type is a java primitive.
    • +
  • handler:The fully qualified name of the FieldHandler to + use.
    • +
  • collection:If the schema component can occur more than + once then this attribute allows specifying the collection to use + to represent the component in Java.
    • +
  • validator:The fully qualified name of the FieldValidator + to use.
    • +
- +

For instance, the following binding definition:

+ + + + ]]> + +

+ instructs the source generator to generate -- within a class + Root -- a Java member named members using the + collection type java.util.Set instead of the default + java.util.List: +

+ + public class Root { - + private java.util.Set members; - + ... - -} + +} -

The following (slightly amended) binding element ...

- - - <elementBinding name="/root/members"> - <member name="memberSet" collection="set"/> - </elementBinding> +

The following (slightly amended) binding element:

-

instructs the source generator to generate - again within a class Root - - a Java member named memberSet (of the same collection type as in the - previous example), overriding the name of the member as specified in the - XML schema:

+ + + ]]> - +

+ instructs the source generator to generate -- again within a class + Root -- a Java member named memberSet (of the same + collection type as in the previous example), overriding the name of + the member as specified in the XML schema: +

+ + public class Root { - + private java.util.Set memberSet; - + ... - -} - -
+ +} + +
-
+
- -<enumBinding> + (enumDef) ->/enumBinding> + -<enumDef> + (enumClassName = xsd:string, enumMember*) -</enumDef> + -<enumMember> + (name = xsd:string, value = xsd:string) ->enumMember> - - -

The <enumBinding> element allows more control on the - code generated for type safe enumerations, used to represent an XML Schema - <simpleType> enumeration.

- -
+ +]]> -

For instance, given the following XML schema enumeration definition ...

- - + The <enumBinding> element allows more control on the + code generated for type-safe enumerations, which are used to + represent an XML Schema <simpleType> enumeration. +

+ +
+ +

+ For instance, given the following XML schema enumeration definition: +

+ + @@ -358,17 +498,21 @@ ]]> - -

the Castor code generator would generate code where the default - naming convention used during the generation would overwrite the first - constant definition for value 'M' with the one generated for - value 'm'.

- -

The following binding definition defines - through the means of an - <enumMember> definition for the enumeration value - 'M' - a special binding for this value ...

- - + the Castor code generator would generate code where the default + naming convention used during the generation would overwrite the + first constant definition for value 'M' with the one + generated for value 'm'. +

+ +

+ The following binding definition defines -- through the means of + an <enumMember> definition for the enumeration + value 'M' -- a special binding for this value: +

+ + @@ -377,19 +521,23 @@ ]]> - -

and instructs the source generator to generate - within a class - DurationUnitType - a constant definition named CUSTOM_M - for the enumeration value M.

- -
+ +

+ and instructs the source generator to generate -- within a class + DurationUnitType -- a constant definition named + CUSTOM_M for the enumeration value M. +

-
+
-

For instance, given the following nested (anonymous) XML schema - enumeration definition ...

- - + +

+ For instance, given the following nested (anonymous) XML schema + enumeration definition: +

+ + @@ -406,13 +554,17 @@ ]]> - -

one could use a slightly modified <enumBinding> definition - based upon the previous exampl by altering the value of the - 'name' attribute to specify the correct XPATH to the anonymous - enumeration <simplyType> definition.

- - + +

+ one could use a slightly modified <enumBinding> + definition based upon the previous example by altering the value + of the 'name' attribute to specify the correct XPATH to + the anonymous enumeration <simplyType> + definition. +

+ + + <enumBinding name="/processDefinition/complexType:anonymous/@duration/enumType:anonymous"> <enum-def> <enumMember> @@ -421,134 +573,149 @@ </enumMember> </enum-def> </enumBinding> - -
+ +
+ +
+ +
+ +
+ +

+ The <javadoc> element allows one to enter the + necessary JavaDoc representing the generated classes or members. +

+ +
+ +
-
+ + name = xsd:string + ]]> -
- -
+
    +
  • name:The name of the interface to generate.
    • +
-

The >javadoc> element will allow one to enter the necessary javadoc - that represents the generated classes or members.

- -
- -
- - - <interface> - name = xsd:string - </interface> -
    -
  • name:The name of the interface that will be generated.
    • -
- -

This element specifies the name of the interface to be generated for an - XML schema component.

- -
+

+ This element specifies the name of the interface to be generated + for an XML schema component. +

- -
+
+ +
-
- -
-

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.

-
- -
- - -<?xml version="1.0" encoding="UTF-8"?> -<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" - elementFormDefault="qualified" - attributeFormDefault="unqualified"> - <xs:element name="Data"> - <xs:annotation> - <xs:documentation>This section contains the supply chain message - data</xs:documentation> - </xs:annotation> - <xs:complexType> - <xs:choice> - <xs:element name="PurchaseOrder"> - <xs:complexType> - <xs:sequence> - <xs:element name="LineItem" type="LineItemType" maxOccurs="unbounded"/> - </xs:sequence> - <xs:attribute name="OrderNumber" type="xs:string" use="required"/> - </xs:complexType> - </xs:element> - <xs:element name="OrderReceipt"> - <xs:complexType> - <xs:sequence> - <xs:element name="LineItem" type="ReceiptLineItemType" maxOccurs="unbounded"/> - </xs:sequence> - <xs:attribute name="OrderNumber" type="xs:string" use="required"/> - </xs:complexType> - </xs:element> - </xs:choice> - </xs:complexType> - </xs:element> - <xs:complexType name="SkuType"> - <xs:annotation> - <xs:documentation>Contains Product Identifier</xs:documentation> - </xs:annotation> - <xs:sequence> - <xs:element name="Number" type="xs:integer"/> - <xs:element name="ID" type="xs:string"/> - </xs:sequence> - </xs:complexType> - <xs:complexType name="ReceiptSkuType"> - <xs:annotation> - <xs:documentation>Contains Product Identifier</xs:documentation> - </xs:annotation> - <xs:complexContent> - <xs:extension base="SkuType"> - <xs:sequence> - <xs:element name="InternalID" type="xs:string"/> - </xs:sequence> - </xs:extension> - </xs:complexContent> - </xs:complexType> - <xs:complexType name="LineItemType"> - <xs:sequence> - <xs:element name="Sku" type="SkuType"/> - <xs:element name="Value" type="xs:double"/> - <xs:element name="BillingInstructions" type="xs:string"/> - <xs:element name="DeliveryDate" type="xs:date"/> - <xs:element name="Number" type="xs:integer"/> - </xs:sequence> - </xs:complexType> - <xs:complexType name="ReceiptLineItemType"> - <xs:sequence> - <xs:element name="Sku" type="ReceiptSkuType"/> - <xs:element name="Value" type="xs:double"/> - <xs:element name="PackingDescription" type="xs:string"/> - <xs:element name="ShipDate" type="xs:dateTime"/> - <xs:element name="Number" type="xs:integer"/> - </xs:sequence> - </xs:complexType> -</xs:schema> -
- -
- -

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.]

- - +
+ +
+

+ 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 support for + (un)marshaling and Castor's code generator to accelerate their + development process. +

+
+ +
+ + + + + + + + This section contains the supply chain message data + + + + + + + + + + + + + + + + + + + + + + + + + + + Contains Product Identifier + + + + + + + + + + Contains Product Identifier + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +]]> +
+ +
+ +

+ 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 version.) +

+ + Data.java DataDescriptor.java LineItem.java @@ -567,63 +734,94 @@ SkuDescriptor.java SkuType.java SkuTypeDescriptor.java - -

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 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. That is, you + can 'bind' an element in the XSD to a differently named class file + that you want to generate. This keeps different elements separate + and ensures that source is properly generated for each XML Schema + object. +

+ + +

+ The warning messages for Castor 0.99+ are very useful 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 occurred 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 occurred 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 occurred 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 occurred 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 occurred 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 occurred 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: +

+ + + + + + + + + + + + + + + + + + -

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.

- - -<binding xmlns="http://www.castor.org/SourceGenerator/Binding" - xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" - xsi:schemaLocation="http://www.castor.org/SourceGenerator/Binding - C:\\Castor\\xsd\\binding.xsd" - defaultBinding="element"> +]]> - <elementBinding name="/Data/PurchaseOrder/LineItem"> - <java-class name="PurchaseOrderLineItem"/> - </elementBinding> - - <elementBinding name="/Data/OrderReceipt/LineItem"> - <java-class name="OrderReceiptLineItem"/> - </elementBinding> - - <elementBinding name="complexType:ReceiptLineItemType/Sku"> - <java-class name="OrderReceiptSku"/> - </elementBinding> - - <elementBinding name="complexType:LineItemType/Sku"> - <java-class name="PurchaseOrderSku"/> - </elementBinding> - -</binding> +

+ One thing to notice in the above binding.xml file is that + the name path used is relative to the root of the XSD and not + the root of the target XML. Also notice that the two complex types + have the "complexType:" prefix to identify them followed by the name + path relative to the root of the XSD. +

-

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 new list of generated classes is:

- + Data.java DataDescriptor.java LineItem.java @@ -650,12 +848,15 @@ SkuDescriptor.java SkuType.java SkuTypeDescriptor.java - -

The developers can now use these generated classes with Castor to - (un)marshal the supply chain messages sent by their business partner.

-
- -
+ +

+ The developers can now use these generated classes with Castor to + (un)marshal the supply chain messages sent by their business + partner. +

+
+ +
@@ -660,4 +861,3 @@ - Index: /home/ekuns/workspace/castor-1/src/doc/test-framework.xml =================================================================== --- /home/ekuns/workspace/castor-1/src/doc/test-framework.xml (revision 6550) +++ /home/ekuns/workspace/castor-1/src/doc/test-framework.xml (working copy) @@ -1,34 +1,41 @@ - - - Castor Test Framework - JDO - Bruce Snyder - - Outlines the Castor JDO test framework. - - Final - + + + Castor Test Framework - JDO + Bruce Snyder + + Outlines the Castor JDO test framework. + + Final + + + + Castor JDO Test Framework Overview - - Test Framework Overview +
-
+

+ 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. +

-

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 by - cut to execute a different set of tests. Upon execution of the suite of tests listed in the - XML configuration file, the results are then reported to the terminal.

- -

For more information on writing unit tests with JUnit, please see this - quick introduction article.

+

+ 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: +

-

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: +

    +
  1. + Configure the database connection. +
    + This is done in the XML file corresponding to the database being + tested. For example, database connections for Oracle are configured in + the file oracle.xml. Change this file to contain the proper + username, password, driver and any driver parameters necessary. For + more information on this, see JDO + Config. +
    2. -
      -
    1. Configure the database connection.
      - - This is done in the XML file corresponding to the database being tested. For example, - database connections for Oracle are configured in the file oracle.xml. Change this file to contain - the proper username, password, driver and any driver parameters necessary. For more information on this, - see JDO Config.
      2. - -
    2. Create the appropriate database tables.
      - - This is done by loading the SQL file corresponding to the database being tested. - For example, the tables needed to test Oracle reside in oracle.sql. Consult the - database documentation on loading the SQL file. Alternatively, there is a little - utility available with Castor called BatchUpdateSQL in the src/tests/jdo directory - that can assist in the loading of SQL files.
      3. - -
    3. Compile the tests.
      - - The tests can be compiled by executing the build script with the argument - 'tests'. Note that compiling Castor is a prerequisite to compiling the tests.
      4. +
    4. + Create the appropriate database tables. +
      -
    5. Run the tests.
      - - To run only the tests for Oracle, for example, execute the test script with the - argument 'castor.oracle'. This argument will cause the CTF-JDO to execute only - the battery of tests for Oracle.


      6. + This is done by loading the SQL file corresponding to the database + being tested. For example, the tables needed to test Oracle reside in + oracle.sql. Consult the database documentation on loading the + SQL file. Alternatively, there is a little utility available with + Castor called BatchUpdateSQL in the directory + src/tests/jdo that can assist in the loading of SQL files. + - 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. - -
    +
  2. + Compile the tests. +
    -

    + The tests can be compiled by executing the build script with the + argument 'tests'. Note that building Castor is a prerequisite to + compiling the tests. +
    3. + +
  3. + Run the tests. +
    + + To run only the tests for Oracle, for example, execute the test + script with the argument 'castor.oracle'. This argument will cause + the CTF-JDO to execute only the battery of tests for Oracle. +
    4. + +

    + 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: +

-
+
    +
  1. + Customize the database XML descriptor to connect to your database. +
    -
    + There are database descriptors in the src/test/jdo directory for + most, if not all, of the supported databases. The database + descriptor is an XML file corresponding to the database being + tested. It provides the information needed to make connections to + the database. For example, database connections for Oracle are + configured in the file oracle.xml. (Note: In this + descriptor is a reference to a mapping descriptor. This should + point to the mapping descriptor created in step two.) For more + information on this, see JDO + Config. +
    2. -
    +
  2. + Create the appropriate database tables. +
    -

    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 extremely - 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 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.

    + This is done by loading the SQL file corresponding to the database + being tested. +
    3. -

    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.

    +
  3. + Create the mapping descriptor. +
    -
    4. - -
    - -

    Writing test cases using the CTF-JDO can be difficult to figure out. The following - steps serve to assist in writing your own: + Most situations will require the creation of an object model for + the tests. This requires that an XML mapping descriptor also be + created. For information on this, see the section on + XML mapping. This mapping descriptor + will need to be referenced in the database descriptor as noted in + step one. + -

      -
    1. Customize the database XML descriptor to connect to your database.
      - - There are database descriptors in the src/test/jdo directory for most, if not - all, of the supported databases. The database descriptor is an XML file corresponding - to the database being tested. It provides the information needed to make connections to - the database. For example, database connections for Oracle are configured in the - file oracle.xml. (Note: In this descriptor is a reference to a mapping descriptor. This - should point to the mapping descriptor created in step two.) For more information on - this, see JDO Config.
      2. - -
    2. Create the appropriate database tables.
      - - This is done by loading the SQL file corresponding to the database being tested.
      3. +
    3. + Write the tests. +
      -
    4. Create the mapping descriptor.
      - - Most situations will require the creation of an object model for the tests. - This requires that an XML mapping descriptor also be created. For information - on this, see the section on XML mapping. This - mapping descriptor will need to be referenced in the database descriptor as - noted in step one.
      5. +

      + 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: +

      + +
        +
      1. + The constructor - This is used to identify the test by giving + it a name and a number. +
        2. +
      2. + setUp() -- This method is used for any necessary + assembly of the test. +
        3. +
      3. + tearDown() -- This method is used to disassemble the + test upon completion of execution. +
        4. +
      4. + runTest() -- This method is passed to JUnit to execute + any tests called in the method body. +
        5. +
      5. + testXXX() -- Any number of test methods can be written. + Each test method's name begins with the word test + followed by a descriptive name using an initial capital letter. +
        6. +
      +
      +
      -
    5. Write the tests.
      - -

      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. +

      +
      6. -
        -
      1. The constructor - This is used to identify the test by giving it a name and a number.
        2. -
      2. setUp() - This method is used for any necessary assembly of the test.
        3. -
      3. tearDown() - This method is used to disassemble the test upon completion of execution.
        4. -
      4. runTest() - This method is passed to JUnit to execute any tests called in the method body.
        5. -
      5. testXXX() - Any number of test methods can be written. Each test method's name begins with the word test followed by a descriptive name using an initial capital letter.
        6. -


      - -

      Simply change setUp(), runTest() and tearDown() to suit your needs. Then - proceed to write any number of testXXX() methods necessary to test your - situation. Just place the name of each testXXX() method (in the proper - order) in the runTest() method.

      +
    6. + Create the test descriptor. +
      -
    7. Create the test descriptor.
      - - The XML test descriptor is simply a list of tests to be executed. The important - part of this file is each <case> element. This is where the fully - qualified name of each test resides. The following is a small example of a - stand alone XML descriptor containing some tests to run: + The XML test descriptor is simply a list of tests to be executed. + The important part of this file is each <case> + element. This is where the fully qualified name of each test + resides. The following is a small example of a stand-alone XML + descriptor containing some tests to run: <harness name="Instance Creation Tests"> @@ -180,39 +261,51 @@ </category> </harness> - - This XML would need to be placed in it's own file. For the sake of this - example, we'll call the file myapp_tests.xml.
      8. + + 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. + -
    8. Create the database tables.
      - - This is done by loading an SQL file that describes the tables. For a - sample of such an SQL file, see the SQL files in the src/tests/jdo - directory. For example, the tables needed to test Oracle reside in - oracle.sql. Incidentally, there is a little utility called BatchUpdateSQL in - the src/tests/jdo directory that is helpful in executing SQL files.
      9. +
    9. + Create the database tables. +
      -
    10. Compile the tests.
      - - Execute the build script with the argument 'tests' to compile the tests. - The standard Castor build script should pick up the files created.
      11. + This is done by loading an SQL file that describes the tables. For + a sample of such an SQL file, see the SQL files in the + src/tests/jdo directory. For example, the tables needed + to test Oracle reside in oracle.sql. Incidentally, there + is a little utility called BatchUpdateSQL in the + src/tests/jdo directory that is helpful in executing SQL + files. + -
    11. Execute the tests.
      - - Execute the test script with the argument '-file myapp_tests.xml'. This points - to the proper XML test descriptor for execution.
      12. +
    12. + Compile the tests. +
      -
    + Execute the build script with the argument 'tests' to compile the + tests. The standard Castor build script should pick up the files + created. + -

    +
  4. + Execute the tests. +
    -
    5. + Execute the test script with the argument '-file myapp_tests.xml'. + This points to the proper XML test descriptor for execution. + -
    -

    Not yet created.

    -
    +
- +
+

Not yet created.

+
+ +
+ + +