C
XDK for Java: Specifications and Cheat Sheets

This appendix describes the XDK for Java specifications and cheat sheets for each XML component for Java. The cheat sheets list the main APIs, classes, and associated methods for each XDK for Java component.

This appendix contains the following sections:

• XML Parser for Java Cheat Sheets

• Accessing XML Parser for Java

• XDK for Java: XML Schema Processor

• XDK for Java: XML Class Generator for Java

• XDK for Java: XSQL Servlet

• XML SQL Utility for Java Cheat Sheet-- See Appendix H, "XML SQL Utility (XSU) Specifications and Cheat Sheets"

XML Parser for Java Cheat Sheets

Table C-1 and Table C-2  list XML Parser for Java top level classes with a brief description of each. The following tables summarize other XML Parser for Java classes:

• Table C-3, "XML Parser for Java: DTD() Class Methods"

• Table C-4, "XML Parser for Java: ElementDecl() Class"

• Table C-5, "XML Parser for Java: NodeFactory() Class"

• Table C-6, "XML Parser for Java: NSName() and NSResolver Classes"

• Table C-7, "XMLParser for Java: SAXAttrList() Class""

• Table C-8, "XMl Parser for Java: SAXParser() Class"

• Table C-9, "XML Parser for Java: XMLParser() Class"

  Note: Not all the XML Parser for Java methods are listed in the foregoing tables.For the detailed reference documentation see: Oracle9i XML Reference http://otn/oracle.com/tech/xml Your installed software under doc/

Table C-1 XML Parser for Java: oracle.xml.parser.v2 Classes 

Class Summary	Description
Interfaces
NSName	This interface provides Namespace support for Element and Attr names
NSResolver	This interface provides support for resolving Namespaces
XMLDocumentHandler	This interface extends the org.xml.sax.DocumentHandler interface.
XMLToken	Basic interface for XMLToken
Classes
AttrDecl	Holds information about each attribute declared in an attribute list in the Document Type Definition.
Package Oracle.xml.parser.v2	Implements the default behavior for the XMLDocumentHandler interface.
DOMParser	Implements an eXtensible Markup Language (XML) 1.0 parser according to the World Wide Web Consortium (W3C) recommendation.
DTD	Implements the DOM DocumentType interface and holds the Document Type Definition information for an XML document.
ElementDecl	Represents an element declaration in a DTD.
NodeFactory	Specifies methods to create various nodes of the DOM tree built during parsing.
oraxml	Provides a command-line interface to validate XML files: java oracle.xml.parser.v2.oraxml options* source -h Prints this message -v Partial Validation mode -s Strict Validation Mode -w Show warnings -debug Debug mode -e <error log> A file to write errors to
oraxsl	Provides a command-line interface to applying stylesheets on multiple XML documents: java oraxsl options* source? stylesheet? result? -w Show warnings -e <error log> A file to write errors to -l <xml file list> List of files to transform -d <directory> Directory with files to transform -x <source extension> Extensions to exclude -i <source extension> Extensions to include -s <stylesheet> Stylesheet to use -r <result extension> Extension to use for results -o <result extension> Directory to place results -p <param list> List of Params -t <# of threads> Number of threads to use -v Verbose mode
SAXAttrList	Implements the SAX AttributeList interface and also provides Namespace support.
SAXParser	Implements an eXtensible Markup Language (XML) 1.0 SAX parser according to the World Wide Web Consortium (W3C) recommendation.
XMLAttr	Implements the DOM Attr interface and holds information on each attribute of an element.
XMLCDATA	Implements the DOM CDATASection interface.
XMLComment	Implements the DOM Comment interface.
XMLDocument	Implements the DOM Document interface, represents an entire XML document and serves the root of the Document Object Model tree.
XMLDocumentFragment	Implements the DOM DocumentFragment interface.
XMLElement	Implements the DOM Element interface.
XMLEntityReference
XMLNode	Implements the DOM Node interface and serves as the primary datatype for the entire Document Object Model.
XMLParser	Serves as a base class for the DOMParser and SAXParser classes.
XMLPI	Implements the DOM Processing Instruction interface.
XMLText	Implements the DOM Text interface.
XMLTokenizer	Implements an eXtensible Markup Language (XML) 1.0 parser according to the World Wide Web Consortium (W3C) recommendation.
XSLProcessor	Provides methods to transform an input XML document using a previously constructed XSLStylesheet.
XSLStylesheet	Holds XSL stylesheet information such as templates, keys, variables, and attribute sets.
Exceptions
XMLParseException	Indicates that a parsing exception occurred while processing an XML document
XSLException	Indicates that an exception occurred during XSL transformation

Table C-2 XML Parser for Java: DOMParser() Methods 

