oracle.xml.sql.query
Class OracleXMLQuery

java.lang.Object
  |
  +--oracle.xml.sql.query.OracleXMLQuery

public class OracleXMLQuery

extends java.lang.Object

The OracleXMLQuery class does the generation of XML given a SQL query. Following is a very simple example:

  import java.sql.*;
  import oracle.xml.sql.query.*;
  import oracle.jdbc.driver.*;

  public class sample
  {
    public static void main(String args[]) throws Exception
    {
      DriverManager.registerDriver(new oracle.jdbc.driver.OracleDriver());
      Connection conn = 
          DriverManager.getConnection("jdbc:oracle:oci8:scott/tiger@");
      OracleXMLQuery qry =  new OracleXMLQuery(conn, "select * from emp");
      System.out.println(qry.getXMLString());
      conn.close();
    }
  } 
  

Field Summary

Type	Field
static int	DTD The DTD is used to specified that the DTD is to be generated
static java.lang.String	ERROR_TAG The ERROR_TAG specifies the default tag name for the ERROR document
static int	MAXROWS_ALL The MAXROWS_ALL specifies that all rows be included in the result
static int	MAXROWS_DEFAULT Deprecated. since v2.0; Use MAXROWS_ALL instead
static int	MAXROWS_NONE Deprecated. since v2.0; Use 0 instead
static int	NONE The NONE is used to specified that no DTD is to be generated
static java.lang.String	ROW_TAG The ROW_TAG specifies the default tag name for the ROW elements
static java.lang.String	ROWIDATTR_TAG The ROWIDATTR_TAG specifies the default tag name for the ROW elements
static java.lang.String	ROWSET_TAG The ROWSET_TAG specifies the default tag name for the document
static int	SCHEMA The SCHEMA is used to specified that no XML schema is to be generated
static int	SKIPROWS_ALL The SKIPROWS_ALL specifies that all rows be skipped in the result.
static int	SKIPROWS_DEFAULT Deprecated. since v2.0; Use 0 instead
static int	SKIPROWS_NONE Deprecated. since v2.0; Use 0 instead

Constructor Summary

OracleXMLQuery(java.sql.Connection conn, java.sql.ResultSet rset)
Constructor for the OracleXMLQueryObject.

OracleXMLQuery(java.sql.Connection conn, java.lang.String query)
Constructor for the OracleXMLQueryObject.

OracleXMLQuery(oracle.xml.sql.query.OracleXMLDataSet dset)
Constructor for the OracleXMLQueryObject.

Method Summary

