7
XML Class Generation for Java

The XML Class Generator for Java is contained within the oracle.xml.classgen package.

This chapter describes API's in the following classes:

• CGDocument Class
• CGNode Class
• CGXSDElement Class
• DTDClassGenerator Class
• InvalidContentException Class
• oracg Class
• SchemaClassGenerator Class

  See Also: Oracle9i XML Developer's Kits Guide - XDK Oracle9i Supplied Java Packages Reference

---

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 7-1 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( String doctype,
                       oracle.xml.parser.v2.DTD dtd);

Parameter	Description
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 grammar 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, String enc);	Prints the constructed XML Document to output stream with user-defined encoding.

Parameter	Description
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);

Parameter	Description
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

Table 7-2 Fields of CGNode

Field	Syntax	Description
isValidating	protected boolean isValidating	Boolean to indicate the validating mode

---

Methods of CGNode

Table 7-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 this value of ID identifier.
storeIDREF()	Stores this value for an IDREF identifier.
validateContent()	Checks if the content of the element is valid 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( String elementName);

Parameter	Description
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( String theData);

Parameter	Description
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( String theData);

Parameter	Description
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);

Parameter	Description
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( String theData);

Parameter	Description
theNode	Text to be deleted from an element.

getAttribute()

Description

Returns the value of the attribute.

Syntax

protected String getAttribute( String attName);

Parameter	Description
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 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(String theNode);

Parameter	Description
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 I/O Error occurs
• ClassNotFoundException when the class could not be instantiated

Syntax

protected void readExternal( oracle.xml.io.XMLObjectInput in,
                             oracle.xml.comp.CXMLContext cxmlContext)

Parameter	Description
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( String attName, 
                              String value);

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

setDocument()

Description

Sets the base document (root element).

Syntax

public void setDocument( CGDocument d);

Parameter	Description
d	Base CGDocument.

setElementNode()

Description

Sets the XMLElement node corresponding to this CGNode.

Syntax

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

Parameter	Description
node	The XMLElement.

storeID()

Description

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

Syntax

protected void storeID( String attName, 
                         String id);

Parameter	Description
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( String attName,
                            String idref);

Parameter	Description
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( String entity);

Parameter	Description
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( String name);

Parameter	Description
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( String name);

Parameter	Description
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);

Parameter	Description
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 7-4 Fields of CGXSDElement

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

---

Methods of CGXSDElement

Table 7-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 corresponded 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( String attName,
                              java.lang.Object attValue);

Parameter	Description
attName	The attribute name.
attValue	The attribute value.

addElement()

Description

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

Syntax

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

Parameter	Description
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 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);

Parameter	Description
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,
                              String name,
                             String namespace);

Parameter	Description
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( String value);

Parameter	Description
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 7-6 Summary of Methods of DTDClassGenerator  

Method	Description
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,
                       String doctype);

Parameter	Description
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);

Parameter	Description
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);

Parameter	Description
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( String dir);

Parameter	Description
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);

Parameter	Description
yes	The boolean flag 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);

Parameter	Description
yes	The boolean flag 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( String s);	This constructor takes an input String of information about the exception.

Parameter	Description
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 7-7 Command-line options of oracg  

Option	Description
-help	Prints the help message text.
-version	Prints the release version.
-dtd [-root <rootName>]	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 7-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( String fileName)	This constructor takes an input String containing the description of the XML Schema.

Parameter	Description
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);

Parameter	Description
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)

Parameter	Description
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);

Parameter	Description
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( String dir);

Parameter	Description
dir	The output directory.