Method	Description
Constructor DOMParser()	Creates a new parser object. Implements an eXtensible Markup Language (XML) 1.0 parser according to the World Wide Web Consortium (W3C) recommendation. to parse an XML document and build a DOM tree.
Methods
getDoctype()	Get the DTD
getDocument()	Gets the document
parseDTD(InputSource, String)	Parses the XML External DTD from given input source
parseDTD(InputStream, String)	Parses the XML External DTD from given input stream.
parseDTD(Reader, String)	Parses the XML External DTD from given input stream.
parseDTD(String, String)	Parses the XML External DTD from the URL indicated
parseDTD(URL, String)	Parses the XML External DTD document pointed to by the given URL and creates the corresponding XML document hierarchy.
setErrorStream(OutputStream)	Creates an output stream for the output of errors and warnings.
setErrorStream(OutputStream, String)	Creates an output stream for the output of errors and warnings.
setErrorStream(PrintWriter)	Creates an output stream for the output of errors and warnings.
setNodeFactory(NodeFactory)	Set the node factory.
showWarnings(boolean)	Switch to determine whether to print warnings

Table C-3 XML Parser for Java: DTD() Class Methods 

DTD Class Members	Description
Class DTD()	Implements the DOM DocumentType interface and holds the Document Type Definition information for an XML document.
Methods
cloneNode(boolean)	Returns a duplicate of this node, i.e., serves as a generic copy constructor for nodes.
findElementDecl(String)	Finds an element declaration for the given tag name.
findEntity(String, boolean)	Finds a named entity in the DTD.
findNotation(String)	Retrieves the named notation from the DTD.
getChildNodes()	A NodeList that contains all children of this node.
getElementDecls()	A NamedNodeMap containing the element declarations in the DTD.
getEntities()	A NamedNodeMap containing the general entities, both external and internal, declared in the DTD.
getName()	Gets the name of the DTD, that is, the name immediately following the DOCTYPE keyword.
getNotations()	A NamedNodeMap containing the notations declared in the DTD.
getPublicId()	Gets the public identifier associated with the DTD, if specified.
getSystemId()	Gets the system identifier associated with the DTD, if specified.
hasChildNodes()	A convenience method to allow easy determination of whether a node has any children.
printExternalDTD(OutputStream)	Writes the contents of this document to the given output stream.
printExternalDTD(OutputStream, String)	Writes the contents of the external DTD to the given output stream.
printExternalDTD(PrintWriter)	Writes the contents of this document to the given output stream.

Table C-4 XML Parser for Java: ElementDecl() Class 

ElementDecl() Member Summary	Description
Class ElementDecl()	This class represents an element declaration in a DTD.
Fields
ANY	Element content type - Children can be any element
ASTERISK	ContentModelParseTreeNode type - "*" node (has one children)
COMMA	ContentModelParseTreeNode type - "," node (has two children)
ELEMENT	ContentModelParseTreeNode type - 'leaf' node (has no children)
ELEMENTS	Element content type - Children can be elements as per Content Model
EMPTY	Element content type - No Children
MIXED	Element content type - Children can be PCDATA & elements as per Content Model
OR	ContentModelParseTreeNode type - "|" node (has two children)
PLUS	ContentModelParseTreeNode type - "+" node (has one children)
QMARK	ContentModelParseTreeNode type - "?" node (has one children)
Methods
expectedElements(Element)	Returns vector of element names that can be appended to the element.
findAttrDecl(String)	Gets an attribute declaration object or null if not found
getAttrDecls()	Gets an enumeration of attribute declarations
getContentElements()	Returns Vector of elements that can be appended to this element
getContentType()	Returns content model of element
getParseTree()	Returns the root node of Content Model Parse Tree.
validateContent(Element)	Validates the content of a element node.

Table C-5 XML Parser for Java: NodeFactory() Class

NodeFactory() Member Summary	Description
Constructors
NodeFactory()	Specifies methods to create various nodes of the DOM tree built during parsing. Applications can override these methods to create their own custom classes to be added to the DOM tree while parsing. Applications have to register their own NodeFactory using the XMLParser's setNodeFactory() method. If a null pointer is returned by these methods, then the node will not be added to the DOM tree.
Methods
createAttribute(String, String)	Creates an attribute node with the specified tag, and text.
createCDATASection(String)	Creates a CDATA node with the specified text.
createComment(String)	Creates a comment node with the specified text.
createDocument()	Creates a document node.
createElement(String)	Creates an Element node with the specified tag.
createProcessingInstruction(String, String)	Creates a PI node with the specified tag, and text.
createTextNode(String)	Creates a text node with the specified text.

Table C-6 XML Parser for Java: NSName() and NSResolver Classes

Member Summary	Description
Class NSName	Provides Namespace support for Element and Attribute names.
Methods
getExpandedName()	Gets the fully resolved name for this name
getLocalName()	Gets the local name for this name
getNamespace()	Gets the resolved Namespace for this name
getPrefix()	Gets the prefix for this name
getQualifiedName()	Gets the qualified name
Class NSResolver	Provides support for resolving Namespaces.
Methods
resolveNamespacePrefix(String)	Finds the namespace definition in scope for a given namespace prefix.

Table C-7 XMLParser for Java: SAXAttrList() Class 

