Skip Headers

Oracle® XML Reference 10g (9.0.4) Part Number B10926-01 |
Home | Contents | Index

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

| Copyright © 2001, 2003 Oracle Corporation. All Rights Reserved. |
Home | Contents | Index