6
Package oracle.xml.classgen

This chapter describes package oracle.xml.classgen, which contains the classes for the XML Class Generator in the Oracle9i XDK for Java. A class generator is a utility that accepts an input file and creates a set of output classes that have corresponding functionality. For the XML Class Generator, the input file is a DTD and the output is a series of classes that can be used to create XML documents conforming with the DTD.

This chapter contains these sections:

• Package oracle.xml.classgen Description
• Package oracle.xml.classgen Summary

---

Package oracle.xml.classgen Description

The XML Class Generator for Java creates Java source files from an XML DTD or XML Schema. This is useful when an application wants to send an XML message to another application based on an agreed-upon DTD or Schema, or as the back end of a Web form to construct and XML document. Using these classes, Java applications can construct, validate, and print XML documents that comply with the input DTD or Schema. The Class Generator works in conjunction with the Oracle XML Parser for Java, which parses the DTD or Schema and passes the parsed document to the class generator.

For more information, refer to Oracle resources for the XDK for Java on the Oracle Technology Network (OTN) Web site.

---

Package oracle.xml.classgen Summary

Table 6-1  Summary of oracle.xml.classgen

Name	Description
CGDocument Class	Serves as the base document class for the DTD class Generator generated classes
CGNode Class	Serves as the base class for the classes corresponding to the nodes of XML document generated by the DTD class generator.
CGXSDElement Class	Serves as the base class for the all the generated classes corresponding to the XML Schema generated by Schema Class Generator.
DTDClassGenerator Class	Generates the data binding classes corresponding to a DTD or an XML file based on a DTD.
InvalidContentException Class	Defines the Exception thrown by DTD ClassGenerator and Schema Class Generator.
oracg Class	Provides a command-line interface to generate java classes corresponding to the DTD or XML
SchemaClassGenerator Class	Generates the classes corresponding to an XML Schema.

---

CGDocument Class

Description of CGDocument

This class serves as the base document class for the DTD class Generator generated classes.

Syntax of CGDocument

public abstract class CGDocument extends oracle.xml.classgen.CGNode implements 
java.io.Externalizable
 
oracle.xml.classgen.CGNode
  |
  +--oracle.xml.classgen.CGDocument

Implemented Interfaces of CGDocument

java.io.Externalizable, java.io.Serializable

---

Methods of CGDocument

Table 6-2 Summary of Methods of CGDocument  

Method	Description
CGDocument(),	Constructor for the root element of the DTD.
print(),	Prints the constructed XML document.
readExternal(),	Reads the compressed stream and creates the object corresponding to the root element.

CGDocument()

Description

Constructor for the root element of the DTD.

Syntax

protected  CGDocument( java.lang.String doctype,

                    oracle.xml.parser.v2.DTD dtd);

Parameters

doctype	Name of the root Element of the DTD.
dtd	The DTD used to generate the classes.

print()

Description

Prints the constructed XML Document. Throws InvalidContentException if the document's content does not match the grammer specified by DTD; the validation mode should be set to TRUE. See also setValidationMode() in DTDClassGenerator Class. The options are described in the following table.

Syntax	Description
protected void print( java.io.OutputStream out);	Prints the constructed XML Document to output stream.
protected void print( java.io.OutputStream out, java.lang.String enc);	Prints the constructed XML Document to output stream whith user-defined encoding.

Parameters

out	Output stream to which the document will be printed.
enc	Encoding of the output stream.

readExternal()

Description

Reads the compressed stream and creates the object corresponding to the root element. Used for instantiating the generated classes with XML instance document.

Syntax

protected void readExternal( java.io.ObjectInput inArg,

                    oracle.xml.comp.CXMLContext cxmlContext);

Parameters

in	ObjectInput stream passed to read the compressed stream
cxmlContext	The context of the compressed stream

---

CGNode Class

Description of CGNode

This class serves as the base class for the classes corresponding to the nodes of XML document generated by the DTD class generator.

Syntax of CGNode

public abstract class CGNode
 