Member Summary	Description
Class SAXAttrList()	Implements the SAX AttributeList interface and also provides Namespace support. Applications that require Namespace support can explicitly cast any attribute list returned by an Oracle parser class to SAXAttrList and use the methods described here.It also implements Attributes (SAX 2.0) interface This interface allows access to a list of attributes in three different ways: By attribute index; By Namespace-qualified name; or By qualified (prefixed) name. The list will not contain attributes that were declared #IMPLIED but not specified in the start tag. It will also not contain attributes used as Namespace declarations (xmlns*) unless the http://xml.org/sax/features/namespace-prefixes feature is set to true (it is false by default). If the namespace-prefixes feature (see above) is false, access by qualified name may not be available; if the http://xml.org/sax/features/namespaces feature is false, access by Namespace-qualified names may not be available. This interface replaces the now-deprecated SAX1 interface, which does not contain Namespace support. In addition to Namespace support, it adds the getIndex methods (below). The order of attributes in the list is unspecified, and will vary with each implementation.
Methods
getExpandedName(int)	Get the expanded name for an attribute in the list (by position)
getLength()	Return the number of attributes in this list.
getLocalName(int)	Get the local name for an attribute in the list (by position)
getName(int)	Return the name of an attribute in this list (by position).
getNamespace(int)	Get the resolved namespace for an attribute in the list (by position)
getPrefix(int)	Get the namespace prefix for an attribute in the list (by position)
getQualifiedName(int)	Get the qualified name for an attribute in the list (by position)
/getType(int index)	Looks up an attribute's type by index. The attribute type is one of the strings "CDATA", "ID", "IDREF", "IDREFS", "NMTOKEN", "NMTOKENS", "ENTITY", "ENTITIES", or "NOTATION" (always in upper case). If the parser has not read a declaration for the attribute, or if the parser does not report attribute types, then it must return the value "CDATA" as stated in the XML 1.0 Recommendation (clause 3.3.3, "Attribute-Value Normalization"). For an enumerated attribute that is not a notation, the parser will report the type as "NMTOKEN".
getType(java.lang.String qName)	Looks up an attribute's type by XML 1.0 qualified name.
getType(java.lang.String uri, java.lang.String localName)	Looks up an attribute's type by Namespace name.
getType(String)	Return the type of an attribute in the list (by name).
getValue(int)	Return the value of an attribute in the list (by position).
getValue(String)	Return the value of an attribute in the list (by name).

Member Summary	Description
Constructors
SAXParser()	Creates a new parser object. Implements an eXtensible Markup Language (XML) 1.0 SAX parser according to the World Wide Web Consortium (W3C) recommendation. Applications can register a SAX handler to receive notification of various parser events. XMLReader is the interface that an XML parser's SAX2 driver must implement. This interface allows an application to set and query features and properties in the parser, to register event handlers for document processing, and to initiate a document parse. All SAX interfaces are assumed to be synchronous: the parse methods must not return until parsing is complete, and readers must wait for an event-handler callback to return before reporting the next event. This interface replaces the (now deprecated) SAX 1.0 Parser interface. XMLReader interface contains two important enhancements over the old Parser interface: It adds a standard way to query and set features and properties; and It adds Namespace support, which is required for many higher-level XML standards.
Methods
setDocumentHandler(DocumentHandler)	SAX applications can use this to register a new document event handler.
setDTDHandler(DTDHandler)	SAX applications can use this to register a new DTD event handler.
setEntityResolver(EntityResolver)	SAX applications can use this to register a new entity resolver
setErrorHandler(ErrorHandler)	SAX applications can use this to register a new error event handler.

Table C-9 XML Parser for Java: XMLParser() Class

Member Summary	Description
Class XMLParser()	This class serves as a base class for the DOMParser and SAXParser classes. It contains methods to parse eXtensible Markup Language (XML) 1.0 documents according to the World Wide Web Consortium (W3C) recommendation. This class can not be instantiated (applications can use the DOM or SAX parser depending on their requirements).
Methods
getReleaseVersion()	Returns the release version of the Oracle XML Parser
getValidationMode()	Returns the validation mode
parse(InputSource)	Parses the XML from given input source
parse(InputStream)	Parses the XML from given input stream.
parse(Reader)	Parses the XML from given input stream.
parse(String)	Parses the XML from the URL indicated
parse(URL)	Parses the XML document pointed to by the given URL and creates the corresponding XML document hierarchy.
setBaseURL(URL)	Sets the base URL for loading external entities and DTDs.
setDoctype(DTD)	Sets the DTD
setLocale(Locale)	Applications can use this to set the locale for error reporting.
setPreserveWhitespace(boolean)	Sets the white space preserving mode
setValidationMode(boolean)	Sets the validation mode

Accessing XML Parser for Java

Oracle XML Parsers are provided with Oracle9i Enterprise and Standard editions from release 8.1.6 and higher. If you do not have these editions you can download the XML Parsers from: http://otn.oracle.com/tech/xml/

Installing XML Parser for Java, Version 2

These sections describe how to install the Windows NT and UNIX versions of the XML Parser for Java, Version 2.

XML Parser for Java, Version 2: Windows NT Installation

To install the Oracle XML Parser for Java (v2) on Windows NT follow these steps:

1. Install JDK-1.1.x. or above and either unzip or WinZip executable.