Type	Method
void	close() Close any open resource, created by the OracleXML engine.
java.lang.Object	getInternalObj() This is an internal API.
long	getNumRowsProcessed() Returns the number of rows processed.
void	getXML(oracle.xml.sql.query.OracleXMLDocGen doc) NOTE: THIS IS AN INTERNAL CALL Transforms the object-relational data, specified in the constructor, into a XML document which is returned via the doc argument.
void	getXML(oracle.xml.sql.query.OracleXMLDocGen doc, boolean withDTD) Deprecated. since v2.0
void	getXML(oracle.xml.sql.query.OracleXMLDocGen doc, int metaType) NOTE: THIS IS AN INTERNAL CALL Transforms the object-relational data, specified in the constructor, into a XML document which is returned via the doc argument.
Document	getXMLDOM() Transforms the object-relational data, specified in the constructor, into a XML document.
Document	getXMLDOM(boolean withDTD) Deprecated. since 1.2.1; please use getXMLDOM(int) instead
Document	getXMLDOM(int metaType) Transforms the object-relational data, specified in the constructor, into a XML document.
Document	getXMLDOM(Node root) Transforms the object-relational data, specified in the constructor, into XML.
Document	getXMLDOM(Node root, int metaType) Transforms the object-relational data, specified in the constructor, into XML.
java.lang.String	getXMLMetaData(int metaType, boolean withVer) This functions returns the DTD or the XMLSchema for the XML document which would have been generated by a getXML call.
void	getXMLMetaData(int metaType, boolean withVer, oracle.xml.sql.query.OracleXMLDocGen doc) NOTE: THIS IS AN INTERNAL CALL This functions returns the DTD or the XMLSchema for the XML document which would have been generated by a getXML call.
void	getXMLSAX(ContentHandler sax) Transforms the object-relational data, specified in the constructor, into a XML document.
Document[]	getXMLSchema() This methods generated the XML Schema(s) corresponding to the specified query.
java.lang.String	getXMLString() Transforms the object-relational data, specified in the constructor, into a XML document.
java.lang.String	getXMLString(boolean withDTD) Deprecated. since 1.2.1; please use getXMLString(int) instead
java.lang.String	getXMLString(int metaType) Transforms the object-relational data, specified in the constructor, into a XML document.
java.lang.String	getXMLString(Node root) Transforms the object-relational data, specified in the constructor, into XML.
java.lang.String	getXMLString(Node root, int metaType) Transforms the object-relational data, specified in the constructor, into XML.
void	keepCursorState(boolean alive) Deprecated. since 1.2.1; use keepObjectOpen instead.
void	keepObjectOpen(boolean alive) The default behavior for all the getXML functions which DO NOT TAKE in a ResultSet object is to close the ResultSet object and Statement objects at the end of the call.
void	removeXSLTParam(java.lang.String name) Removes the value of a top-level stylesheet parameter.
void	setCollIdAttr(java.lang.String collIdAttr) Deprecated. since 1.2.1; please use setCollIdAttrName instead.
void	setCollIdAttrName(java.lang.String attrName) Sets the name of the id attribute of the collection element's separator tag.
void	setDataHeader(java.io.Reader header, java.lang.String docTag) Sets the xml data header.
void	setDateFormat(java.lang.String mask) Sets the format of the generated dates in the XML doc.
void	setEncoding(java.lang.String enc) Sets the encoding PI (processing instruction) in the XML doc.
void	setErrorTag(java.lang.String tag) Sets the tag to be used to enclose the xml error docs.
void	setException(java.lang.Exception e) Allows the user to pass in an exception, and have the XSU handle it.
void	setMaxRows(int rows) Sets the max number of rows to be converted to XML.
void	setMetaHeader(java.io.Reader header) Sets the XML meta header.
void	setRaiseException(boolean flag) Tells the XSU to throw the raised exceptions.
void	setRaiseNoRowsException(boolean flag) Tells the XSU to throw or not to throw an OracleXMLNoRowsException in the case when for one reason or another, the XML doc generated is empty.
void	setRowIdAttrName(java.lang.String attrName) Sets the name of the id attribute of the row enclosing tag.
void	setRowIdAttrValue(java.lang.String colName) Specifies the scalar column whose value is to be assigned to the id attribute of the row enclosing tag.
void	setRowIdColumn(java.lang.String colName) Deprecated. since 1.2.1 -- please use setRowIdAttrValue instead.
void	setRowsetTag(java.lang.String tag) Sets the tag to be used to enclose the xml dataset.
void	setRowTag(java.lang.String tag) Sets the tag to be used to enclose the xml element corresponding to a db.
void	setSkipRows(int rows) Sets the number of rows to skip.
void	setSQLToXMLNameEscaping(boolean flag) This turns on or off escaping of XML tags in the case that the SQL object name, which is mapped to a XML identifier, is not a valid XML identifier.
void	setStyleSheet(java.lang.String uri) Deprecated. since XSU2.0 -- please use setStylesheetHeader instead.
void	setStyleSheet(java.lang.String uri, java.lang.String type) Deprecated. since XSU2.0 -- please use setStylesheetHeader instead.
void	setStylesheetHeader(java.lang.String uri) Sets the stylesheet header (i.e.
void	setStylesheetHeader(java.lang.String uri, java.lang.String type) Sets the stylesheet header (i.e.
void	setXSLT(java.io.Reader stylesheet, java.lang.String ref) Registers a XSL transform to be applied to generated XML.
void	setXSLT(java.lang.String stylesheet, java.lang.String ref) Registers a XSL transform to be applied to generated XML.
void	setXSLTParam(java.lang.String name, java.lang.String value) Sets the value of a top-level stylesheet parameter.
void	useLowerCaseTagNames() This will set the case to be lower for all tag names.
void	useNullAttributeIndicator(boolean flag) Specified weather to use an XML attribute to indicate NULLness, or to do it by omitting the inclusion of the particular entity in the XML document.
void	useTypeForCollElemTag(boolean flag) By default the tag name for elements of a collection is the collection's tag name followed by "_item".
void	useUpperCaseTagNames() This will set the case to be upper for all tag names.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

MAXROWS_NONE

public static final int MAXROWS_NONE

Deprecated. since v2.0; Use 0 instead

MAXROWS_ALL

public static final int MAXROWS_ALL

The MAXROWS_ALL specifies that all rows be included in the result

MAXROWS_DEFAULT

public static final int MAXROWS_DEFAULT

Deprecated. since v2.0; Use MAXROWS_ALL instead

SKIPROWS_NONE

public static final int SKIPROWS_NONE

Deprecated. since v2.0; Use 0 instead

SKIPROWS_ALL

public static final int SKIPROWS_ALL

The SKIPROWS_ALL specifies that all rows be skipped in the result.

SKIPROWS_DEFAULT

public static final int SKIPROWS_DEFAULT

Deprecated. since v2.0; Use 0 instead

NONE

public static final int NONE

The NONE is used to specified that no DTD is to be generated

DTD

public static final int DTD

The DTD is used to specified that the DTD is to be generated

SCHEMA

public static final int SCHEMA

The SCHEMA is used to specified that no XML schema is to be generated

ROWSET_TAG

public static final java.lang.String ROWSET_TAG

The ROWSET_TAG specifies the default tag name for the document

ROW_TAG

public static final java.lang.String ROW_TAG

The ROW_TAG specifies the default tag name for the ROW elements

ERROR_TAG

public static final java.lang.String ERROR_TAG

The ERROR_TAG specifies the default tag name for the ERROR document

ROWIDATTR_TAG

public static final java.lang.String ROWIDATTR_TAG

The ROWIDATTR_TAG specifies the default tag name for the ROW elements

Constructor Detail

OracleXMLQuery

public OracleXMLQuery(java.sql.Connection conn,
                      java.lang.String query)

Constructor for the OracleXMLQueryObject.

Parameters:

conn - database connection

query - the SQL query string

OracleXMLQuery

public OracleXMLQuery(java.sql.Connection conn,
                      java.sql.ResultSet rset)

Constructor for the OracleXMLQueryObject.

Parameters:

conn - database connection

rset - jdbc result set object

OracleXMLQuery

public OracleXMLQuery(oracle.xml.sql.query.OracleXMLDataSet dset)

Constructor for the OracleXMLQueryObject.

Parameters:

conn - database connection

dset - dataset

Method Detail

getXMLString

public java.lang.String getXMLString()

Transforms the object-relational data, specified in the constructor, into a XML document.

Returns:

the string representation of the XML document

getXMLString

public java.lang.String getXMLString(int metaType)

Transforms the object-relational data, specified in the constructor, into a XML document. The metaType argument is used to specify the type of XML metadata the XSU is to generate along with the XML. Valid values for the metaType argument are NONE and DTD (static fields of this class).

Parameters:

metaType - the type of XML metadata (NONE, DTD, or SCHEMA)

Returns:

the string representation of the XML document

getXMLString

public java.lang.String getXMLString(boolean withDTD)

Deprecated. since 1.2.1; please use getXMLString(int) instead

getXMLString

public java.lang.String getXMLString(Node root)

Transforms the object-relational data, specified in the constructor, into XML. If not NULL, the root argument, is considered the "root" element of the XML doc.

Parameters:

root - root node to which to append the new XML

Returns:

the string representation of the XML document

getXMLString

public java.lang.String getXMLString(Node root,
                                     int metaType)

Transforms the object-relational data, specified in the constructor, into XML. If not NULL, the root argument, is considered the "root" element of the XML doc. The metaType argument is used to specify the type of XML metadata the XSU is to generate along with the XML. Valid values for the metaType argument are NONE and DTD (static fields of this class). Note that if the root argument is non-null, no DTD is generated even if requested.

Parameters:

root - root node to which to append the new XML

metaType - the type of XML metadata (NONE, DTD, or SCHEMA)

Returns:

the string representation of the XML document

getXMLDOM

public Document getXMLDOM()

Transforms the object-relational data, specified in the constructor, into a XML document.

Returns:

the DOM representation of the XML document

getXMLDOM

public Document getXMLDOM(Node root)

Transforms the object-relational data, specified in the constructor, into XML. If not NULL, the root argument, is considered the "root" element of the XML doc.

Parameters:

root - root node to which to append the new XML

Returns:

the string representation of the XML document

getXMLDOM

public Document getXMLDOM(int metaType)

Transforms the object-relational data, specified in the constructor, into a XML document. The metaType argument is used to specify the type of XML metadata the XSU is to generate along with the XML. Currently this value is ignored, and no XML metadata is generated.

Parameters:

metaType - the type of XML metadata (NONE, SCHEMA)

Returns:

the string representation of the XML document

getXMLDOM

public Document getXMLDOM(boolean withDTD)

Deprecated. since 1.2.1; please use getXMLDOM(int) instead

getXMLDOM

public Document getXMLDOM(Node root,
                          int metaType)

Transforms the object-relational data, specified in the constructor, into XML. If not NULL, the root argument, is considered the "root" element of the XML doc. The metaType argument is used to specify the type of XML metadata the XSU is to generate along with the XML. Currently this value is ignored, and no XML metadata is generated.

Parameters:

root - root node to which to append the new XML

metaType - the type of XML metadata (NONE, SCHEMA)

Returns:

the string representation of the XML document

getXMLSAX

public void getXMLSAX(ContentHandler sax)

Transforms the object-relational data, specified in the constructor, into a XML document.

Parameters:

sax - ContentHandler object to be registered

getXML

public void getXML(oracle.xml.sql.query.OracleXMLDocGen doc)

NOTE: THIS IS AN INTERNAL CALL Transforms the object-relational data, specified in the constructor, into a XML document which is returned via the doc argument.

Parameters:

doc - object containing the generated XML document

getXML

public void getXML(oracle.xml.sql.query.OracleXMLDocGen doc,
                   boolean withDTD)

Deprecated. since v2.0

getXML

public void getXML(oracle.xml.sql.query.OracleXMLDocGen doc,
                   int metaType)

NOTE: THIS IS AN INTERNAL CALL Transforms the object-relational data, specified in the constructor, into a XML document which is returned via the doc argument.

Parameters:

doc - object containing the generated XML document

metaType - type of XML metadata to generate (NONE or DTD)

getNumRowsProcessed

public long getNumRowsProcessed()

Returns the number of rows processed.

Returns:

number of rows processed.

getXMLMetaData

public java.lang.String getXMLMetaData(int metaType,
                                       boolean withVer)

This functions returns the DTD or the XMLSchema for the XML document which would have been generated by a getXML call. The "metaType" parameter specifies the type of XML metadata to be generated. The withVer parameter specifies if version header is to be generated or not.

Parameters:

metaType - XML meta data type to generate (NONE or DTD)

withVer - generate the version PI ?

getXMLMetaData

public void getXMLMetaData(int metaType,
                           boolean withVer,
                           oracle.xml.sql.query.OracleXMLDocGen doc)

NOTE: THIS IS AN INTERNAL CALL This functions returns the DTD or the XMLSchema for the XML document which would have been generated by a getXML call. The "metaType" parameter specifies the type of XML metadata to be generated. The withVer parameter specifies if version header is to be generated or not.

Parameters:

metaType - XML meta data type to generate (NONE or DTD)

withVer - generate the version PI ?

doc - object into which to write the metadata

getXMLSchema

public Document[] getXMLSchema()

This methods generated the XML Schema(s) corresponding to the specified query.

Returns:

the XML Schema(s)

setMetaHeader

public void setMetaHeader(java.io.Reader header)

Sets the XML meta header. When set, the header is inserted at the begining of the metadata part (DTD or XMLSchema) of each XML document generated by this object. Note that the last meta header specified is the one that is used; furthermore, passing in null for the header, parameter unsets the meta header.

Parameters:

header - header

setDataHeader

public void setDataHeader(java.io.Reader header,
                          java.lang.String docTag)

Sets the xml data header. The data header is an XML entity which is appended at the begining of the query-generated xml entity (ie. rowset). The two entities are enclosed by the tag specified via the docTag argument. Note that the last data header specified is the one that is used; furthermore, passing in null for the header, parameter unsets the data header.

Parameters:

header - header

tag - tag used to enclose the data header and the rowset

setEncoding

public void setEncoding(java.lang.String enc)

Sets the encoding PI (processing instruction) in the XML doc. If null or an empty string are specified as the encoding, then the default characterset is specified in the encoding PI.

Parameters:

enc - characterset encoding of the XML doc

setDateFormat

public void setDateFormat(java.lang.String mask)

Sets the format of the generated dates in the XML doc. The syntax of the date format patern (i.e. the date mask), should conform to the requirements of the java.text.SimpleDateFormat class. Setting the mask to null or an empty string, unsets the date mask.

Parameters:

mask - the date mask

setRowsetTag

public void setRowsetTag(java.lang.String tag)

Sets the tag to be used to enclose the xml dataset.

Parameters:

tag - tag name

setRowTag

public void setRowTag(java.lang.String tag)

Sets the tag to be used to enclose the xml element corresponding to a db. record.

Parameters:

tag - tag name

setErrorTag

public void setErrorTag(java.lang.String tag)

Sets the tag to be used to enclose the xml error docs.

Parameters:

tag - tag name

setRowIdAttrName

public void setRowIdAttrName(java.lang.String attrName)

Sets the name of the id attribute of the row enclosing tag. Passing null or an empty string for the tag results the row id attribute to be omitted.

Parameters:

attrName - attribute name

setRowIdAttrValue

public void setRowIdAttrValue(java.lang.String colName)

Specifies the scalar column whose value is to be assigned to the id attribute of the row enclosing tag. Passing null or an empty string for the colName results the row id attribute being assigned the row count value (i.e. 0, 1, 2 and so on).

Parameters:

colName - column whose value is to be assigned to the row id attr

setRowIdColumn

public void setRowIdColumn(java.lang.String colName)

Deprecated. since 1.2.1 -- please use setRowIdAttrValue instead.

setCollIdAttrName

public void setCollIdAttrName(java.lang.String attrName)

Sets the name of the id attribute of the collection element's separator tag. Passing null or an empty string for the tag results the row id attribute to be omitted.

Parameters:

attrName - attribute name

setCollIdAttr

public void setCollIdAttr(java.lang.String collIdAttr)

Deprecated. since 1.2.1; please use setCollIdAttrName instead.

useTypeForCollElemTag

public void useTypeForCollElemTag(boolean flag)

By default the tag name for elements of a collection is the collection's tag name followed by "_item". This method, when called with argument of true, tells the XSU to use the collection element's type name as the collection element tag name.

Parameters:

flag - use the coll. elem. type as its tag name?

useNullAttributeIndicator

public void useNullAttributeIndicator(boolean flag)

Specified weather to use an XML attribute to indicate NULLness, or to do it by omitting the inclusion of the particular entity in the XML document.

Parameters:

flag - use attribute to indicate null?

setStylesheetHeader

public void setStylesheetHeader(java.lang.String uri)

Sets the stylesheet header (i.e. stylesheet processing instructions) in the generated XML doc. Note: Passing null for the uri argument will unset the stylesheet header and the stylesheet type.

Parameters:

uri - stylesheet URI

setStyleSheet

public void setStyleSheet(java.lang.String uri)

Deprecated. since XSU2.0 -- please use setStylesheetHeader instead.

setStylesheetHeader

public void setStylesheetHeader(java.lang.String uri,
                                java.lang.String type)

Sets the stylesheet header (i.e. stylesheet processing instructions) in the generated XML doc. Note: Passing null for the uri argument will unset the stylesheet header and the stylesheet type.

Parameters:

uri - stylesheet URI

type - stylesheet type; defaults to 'text/xsl'

setStyleSheet

public void setStyleSheet(java.lang.String uri,
                          java.lang.String type)

Deprecated. since XSU2.0 -- please use setStylesheetHeader instead.

setXSLT

public void setXSLT(java.lang.String stylesheet,
                    java.lang.String ref)

Registers a XSL transform to be applied to generated XML. If a stylesheet was already registered, it gets replaced by the new one. To un-register the stylesheet pass in a null for the stylesheet argument.

Parameters:

stylesheet - the stylesheet URI

ref - URL for include, import and external entities

setXSLT

public void setXSLT(java.io.Reader stylesheet,
                    java.lang.String ref)

Registers a XSL transform to be applied to generated XML. If a stylesheet was already registered, it gets replaced by the new one. To un-register the stylesheet pass in a null for the stylesheet argument.

Parameters:

stylesheet - the stylesheet

ref - URL for include, import and external entities

setXSLTParam

public void setXSLTParam(java.lang.String name,
                         java.lang.String value)

Sets the value of a top-level stylesheet parameter. The parameter value is expected to be a valid XPath expression (note that string literal values would therefore have to be explicitly quoted). NOTE: if no stylesheet is registered, this method is a no op.

Parameters:

name - parameter name

value - parameter value as an XPATH expression

removeXSLTParam

public void removeXSLTParam(java.lang.String name)

Removes the value of a top-level stylesheet parameter. NOTE: if no stylesheet is registered, this method is a no op.

Parameters:

name - parameter name

setSQLToXMLNameEscaping

public void setSQLToXMLNameEscaping(boolean flag)

This turns on or off escaping of XML tags in the case that the SQL object name, which is mapped to a XML identifier, is not a valid XML identifier.

Parameters:

flag - turn on SQL to XML identifier escaping.

useLowerCaseTagNames

public void useLowerCaseTagNames()

This will set the case to be lower for all tag names. Note, make this call after all the desired tags have been set.

useUpperCaseTagNames

public void useUpperCaseTagNames()

This will set the case to be upper for all tag names. Note, make this call after all the desired tags have been set.

setException

public void setException(java.lang.Exception e)

Allows the user to pass in an exception, and have the XSU handle it.

Parameters:

e - the exception to be processed by the XSU.

setRaiseException

public void setRaiseException(boolean flag)

Tells the XSU to throw the raised exceptions. If this call isn't made or if false is passed to the flag argument, the XSU catches the SQL exceptions and generates an XML doc out of the exception's message.

Parameters:

flag - throw raised exceptions?

setRaiseNoRowsException

public void setRaiseNoRowsException(boolean flag)

Tells the XSU to throw or not to throw an OracleXMLNoRowsException in the case when for one reason or another, the XML doc generated is empty. By default, the exception is not thrown.

Parameters:

flag - throw OracleXMLNoRowsException if no data found?

setMaxRows

public void setMaxRows(int rows)

Sets the max number of rows to be converted to XML. By default there is no max set. To explicitly specify no max see MAXROWS_ALL.

Parameters:

rows - max number of rows to generate

setSkipRows

public void setSkipRows(int rows)

Sets the number of rows to skip. By default 0 rows are skipped. To skip all the rows use SKIPROWS_ALL.

Parameters:

rows - number of rows to skip

close

public void close()

Close any open resource, created by the OracleXML engine. This will not close for instance resultset supplied by the user

keepObjectOpen

public void keepObjectOpen(boolean alive)

The default behavior for all the getXML functions which DO NOT TAKE in a ResultSet object is to close the ResultSet object and Statement objects at the end of the call. If you need to use the persistant feature, where by calling getXML repeatedly you get the next set of rows, you need to turn off this behavior by calling this function with value true. i.e. OracleXMLQuery would not close the ResultSet and Statement objects after the getXML calls. You can call the close() function to explicitly close the cursor state.

Parameters:

alive - keep object open ?

keepCursorState

public void keepCursorState(boolean alive)

Deprecated. since 1.2.1; use keepObjectOpen instead.

getInternalObj

public java.lang.Object getInternalObj()

This is an internal API.