oracle.xml.classgen.CGNode

Direct Subclasses of CGNode

CGDocument

---

Fields of CGNode

isValidating

protected boolean isValidating

Boolean to indicate the validating mode.

---

Methods of CGNode

Table 6-3  Summary of Methods of CGNode

Method	Description
CGNode(),	Constructor for the Elements of the DOM Tree.
addCDATASection(),	Adds CDATA Section to the Element.
addData(),	Adds PCDATA to the element node.
addNode(),	Adds a node as a child to the element.
deleteData(),	Deletes PCDATA from an element node.
getAttribute(),	Retrieves the value of the attribute.
getCGDocument(),	Retrieves the base document.
getData(),	Retrieves the PCDATA of the element.
getDTDNode(),	Retrieves the static DTD from the base document.
getElementNode(),	Retrieves the XMLElement node corresponding to this CGNode.
getNode(),	Retrieves the CGNode which is one of the children of the element corresponding to this node whose name matches the input string.
readExternal(),	Reads the compressed stream and instantiates the corresponding node.
setAttribute(),	Sets the value of the attribute.
setDocument(),	Sets the base document.
setElementNode(),	Sets the XMLElement node corresponding to this CGNode.
storeID(),	Stores theis value of ID identifier.
storeIDREF(),	Stores thhis value for an IDREF identifier.
validateContent(),	Checks if the content of the element is valide according to the Content Model specified in DTD.
validEntity(),	Checks if the ENTITY identifier is valid.
validID(),	Checks if the ID identifier is valid.
validNMTOKEN(),	Checks if the NMTOKEN identifier is valid.
writeExternal(),	Writes the compressed stream corresponding to this node.

CGNode()

Description

Constructor for the Elements of the DOM Tree.

Syntax

protected  CGNode( java.lang.String elementName);

Parameters

elementName

Name of the element.

addCDATASection()

Description

Adds CDATA Section to the Element. Throws InvalidContentException if theData has illegal characters; validation must be set to TRUE. See also setValidationMode() in DTDClassGenerator Class.

Syntax

protected void addCDATASection( java.lang.String theData);

Parameters

theData

Text to be added as CDATA Section to the element.

addData()

Description

Adds PCDATA to the element node. Throws InvalidContentException if theData has illegal characters; validation must be set to TRUE. See also setValidationMode() in DTDClassGenerator Class.

Syntax

protected void addData( java.lang.String theData);

Parameters

theData

Text to be added a to the element.

addNode()

Description

Adds a node as a child to the element. Throws InvalidContentException if theData has illegal characters; validation must be set to TRUE. See also setValidationMode() in DTDClassGenerator Class.

Syntax

protected void addNode( CGNode theNode);

Parameters

theNode

The node to be added as child.

deleteData()

Description

Deletes PCDATA from the element node. Throws InvalidContentException if theData has illegal characters; validation must be set to TRUE. See also setValidationMode() in DTDClassGenerator Class.

Syntax

protected void deleteData( java.lang.String theData);

Parameters

theNode

Text to be deleted from an element.

getAttribute()

Description

Returns the value of the attribute.

Syntax

protected java.lang.String getAttribute( java.lang.String attName);

Parameters

attName

Name of the attribute.

getCGDocument()

Description

Gets the base document (root Element).

Syntax

protected CGDocument getCGDocument();

getData()

Description

Gets the PCDATA of the Element. Throws InvalidContentException if the data is not present.

Syntax

protected java.lang.String getData();

getDTDNode()

Description

Retrieves the static DTD from the base CGDocument.

Syntax

protected abstract oracle.xml.parser.v2.DTD getDTDNode();

getElementNode()

Description

Retrieves the XMLElement node corresponding to this CGNode.

Syntax

protected oracle.xml.parser.v2.XMLElement getElementNode();

getNode()

Description

Retrieves the CGNode which is one of the children of the element corresponding to the node whose name matches the input string.

Syntax

protected java.lang.Object getNode(java.lang.String theNode);

Parameters

theNode