2. Download the Oracle XML Parser in ZIP format.

3. Unzip xmlparser.zip into a directory. For example:

   C:\[your directory]> unzip xmlparser.zip 
   
   

4. The result should be the following files and directories:

• license.html -- copy of license agreement

• readme.html -- release and installation notes

• doc\ -- directory for documents

• lib\ -- directory for parser class files

• sample\ -- sample code files

XML Parser for Java, Version 2: UNIX Installation

To install the XML Parser for Java (v2) in UNIX follow these steps:

1. Install JDK-1.1.x or above and GNU gzip.

2. Download the Oracle XML Parser in .tar.gz format.

3. Extract the distribution package into a directory. For example:

   #gzip -dc xmlparser.tar.gz | tar xvf - 
   

4. The result should be the following files and directories:

• license.html -- copy of license agreement

• readme.html -- release and installation notes

• doc/ -- directory for documents

• lib/ -- directory for parser class files

• sample/ -- sample code files

Sample Code

See Chapter 20, "Using XML Parser for Java", for sample code and suggestions on how to use the XML Parsers.

XML Parser for Java, Version 2 Specifications

The Oracle XML Parser for Java, Version 2 specifications follow:

• New high performance architecture

• Integrated support for W3C XSLT 1.0 Recommendation

• Supports validation and non-validation modes

• Built-in Error Recovery until fatal error

• Integrated Document Object Model (DOM) Level 1.0 and 2.0 API

• Integrated SAX 1.0 and 2.0 API

• Supports W3C Recommendation for XML Namespaces

Requirements

Operating Systems: Any with Java 1.1.x support

JAVA: JDK 1.1.x. or above.

The contents of both the Windows and UNIX versions are identical. They are simply archived differently for operating system compatibility and your convenience.

Online Documentation

Documentation for Oracle XML Parser for Java is located in the doc/ directory in your install area.

Release Specific Notes

The readme.html file in the root directory of the archive contains release specific information including bug fixes, API additions, and so on.

Oracle XML Parser is an early adopter release and is written in Java. It will check if an XML document is well-formed and, optionally, if it is valid. The parser will construct a Java object tree which can be accessed. It also contains an integrated XSLT processor for transforming XML documents.

Standards Conformance

The parser conforms to the following W3C Recommendations:

• Extensible Markup Language (XML) 1.0
  http://www.w3.org/TR/1998/REC-xml-19980210

• Namespaces in XML at
  http://www.w3.org/TR/REC-xml-names/

• Document Object Model Level 1 1.0
  http://www.w3.org/TR/REC-DOM-Level-1/

• Document Object Model Level 2
  http://www.w3.org/TR/DOM-Level-2-Core/

• XML Path Language (XPath) 1.0
  http://www.w3.org/TR/1999/REC-xpath-19991116

• XML Transformations (XSLT) 1.0
  http://www.w3.org/TR/1999/REC-xslt-19991116

The parser also conforms to the following W3C Proposed Recommendations:

• XML Schema Part 1: Structures
  http://www.w3.org/TR/xmlschema-1

• XML Schema Part 2: Datatypes
  http://www.w3.org/TR/xmlschema-2

In addition, the parser implements the following interfaces defined by the XML development community:

• Simple API for XML (SAX) 1.0 and 2.0 at http://www.megginson.com/SAX/index.html

Supported Character Set Encodings

The XML Parser for Java currently supports the following encodings:

• BIG 5

• EBCDIC-CP-*

• EUC-JP

• EUC-KR

• GB2312

• ISO-2022-JP

• ISO-2022-KR

• ISO-8859-1to -9

• ISO-10646-UCS-2

• ISO-10646-UCS-4

• KOI8-R

• Shift_JIS

• US-ASCII

• UTF-8

• UTF-16

Default:

UTF-8 is the default encoding if none is specified. Any other ASCII or EBCDIC based encodings that are supported by the JDK may be used.However, they must be specified in the format required by the JDK instead of as official character set names defined by IANA.

Error Recovery

The parser also provides error recovery. It will recover from most errors and continue processing until a fatal error is encountered.

Oracle XML Parser V1 and V2

Version 2 of the XML Parser for Java, besides incorporating an XSLT processor, has been re-architected from version 1. This has resulted in a number of changes to the class names especially those that support Namespaces. The following summarizes changes you have to take into account when converting code from v1 to v2.

Note: This summary is based upon XML Parser versions v1.0.1.4 as v1 and v2.0.0.0 as v2.

NEW CLASS STRUCTURE

oracle.xml.parser package has been renamed to oracle.xml.parser.v2.

The following are new interfaces:

• NSName

• XMLDocumentHandler

The following interfaces have been removed:

• NSAttr

• NSAttributeList

• NSDocumentHandler

• NSElement

The following are new classes in v2:

• DOMParser

• DefaultXMLDocumentHandler

• SAXAttrList

• SAXParser

• XSLProcessor

• XSLStylesheet

• XSLException

Table C-3 lists the XDK for Java classes that have been reorganized.

Table C-10 XML Parser for Java: Classes Reoganization and Changes

