6
XML Class Generation for Java

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

This chapter describes APIs in the following classes:

• CGDocument Class

• CGNode Class

• CGXSDElement Class

• DTDClassGenerator Class

• InvalidContentException Class

• oracg Class

• SchemaClassGenerator Class

  See Also: Oracle Application Developer's Guide - XML

---

CGDocument Class

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

Syntax

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

Table 6-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()

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()

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()

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

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

Syntax

public abstract class CGNode
 

Table 6-2 Fields of CGNode

Field	Syntax	Description
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 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()

Constructor for the Elements of the DOM Tree.

Syntax

protected  CGNode( String elementName);

Parameter	Description
elementName	Name of the element.

---

addCDATASection()

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()

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()

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()

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()

Returns the value of the attribute.

Syntax

protected String getAttribute( String attName);

Parameter	Description
attName	Name of the attribute.

---

getCGDocument()

Gets the base document (root Element).

Syntax

protected CGDocument getCGDocument();

---

getData()

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

Syntax

protected String getData();

---

getDTDNode()

Retrieves the static DTD from the base CGDocument.

Syntax

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

---

getElementNode()

Retrieves the XMLElement node corresponding to this CGNode.

Syntax

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

---

getNode()

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()

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()

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()

Sets the base document (root element).

Syntax

public void setDocument( CGDocument d);

Parameter	Description
d	Base CGDocument.

---

setElementNode()

Sets the XMLElement node corresponding to this CGNode.

Syntax

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

Parameter	Description
node	The XMLElement.

---

storeID()

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()

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()

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

Syntax

protected void validateContent();

---

validEntity()

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()

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()

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()

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

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

Syntax

public abstract class CGXSDElement extends java.lang.Object
 

Table 6-4 Fields of CGXSDElement

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

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 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()

Default constructor.

Syntax

public  CGXSDElement();

---

addAttribute()

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()

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()

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

Syntax

public java.util.Hashtable getAttributes();

---

getChildElements()

Retrieves the vector of all local elements.

Syntax

public java.util.Vector getChildElements();

---

getNodeValue()

Returns the value of the node.

Syntax

public String getNodeValue();

---

print()

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()

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()

Sets the node value of an element.

Syntax

protected void setNodeValue( String value);

Parameter	Description
value	The node vale.

---

DTDClassGenerator Class

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

Syntax

public class DTDClassGenerator extends java.lang.Object
 

Table 6-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()

Default constructor for DTDClassGenerator.

Syntax

public  DTDClassGenerator();

---

generate()

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()

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()

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()

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()

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()

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

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

Syntax

public class InvalidContentException extends java.lang.Exception
 

---

InvalidContentException()

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

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

Syntax

public class oracg extends java.lang.Object
 

Table 6-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

This class generates the classes corresponding to an XML Schema.

Syntax

public class SchemaClassGenerator extends java.lang.Object

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()

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()

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()

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()

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()

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.