The name of the string corresponding to the CGNode returned.

readExternal()

Description

Reads the compressed stream and instantiate the corresponding node. Throws the following exceptions:

IOException	When an IO Error occurs
ClassNotFoundException	When the corresponding class could not be instantiated.

Syntax

protected void readExternal(oracle.xml.io.XMLObjectInput in,

                    oracle.xml.comp.CXMLContext cxmlContext)

Parameters

in	The XMLObjectInput stream that is used to read the compressed stream.
cxmlContext	The context of the compressed stream.

setAttribute()

Description

Sets the value of the attribute.

Syntax

protected void setAttribute(java.lang.String attName,

                    java.lang.String value);

Parameters

attName	Name of the attribute.
value	Value of the attribute.

setDocument()

Description

Sets the base document (root element).

Syntax

public void setDocument( CGDocument d);

Parameters

d	Base CGDocument.

setElementNode()

Description

Sets the XMLElement node corresponding to this CGNode.

Syntax

protected void setElementNode(oracle.xml.parser.v2.XMLElement node);

Parameters

node	The XMLElement.

storeID()

Description

Store this value for an ID identifier, which can be verified with IDREF values.

Syntax

protected void storeID(java.lang.String attName,

                    java.lang.String id);

Parameters

attName	Name of the ID attribute.
id	Value of the ID

storeIDREF()

Description

Store this value for an IDREF identifier, which can be verified by the corresponding ID.

Syntax

protected void storeIDREF( java.lang.String attName,

                    java.lang.String idref);

Parameters

attName	Name of the IDREF attribute.
idref	Value of the IDREF

validateContent()

Description

Checks if the content of the element is valid according to the Content Model specified in DTD.

Syntax

protected void validateContent();

validEntity()

Description

Checks if the ENTITY identifier is valid. Returns TRUE if ENTITY is valid, FALSE otherwise.

Syntax

protected boolean validEntity( java.lang.String entity);

Parameters

name	Value of the ENTITY attribute

validID()

Description

Checks if the ID identifier is valid. Returns TRUE if ID is valid, FALSE otherwise.

Syntax

protected boolean validID( java.lang.String name);

Parameters

name	Value of the ID attribute.

validNMTOKEN()

Description

Checks if the NMTOKEN identifier is valid. Returns TRUE if NMTOKEN is valid, FALSE otherwise.

Syntax

protected boolean validNMTOKEN( java.lang.String name);

Parameters

name	Value of the NMTOKEN attribute.

writeExternal()

Description

Writes the compressed stream corresponding to this node.

Syntax

protected void writeExternal( oracle.xml.io.XMLObjectOutput out,

                    oracle.xml.comp.CXMLContext cxmlContext);

Parameters

out	ObjectOutput stream to write the compressed data.
cxmlContext	The context of the compressed stream.

---

CGXSDElement Class

Description of CGXSDElement

This class serves as the base class for the all the generated classes corresponding to the XML Schema generated by Schema Class Generator.

Syntax of CGXSDElement

public abstract class CGXSDElement extends java.lang.Object
 
java.lang.Object
  |
  +--oracle.xml.classgen.CGXSDElement

---

Fields of CGXSDElement

Table 6-4 Fields of ElementDecl

Field	Syntax	Description
type	protected java.lang.Object type	Type information of a node

---

Methods of CGXSDElement

Table 6-5 Summary of Methods of CGXSDElement  

Method	Description
CGXSDElement(),	Default constructor.
addAttribute(),	Adds the attribute of a given node to the hashtable.
addElement(),	Adds the local elements of an element node to the vector correspondig to the elements.
getAttributes(),	Returns the attributes as a hashtable of attribute names and values.
getChildElements(),	Retrieves the vector of all local elements.
getNodeValue(),	Returns the value of the node.
print(),	Prints an element node.
printAttributes(),	Prints an attribute node.
setNodeValue(),	Sets the node value of an element.

CGXSDElement()

Description

Default constructor.

Syntax

public  CGXSDElement();