Version 1	Version 2
Class Reorganization
XMLParser	XMLParser (includes methods applicable to DOM and SAX access), DOMParser (includes methods specific to DOM access), SAXParser (includes methods specific to SAX access)
NSDocumentHandler	XMLDocumentHandler
NSAttr	XMLAttr (supports Namespace, NSAttr interface has been removed)
NSAttributeList	SAXAttrList (includes methods in NSAttributeList and org.xml.sax.AttributeList)
NSElement	XMLElement (supports Namespace, NSElelement interface removed)
PUBLIC CLASS / VARIABLE / CONSTRUCTOR / METHOD CHANGES
AttrDecl
getName()	<eliminated> Use XMLNode.getNodeName
getPresence()	getAttrPresence()
getType()	getAttrType()
getValues()	getEnumerationValues()
ElementDecl
ASTERISK	Reserved for future implementation.
COMMA	Reserved for future implementation.
ELEMENT	Reserved for future implementation.
OR	Reserved for future implementation.
PLUS	Reserved for future implementation.
QMARK	Reserved for future implementation.
getParseTree()	Reserved for future implementation.
XMLAttr	New constructor - XMLAttr(String, String, String, String) New methods - cloneNode(), getPrefix()
XMLElement	New constructor - XMLElement(String, String, String) New methods: checkNamespace(String, String) getElementsByTagName(String, String), resolveNamespacePrefix(String)
XMLNode	New method - transformNode()
XMLText	New method - getNodeValue()

XDK for Java: XML Schema Processor

Table C-12 summarizes the XML Schema Processor for Java's classes, constructors, and methods.

See Also: Chapter 21, "Using XML Schema Processor for Java" The readme.txt file in your installed software's doc/ directory. This software can also be downloaded from http://otn.oracle.com/tech/xml

Table C-11 XML Schema Processor for Java: Classes, Constructors, Methods 

Members	Description
Class XMLSchema	Sets top-level XMLSchema document declarations & definitions plus schema location and schema target namespace. XMLSchema objects are created by XSDBuilder as a result of processing XMLSchema documents. They are used by XSDParser for instance XML documents validation and by XSDBuilder as imported schemas.
Constructors XMLSchema() XMLSchema(int)
Class XDSBuilder	Builds an XMLSchema object from XMLSchema document. XMLSchema object is a set of objects (Infoset items) corresponding to top-level schema declarations & definitions. Schema document is 'XML' parsed and converted to a DOM tree. This schema DOM tree is 'Schema' parsed in a following order: (if any) builds a schema object and makes it visible. (if any) is replaced by corresponding DOM tree. Top-level declarations & definitions are registered as a current schema infoset items. Finally, top-level tree elements (infoset items) are 'Schema' parsed. The result XMLSchema object is a set (infoset) of objects (top-level input elements). Object's contents is a tree with nodes corresponding to low-level element/group decls/refs preceded by node/object of type SNode containing cardinality info (min/maxOccurs).
Methods build(InputStream,URL)	Builds an XMLSchema object
build(Reader, URL)	Builds an XMLSchema object
build(String)	Builds an XMLSchema object
build(String, String)	Builds an XMLSchema object
build(String, URL)	Builds an XMLSchema object
build(URL)	Builds an XMLSchema object
build(XMLDocument,URL)	Builds XMLSchema from XML document
getObject()	Returns the schema object.
setError(XMLError)	Sets XMLError object.
setLocale(Locale)	Sets locale for error reporting.
XSDException	Indicates that an exception occurred during XMLSchema validation.
Methods getMessage()	Override getMessage, in order to construct error message from error id, and error params
getMessage(XMLError)	Get localized message based on the XMLError sent as parameter

XDK for Java: XML Class Generator for Java

Oracle XML Class Generator for Java requires Oracle XML Parser for Java. The XML Document, printed by the generated classes, confirms to the W3C recommendation for Extensible Markup Language (XML) 1.0. Oracle XML Class Generator can optionally generate validating Java source files. It also optionally generates Javadoc comments in the source files.

Oracle XML Class Generator supports the following encodings for printing the XMLDocument:

UTF-8, UTF-16, ISO-10646-UCS-2, ISO-10646-UCS-4, US-ASCII, EBCDIC-CP-US, ISO-8859-1, and Shift_SJIS.

ASCII is the default encoding if none is specified. Any other ASCII or EBCDIC based encodings that are supported by the JDK can be used.

Installing XML Class Generator for Java

Installing the Oracle XML Java Class Generator, is described in the following sections.

XML Class Generator for Java: Windows NT Installation

To install Oracle XML Class Generators on Windows NT, follow these steps:

1. Install JDK-1.1.x. or above and either unzip or run the WinZip executable.

2. Download the Oracle XML Class Generator for Java in ZIP format from

   http://otn.oracle.com/tech/xml/classgen

   This Class Generator for Java uses 63KB. Select the following:

   • Software, from the XML top menu >

   • Oracle XML Class Generator for Windows NT

3. Unzip xmlclassgenV1_0_0.zip into a directory. For example:

   C:\[your directory]>unzip xmlclassgenV1_0_0.zip 
   
   

4. The result should be the following files and directories:
   • license.html -- copy of license agreement

   • readme.html -- release and installation notes

   • doc\ -- directory for documents

   • lib\ -- directory for classgen class files

   • sample\ -- sample code files

XML Class Generator for Java: UNIX Installation

To install Oracle XML Class Generator for Java in UNIX, follow these steps:

1. Install JDK-1.1.x or above and GNU gzip.

2. Download the Oracle XML Class Generator for Java in .tar.gz format from

   http://otn.oracle.com/tech/xml/classgen

   This Class Generator for Java uses 63Kb. Select the following:

   • Software, from the XML top menu >

   • Oracle XML Class Generator for UNIX

3. Extract the distribution package into a directory. For example:

   #gzip -dc xmlclassgenV1_0_0.tar.gz | tar xvf - 
   
   

4. The result should be the following files and directories:
   • license.html -- copy of license agreement

   • readme.html -- release and installation notes

   • doc/ -- directory for documents

   • lib/ -- directory for classgen class files

   • sample/ -- sample code files

XML Class Generator for Java Cheat Sheet

Table C-12 lists the main XML Class Generator for Java APIs and top level classes with a brief description of each. Table C-13lists the XML Class Generator for Java methods.

Table C-12 XML Class Generator for Java: APIs and Classes

Classes	Description
Classes
CGDocument	Serves as the base document class for the Class Generated generated classes. Constructor for the Root element of the DTD. Parameters: doctype - Name of the root Element of the DTD, dtd - The DTD used to generate the classes
CGNode	Serves as the base class for nodes generated by the Class Generated
DTDClassGenerator	Used by the Class Generator to generate classes against a DTD
SchemaClassGenerator	Used by the Class Generator to generate classes against a Schema
CGXSDElement	This class is the base class for the classes generated by Schema Class generator. The classes corresponding to the top level elements in a schema extends this class. This class contains the code for initialization and building the schema from the schema file which is required for validation purpose. Note: Since the validation is not supported, the static block for reading the schema file is not used. It should be possible to read schema file from anywhere in the scope of the CLASSPATH. It is required to read the schema file using getResource.
Exceptions
InvalidContentException	Definition of InvalidContentException thrown by dtdcompiler classes

Table C-13 XML Class Generator for Java: Methods 

Methods	Description
Class CGDocument(String, DTD)	Constructor for the Root element of the DTD. public abstract class CGDocument extends CGNode. Serves as the base document class for the DTD compiler generated classes
Methods print(OutputStream)	Prints the constructed XML Document
print(OutputStream, String)	Prints the constructed XML Document
public abstract class CGNode	extends Object. Serves as the base class for nodes generated by the XML Class Generator.
Class generate(DTD, String)	Traverses the DTD with element doctype as root and generates Java classes
Methods setGenerateComments(boolean)	Switch to determine whether to generate java doc comments. Default - TRUE
setJavaPackage(String)	Sets the package for the classes generated. Default - No package
setOutputDirectory(String)	Sets the output directory. Default - current directory
setSerializationMode(boolean)	Switch to determine if the DTD should be saved as a serialized object or as text file.
setValidationMode(boolean)	Switch to determine whether the classes generated should validate the XML Document being constructed.Default - TRUE
Class CGNode(String)	Constructor for the Elements of the DOM Tree
Methods addCDATASection(string)	Adds CDATA Section to the Element.
addData(String)	Adds PCDATA to the Element
addNode(CGNode)	Adds a node as a child to the element
getCGDocument()	Gets the base document (root Element)
getDTDNode()	Gets the static DTD from the base document
setAttribute(String, String)	Sets the value of the Attribute
setDocument(CGDocument)	Sets the base document (root Element)
storeID(String, String)	Store this value for an ID identifier, so that we can later verify IDREF values
storeIDREF(String, String)	Store this value for an IDREF identifier, so that we can later verify, if an corresponding ID was defined.
validateContent()	Checks if the content of the element is valid as per the Content Model specified in DTD
validEntity(String)	Checks if the ENTITY identifier is valid
validID(String)	Checks if the ID identifier is valid
validNMTOKEN(String)	Checks if the NMTOKEN identifier is valid
Class CGXSDElement	This class serves as the base class for the all the generated classes corresponding to the XML Schema generated by Schema Class Generator
Methods
addAttribute(String, String)	Add the attribute of a given node to the hashtable. Parameters: attName - the attribute name, attValue - the attribute value
addElement(Object)	Add the elements of a given element node to the vector corresponding to the elements. Parameters: elem - the object which needs to be added
getAttributes()	public java.util.Hashtable getAttributes(). Return the attributes. Returns: attributes the hashtable containing attribute name and value
getChildElements()	public java.util.Vector getChildElements(). Get the vector having all the local elements. Returns: elemChild vector
getNodeValue()	public java.lang.String getNodeValue(). Return the node value
getType()	public java.lang.Object getType(). Return the type
print(XMLOutputStream)	public void print(oracle.xml.parser.v2.XMLOutputStream. out). Print an element node. Parameters: out - the stream where the output is printed
printAttributes(XMLOutputStream, String)	public void printAttributes(oracle.xml.parser.v2.XMLOutputStream out, java.lang.String name). Print an attribute node. Parameters: out - the stream where the output is printed, name - the attribute name
setNodeValue(String)	protected void setNodeValue(java.lang.String value). Set the node value of an element. Parameters: value - the node value