addAttribute()

Description

Adds the attribute of a given node to the hashtable.

Syntax

protected void addAttribute(java.lang.String attName,

                    java.lang.Object attValue);

Parameters

attName	The attribute name.
attValue	The attribute value.

addElement()

Description

Adds the local elements of an element node to the vector correspondig to the elements.

Syntax

protected void addElement( java.lang.Object elem);

Parameters

elem	The object which needs to be added.

getAttributes()

Description

Returns the attributes as a hashtable of attribute names and values.

Syntax

public java.util.Hashtable getAttributes();

getChildElements()

Description

Retrieves the vector of all local elements.

Syntax

public java.util.Vector getChildElements();

getNodeValue()

Description

Returns the value of the node.

Syntax

public java.lang.String getNodeValue();

print()

Description

Prints an element node. Throws an IOException if not able to print to the output stream

Syntax

public void print( oracle.xml.parser.v2.XMLOutputStream out);

Parameters

out	The XMLObjectOutput stream to which the output is printed.

printAttributes()

Description

Prints an attribute node. Throws an IOException if not able to print to the XMLObjectOutput stream.

Syntax

public void printAttributes( oracle.xml.parser.v2.XMLOutputStream out,

                    java.lang.String name,

                    java.lang.String namespace);

Parameters

out	The XMLObjectOutput stream to which the output is printed.
name	The attribute name
namespace	The namespace

setNodeValue()

Description

Sets the node value of an element.

Syntax

protected void setNodeValue( java.lang.String value);

Parameters

value

The node vale.

---

DTDClassGenerator Class

Description of DTDClassGenerator

Generates the data binding classes corresponding to a DTD or an XML file based on a DTD.

Syntax of DTDClassGenerator

public class DTDClassGenerator extends java.lang.Object
 
java.lang.Object
  |
  +--oracle.xml.classgen.DTDClassGenerator

---

Methods of DTDClassGenerator

Table 6-6 Summary of Methods of DTDClassGenerator  

Method	Decription
DTDClassGenerator(),	Default constructor for DTDClassGenerator.
generate(),	Traverses the DTD with element doctype as root and generates Java classes.
setGenerateComments(),	Sets the switch to determine whether to generate java doc comments for the generated classes.
setJavaPackage(),	Sets the package for the classes generated.
setOutputDirectory(),	Sets the output directory where the java source code for the DTD is generated.
setSerializationMode(),	Sets the switch to determine if the DTD should be saved as a serialized object or as text file.
setValidationMode(),	Sets the switch to determine whether the classes generated should validate the XML document.

DTDClassGenerator()

Description

Default constructor for DTDClassGenerator.

Syntax

public  DTDClassGenerator();

generate()

Description

Traverses the DTD with element doctype as root and generates Java classes.

Syntax

public void generate( oracle.xml.parser.v2.DTD dtd,

                    java.lang.String doctype);

Parameters

DTD	The DTD used to generate the classes.
doctype	Name of the root element.

setGenerateComments()

Description

Sets the switch to determine whether to generate java doc comments for the generated classes. Default value is TRUE.

Syntax

public void setGenerateComments(boolean comments);

Parameters

comments

The boolean flag for turning on/off the java doc comment generation.

setJavaPackage()

Description

Sets the package for the classes generated. Default - no package set.

Syntax

public void setJavaPackage( java.util.Vector packageName);

Parameters

packageName

Name of the package.

setOutputDirectory()

Description

Sets the output directory where the java source code for the DTD is generated. Default value is the current directory.

Syntax

public void setOutputDirectory( java.lang.String dir);

Parameters

dir	Output directory.

setSerializationMode()

Description

Sets the switch to determine if the DTD should be saved as a serialized object or as text file. Serializing the DTD improves the performance when the generated classes are used to author XML files.

Syntax

public void setSerializationMode( boolean yes);

Parameters

yes	The boolean falg for turning on/off saving of DTD as serialized object (TRUE). Default is saving as a text file (FALSE).

setValidationMode()

Description