oracg Command Line Utility

oracg invokes the DTD or Schema Class Generator for Java to generate classes based on DTD and Schema respectively, depending on the input arguments given. Table C-14lists the oracg arguments.

Table C-14 oracg Command Line Utility

oracg Argument	Description
-h	Prints the help message text
- d<dtd file>	DTD file (.dtd file)
- s <schema file>	Schema file (.xsd file)
- o <Output dirname>	Output directory
- c	Comment option
- p <package name/s>	The package names corresponding to namespace

XDK for Java: XSQL Servlet

Downloading and Installing XSQL Servlet

Downloading XSQL Servlet from OTN

You can download XSQL Servlet distribution from:

http://otn.oracle.com/tech/xml/xsql_servlet

1. Click on the 'Software' icon at the top of the page:

2. Log in with your OTN username and password (registration is free if you do not already have an account).

3. Selecting whether you want the NT or Unix download (both contain the same files)

4. Acknowledge the licensing agreement and download survey

5. Clicking on xsqlservlet_v1.0.2.0.tar.gz or xsqlservlet_v1.0.2.0.zip

Extracting the Files in the Distribution

To extract the contents of XSQL Servlet distribution, do the following:

1. Choose a directory under which you would like the .\xsql directory and subdirectories to go, for example, C:\

2. Change directory to C:\, then extract the XSQL downloaded archive file there. For example:

   UNIX:

       tar xvfz xsqlservlet_v1.0.2.0.tar.gz
   
   

   Windows NT:

       pkzip25 -extract -directories xsqlservlet_v1.0.2.0.zip
   
   

   using the pkzip25 command-line tool or the WinZip visual archive extraction tool.

Windows NT: Starting the Web-to-go Server

XSQL Servlet comes bundled with the Oracle Web-to-go server that is pre-configured to use XSQL Pages. The Web-to-go web server is a single-user server, supporting the Servlet 2.1 API, used for mobile application deployment and for development. This is a great way to try XSQL Pages out on your Windows machine before delving into the details of configuring another Servlet Engine to run XSQL Pages.

Note: The Web-to-go Web server is part of Oracle's development and deployment platform for mobile applications. For more information on Web-to-go, see http://www.oracle.com/mobile.

Windows NT users can get started quickly with XSQL Pages by following these steps:

1. Running the xsql-wtg.bat script in the .\xsql directory.

2. Browsing the URL http://localhost:7070/xsql/index.html

If you get an error starting this script, edit the xsql-wtg.bat file to properly set the two environment variables JAVA and XSQL_HOME to appropriate values for your machine.

    REM ----------------------------------------------
    REM Set the 'JAVA' variable equal to the full path
    REM of your Java executable.
    REM ----------------------------------------------
    set JAVA=J:\java1.2\jre\bin\java.exe
    set XSQL_HOME=C:\xsql
    REM ----------------------------------------------
    REM Set the 'XSQL_HOME' variable equal to the full
    REM path of where you install the XSQL Servlet 
    REM distribution.
    REM ----------------------------------------------

Then, repeat the two steps above.

If you get an error connecting to the database when you try the demos, you'll need to go on to the next section, then try the steps above again after setting up your database connection information correctly in the XSQLConfig.xml file.

Setting Up the Database Connection Definitions for Your Environment

The demos are set up to use the SCOTT schema on a database on your local machine (that is, the machine where the web server is running). If you are running a local database and have a SCOTT account whose password is TIGER, then you are all set. Otherwise, you need to edit the .\xsql\lib\XSQLConfig.xml file to correspond to your appropriate values for username, password, dburl, and driver values for the connection named "demo".

<?xml version="1.0" ?>
    <XSQLConfig>
         :
      <connectiondefs>
        <connection name="demo">
          <username>scott</username>
          <password>tiger</password>
          <dburl>jdbc:oracle:thin:@localhost:1521:ORCL</dburl>
          <driver>oracle.jdbc.driver.OracleDriver</driver>
        </connection>
        <connection name="lite">
          <username>system</username>
          <password>manager</password>
          <dburl>jdbc:Polite:POlite</dburl>
          <driver>oracle.lite.poljdbc.POLJDBCDriver</driver>
        </connection>
      </connectiondefs>
          :
</XSQLConfig>

UNIX: Setting Up Your Servlet Engine to Run XSQL Pages

UNIX users and any user wanting to install the XSQL Servlet on other web servers should continue with the instructions below depending on the web server you're trying to use. In every case, there are 3 basic steps:

1. Include the list of XSQL Java archives as well as the directory where XSQLConfig.xml resides (by default ./xsql/lib) in the server CLASSPATH.

   Note: For convenience, the xsqlservlet_v1.0.2.0.tar.gz and xsqlservlet_v1.0.2.0.zip distributions include the .jar files for the Oracle XML Parser for Java (V2), the Oracle XML SQL Utilities for Java, and the 8.1.6 JDBC driver in the .\lib subdirectory, along with Oracle XSQL Pages' own .jar archive.

2. Map the .xsql file extension to the oracle.xml.xsql.XSQLServlet servlet class

3. Map a virtual directory /xsql to the directory where you extracted the XSQL files (to access the on-line help and demos)

XSQL Servlet Specifications

The following lists the XSQL servlet specifications:

• Produce dynamic XML documents based on one or more SQL queries

• Optionally transforms the resulting XML document in the server or client using XSLT

• Supports W3C XML 1.0 Recommendation

• Supports Document Object Model (DOM) Level 1.0 and 2.0 API

• Support the W3C XSLT 1.0 Recommendation

• Supports W3C Recommendation for XML Namespaces

Character Set Support

XSQL Servlet supports the following character set encodings:

• BIG

• EBCDIC-CP-*

• EUC-JP

• EUC-KR

• GB2312

• ISO-2022-JP

• ISO-2022-KR

• ISO-8859-1to -9

• ISO-10646-UCS-2

• ISO-10646-UCS-4

• KOI8-R

• Shift_JIS

• US-ASCII

• UTF-8

• UTF-16

XDK for Java: XSQL Servlet Cheat Sheets

Table C-15 and Table C-16 list XSQL Servlet APIs and top level classes with a brief description of each.

Table C-15 XSQL Servlet Classes  

Class Summary	Description
Interfaces
XSQLActionHandler	Interface that must be implemented by all XSQL Action Element Handlers
XSQLPageRequest	Interface representing a request for an XSQL Page
Classes
XSQLActionHandlerImpl	Base Implementation of XSQLActionHandler that can be extended to create your own custom handlers.
XSQLCommandLine	Command-line Utility to process XSQL Pages.
XSQLPageRequestImpl	Base implementation of the XSQLPageRequest interface that case be used to derive new kinds of page request implementations.
XSQLParserHelper	Common XML Parsing Routines
XSQLRequest	Programmatically process a request for an XSQL Page.
XSQLServlet	Servlet to enable HTTP GET-ing of and POST-ing to XSQL Pages
XSQLServletPageRequest	Implementation of XSQLPageRequest for Servlet-based XSQL Page requests.
XSQLStylesheetProcessor	XSLT Stylesheet Processing Engine

Table C-16 XSQLPageRequest Interface Methods  

Methods	Description
createNestedRequest(URL, Dictionary)	Returns an instance of a nested Request
getConnectionName()	Returns the name of the connection being used for this request May be null if no connection set/in-use.
getErrorWriter()	Returns a PrintWriter to print out errors processing this request
getJDBCConnection()	Gets the JDBC connection being used for this request (can be null)
getPageEncoding()	Returns encoding of source XSQL Page associated with this request
getParameter(String)	Returns the value of the requested parameter
getPostedDocument()	Returns the content of Posted XML for this request as an XML Document
getRequestParamsAsXMLDocument()	Returns the content of a Request parameters as an XML Document
getRequestType()	Returns a string identifying the type of page request being made.
getSourceDocumentURI()	Returns a String representation of the requested document's URI
getStylesheetParameter(String)	Gets a stylesheet parameter by name
getStylesheetParameters()	Gets an enumeration of stylesheet parameter names
getStylesheetURI()	Returns the URI of the stylesheet to be used to process the result.
getUserAgent()	Returns a String identifier of the requesting program
getWriter()	Returns a PrintWriter used for writing out the results of a page request
getXSQLConnection()	Gets the XSQLConnection Object being used for this request Might be null.
isIncludedRequest()	Returns true if this request is being included in another.
isOracleDriver()	Returns true if the current connection uses the Oracle JDBC Driver
printedErrorHeader()	Returns the state of whether an Error Header has been printed
requestProcessed()	Allows Page Request to Perform end-of-request processing
setConnectionName(String)	Sets the connection name to use for this request
setContentType(String)	Sets the content type of the resulting page
setIncludingRequest(XSQLPageRequest)	Sets the Including Page Request object for this request.
setPageEncoding(String)	Sets encoding of source XSQL page associated with this request.
setPageParam(String, String)	Sets a dynamic page parameter value.
setPostedDocument(Document)	Allows programmatic setting of the Posted Document
setPrintedErrorHeader(boolean)	Sets whether an Error Header has been printed
setStylesheetParameter(String, String)	Sets the value of a parameter to be passed to the associated stylesheet
setStylesheetURI(String)	Sets the URI of the stylesheet to be used to process the result.
translateURL(String)	Returns a string representing an absolute URL resolved relative to the base URI for this request.
useConnectionPooling()	Returns true if connection pooling is desired for this request
useHTMLErrors()	Returns true if HTML-formatted error messages are desired for this request

XML SQL Utility for Java Cheat Sheet

See Appendix H, "XML SQL Utility (XSU) Specifications and Cheat Sheets".