Sets the switch to determine whether the classes generated should validate the XML document being constructed. Default value is TRUE.

Syntax

public void setValidationMode( boolean yes);

Parameters

yes	The boolean falg for turning on/off validation of XML document. Default is TRUE.

---

InvalidContentException Class

Description of InvalidContentException

Defines the Exception thrown by DTD ClassGenerator and Schema Class Generator.

Syntax of InvalidContentException

public class InvalidContentException extends java.lang.Exception
 
java.lang.Object
  |
  +--java.lang.Throwable
        |
        +--java.lang.Exception
              |
              +--oracle.xml.classgen.InvalidContentException

Implemented Interfaces of InvalidContentException

java.io.Serializable

---

Methods of InvalidContentException

InvalidContentException()

Description

Constructor. The options are described in the following table.

Syntax	Description
public InvalidContentException();	Default constructor.
public InvalidContentException( java.lang.String s);	This constructor takes an input String of information about the exception.

Parameters

s	String that contains the information about the exception.

---

oracg Class

Description of oracg

Provides a command-line interface to generate java classes corresponding to the DTD or XML

Syntax of oracg

public class oracg extends java.lang.Object
 
java.lang.Object
  |
  +--oracle.xml.classgen.oracg

Command-line options of oracg

Table 6-7 Command-line options of oracg  

Option	Description
-help	Prints the help message text.
-version	Prints the release version.
-dtd [-root <rootNmae>]	The input file is a DTD file or DTD based XML file.
-schema <Schema File>	The input file is a Schema file or Schema based XML file.
-outputDir <Output Dir>	The directory name where java source is generated.
-package <Package Name>	The package name(s) of the generated java classes.
-comment	Generate comments for the generated java source code.

---

SchemaClassGenerator Class

Description of SchemaClassGenerator

This class generates the classes corresponding to an XML Schema.

Syntax of SchemaClassGenerator

public class SchemaClassGenerator extends java.lang.Object
 
java.lang.Object
  |
  +--oracle.xml.classgen.SchemaClassGenerator

---

Methods of SchemaClassGenerator

Table 6-8 Summary of Methods of SchemaClassGenerator  

Method	Description
SchemaClassGenerator(),	Constructor.
generate(),	Generates the Schema classes corresponding to top level elements, simpleType elements and complexType elements.
setGenerateComments(),	Sets the switch to determine whether to generate java doc comments.
setJavaPackage(),	Assigns a user-defined Java package name for each namespace.
setOutputDirectory(),	Sets the output directory where the java source code for the Schema class are generated.

SchemaClassGenerator()

Description

Constructor. The options are described in the following table.

Syntax	Description
public SchemaClassGenerator();	Default empty constructor for Schema Class Generator.
public SchemaClassGenerator( java.lang.String fileName)	This constructor takes an input String containing the description of the XML Schema.

Parameters

fileName

The input XML Schema.

generate()

Description

Generates the Schema classes corresponding to top level elements, simpleType elements and complexType elements by calling createSchemaClass() on each of these nodes.

Syntax

public void generate( oracle.xml.parser.schema.XMLSchema schema);

Parameters

XML	Schema object.

setGenerateComments()

Description

Sets the switch to determine whether to generate java doc comments. TRUE by default.

Syntax

public void setGenerateComments(boolean comments)

Parameters

comments

Turns on/off the java doc comment generation. TRUE by default.

setJavaPackage()

Description

Assigns user-defined Java package name for each namespace. The Namespaces defined in the schema are queried, and their number should match the number of package names provided by the user; otherwise, an error is thrown.

Syntax

public void setJavaPackage( oracle.xml.parser.schema.XMLSchema schema,

                    java.util.Vector pkgName);

Parameters

schema	The XML Schema
pkgName	A vector containing user defined package names given through command line.

setOutputDirectory()

Description

Sets the output directory where the java source code for the Schema class are generated. The current directory is the default.

Syntax

public void setOutputDirectory( java.lang.String dir);

Parameters

dir	The output directory.