5
Package oracle.AQ.xml

This package contains classes required by the Oracle9i Advanced Queuing (AQ) XML Servlet. This servlet is used to access Oracle9i AQ via open protocols like HTTP and SMTP using the Internet Data Access Presentation(iDAP).

The servlet can be created by defining a Java class that extends the oracle.AQ.xml.AQxmlServlet or oracle.AQ.xml.AQxmlServlet20 class. These classes inturn extend the javax.servlet.http.HttpServlet class.

The servlet can be deployed in any Webserver or ServletRunner that implements Javasoft's Servlet 2.0 or Servlet 2.2 interfaces

1. To deploy the AQ Servlet with a webserver that implements Javasoft's Servlet2.0 interfaces, users must define a class that extends the oracle.AQ.xml.AQxmlServle20 class.

2. To deploy the AQ Servlet with a webserver that implements Javasoft's Servlet2.2 interfaces, users must define a class that extends the oracle.AQ.xml.AQxmlServlet class.

The servlet can be compiled using JDK 1.1.x or JDK 1.2.x libraries.

3. For JDK 1.1.x the CLASSPATH must contain:

   $ORACLE_HOME/jdbc/lib/classes111.zip 
   $ORACLE_HOME/jdbc/lib/jta.zip
   $ORACLE_HOME/jdbc/lib/nls_charset11.zip
   $ORACLE_HOME/jdbc/lib/jndi.zip
   $ORACLE_HOME/lib/lclasses11.zip
   $ORACLE_HOME/lib/xmlparserv2.jar
   $ORACLE_HOME/lib/xschema.jar
   $ORACLE HOME/rdbms/jlib/aqapi11.jar
   $ORACLE_HOME/rdbms/jlib/jmscommon.jar
   $ORACLE_HOME/rdbms/jlib/aqxml.jar
   $ORACLE_HOME/rdbms/jlib/xsu111.jar
   $ORACLE_HOME/jis/lib/servlet.jar
   

4. For JDK 1.2.x the CLASSPATH must contain:

   $ORACLE_HOME/jdbc/lib/classes12.zip
   $ORACLE_HOME/jdbc/lib/jta.zip
   $ORACLE_HOME/jdbc/lib/nls_charset12.zip
   $ORACLE_HOME/jdbc/lib/jndi.zip
   $ORACLE_HOME/lib/lclasses12.zip
   $ORACLE_HOME/lib/xmlparserv2.jar
   $ORACLE_HOME/lib/xschema.jar
   $ORACLE_HOME/rdbms/jlib/aqapi.jar
   $ORACLE_HOME/rdbms/jlib/jmscommon.jar
   $ORACLE_HOME/rdbms/jlib/aqxml.jar
   $ORACLE_HOME/rdbms/jlib/xsu12.jar
   $ORACLE_HOME/jis/lib/servlet.jar
   

Since the servlet uses JDBC OCI drivers to connect to the Oracle9i server, it is required that 9i Oracle Client libraries be installed on the machine that hosts the servlet. The LD_LIBRARY_PATH must contain $ORACLE_HOME/lib

For more information on Internet access to AQ, refer to Oracle Application Developer's guide - Advanced Queuing

---

Package Oracle.AQ.xml Description

Class Summary
Interfaces
AQxmlCallback	This interface is used to define callbacks to be invoked before/after the servlet performs AQ operations.
Classes
AQxmlDataSource	The AQ data source is used the specify the backend database to which the servlet connects to perform AQ operations.
AQxmlServlet	AQxmlServlet - this is the AQ xml servlet which handles HTTP POST requests from clients. To be used with Servlet 2.2 implementations
AQxmlServlet20	AQxmlServlet - this is the AQ xml servlet which handles HTTP POST requests from clients. To be used with Servlet 2.0 implementations
AQxmlCallbackContext	This is the context passed to the user before/after callback functions This CallbackContext has methods to retrieve the parsed XML document, get a JDBC connection to the AQ database, override the response stream sent by the servlet and set the xml style sheet for the response
AQxmlDebug	AQ xml Debug class
Exceptions
AQxmlException	AQ XML Exception

---

AQxmlCallback

Syntax

public interface AQxmlCallback

Description

This interface is used to define callbacks to be invoked before/after the servlet performs AQ operations. The callback must be defined in the init method of the servlet by using the setUserCallback method The callback methods get the servlet request stream, the servlet response and the callback context. The CallbackContext has methods to retrieve the parsed XML document, get a JDBC connection to the AQ database, and override the response stream sent by the servlet

Member Summary
Methods
afterAQOperation(HttpServletRequest, HttpServletResponse, AQxmlCallbackContext)	Callback invoked after any AQ operations are performed by the servlet
beforeAQOperation(HttpServletRequest, HttpServletResponse, AQxmlCallbackContext)	Callback invoked before any AQ operations are performed by the servlet

Methods

afterAQOperation(HttpServletRequest, HttpServletResponse, AQxmlCallbackContext)

public void afterAQOperation(oracle.AQ.xml.HttpServletRequest request, 
oracle.AQ.xml.HttpServletResponse response, AQxmlCallbackContext ctx)

Callback invoked after any AQ operations are performed by the servlet

Parameters:

request - servlet request

response - servlet response

ctx - Callback context

beforeAQOperation(HttpServletRequest, HttpServletResponse, AQxmlCallbackContext)

public void beforeAQOperation(oracle.AQ.xml.HttpServletRequest request, 
oracle.AQ.xml.HttpServletResponse response, AQxmlCallbackContext ctx)

Callback invoked before any AQ operations are performed by the servlet

Parameters:

request - servlet request

response - servlet response

ctx - Callback context

---

AQxmlDataSource

Syntax

public class AQxmlDataSource extends java.lang.Object
 
java.lang.Object
  |
  +--oracle.AQ.xml.AQxmlDataSource

Description

The AQ data source is used the specify the backend database to which the servlet connects to perform AQ operations. It contains the database SID, host name, listener port and the username/password of the AQ servlet super-user. The AQ servlet uses the JDBC-OCI driver to connect to the database. It creates a connection cache - the default size of the connection pool is 5.

Member Summary
Constructors
AQxmlDataSource(OracleOCIConnectionPool pool_ds)	Creates an AQ data source
AQxmlDataSource(String, String, String, String, String)	Creates an AQ data source
Methods
getCacheSize()	Get the size of the connection cache
getDBDrv()	Get the JDBC driver used by the data source
getHost()	Get the host name
getPort()	Get the listener port
getSid()	Get the database SID
setCacheSize(int)	Set the size of the connection cache

Inherited Member Summary
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructors

AQxmlDataSource(OracleOCIConnectionPool pool_ds)

public  AQxmlDataSource(OracleOCIConnectionPool pool_ds)

Creates an AQ data source given an OCI connection pool

Parameters:

pool_ds - OCI connection pool

Throws:

AQxmlException - if fails to create a data source

AQxmlDataSource(String, String, String, String, String)

public  AQxmlDataSource(java.lang.String user, java.lang.String password, 
java.lang.String sid, java.lang.String host, java.lang.String port)

Creates an AQ data source

Parameters:

user - username

password - user password

sid - database SID

port - listener port

Throws:

AQxmlException - if fails to create a data source

Methods

getCacheSize()

public int getCacheSize()

Get the size of the connection cache

getDBDrv()

public java.lang.String getDBDrv()

Get the JDBC driver used by the data source

getHost()

public java.lang.String getHost()

Get the host name

getPort()

public java.lang.String getPort()

Get the listener port

getSid()

public java.lang.String getSid()

Get the database SID

setCacheSize(int)

public void setCacheSize(int csize)

Set the size of the connection cache

Parameters:

csize - cache size

---

AQxmlCallbackContext

Syntax

public class AQxmlCallbackContext extends java.lang.Object
 
java.lang.Object
  |
  +--oracle.AQ.xml.AQxmlCallbackContext

Description

This is the context passed to the user before/after callback functions This CallbackContext has methods to retrieve the parsed XML document, get a JDBC connection to the AQ database, override the response stream sent by the servlet and set the xml style sheet for the response

Member Summary
Methods
getDBConnection()	Get the JDBC connection that is used to perform this request Users can perform SQL operations using this database connection.
getOverrideAQResponseFlag()
getServerResponseDoc()	Get the AQxmlDocument representing the response that will be sent back from the servlet.
getStyleSheetProcessingInstr()	Get the stylesheet processing instruction for the XML response
parseRequestStream()	Parse the XML document in the servlet request
setOverrideAQResponseFlag(boolean)	Set flag to override the response sent back by the AQ servlet.
setStyleSheet(String, String)	Set StyleSheet for the XML response.
setStyleSheetProcessingInstr(String)	Set StyleSheet processing instruction for the XML response.

Inherited Member Summary
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods

getDBConnection()

public java.sql.Connection getDBConnection()

Get the JDBC connection that is used to perform this request Users can perform SQL operations using this database connection. The operations performed will be part of the same transaction as the AQ operations. They will be committed or aborted when the AQ operation in the IDAP message is committed or aborted. Users cannot call commit/rollback on these connections. Commit/Rollback has to be done by sending an IDAP message to the servlet.

getOverrideAQResponseFlag()

public boolean getOverrideAQResponseFlag()

getServerResponseDoc()

public AQxmlDocument getServerResponseDoc()

Get the AQxmlDocument representing the response that will be sent back from the servlet. This is available only in the afterAQOperation callback

getStyleSheetProcessingInstr()

public java.lang.String getStyleSheetProcessingInstr()

Get the stylesheet processing instruction for the XML response

parseRequestStream()

public oracle.AQ.xml.Document parseRequestStream()

Parse the XML document in the servlet request

setOverrideAQResponseFlag(boolean)

public void setOverrideAQResponseFlag(boolean value)

Set flag to override the response sent back by the AQ servlet. The AQ servlet sends back an IDAP response to the requestor. User callbacks can set this flag if they want to write their own response instead of the one sent back by AQ

setStyleSheet(String, String)

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

Set StyleSheet for the XML response. This can be used to set a xml-stylesheet processing instruction for the XML responses that will be sent fo this request

Parameters:

type - stylesheet type (Example: "text/xml")

href - stylesheet href (Example: "http://www.aq.com/AQ/xslt.html" )

Throws:

AQxmlException - if invalid parameters specified

setStyleSheetProcessingInstr(String)

public void setStyleSheetProcessingInstr(java.lang.String proc_instr)

Set StyleSheet processing instruction for the XML response. This can be used to set a xml-stylesheet processing instruction for the XML responses that will be sent fo this request

Parameters:

proc_instr - stylesheet processing instruction

(Example: "type=\"text/xsl\" href=\"http://www.oa.com/AQ/xslt23.html\"" )

---

AQxmlServlet

Syntax

public class AQxmlServlet implements java.lang.Runnable
 
oracle.AQ.xml.AQxmlServlet

All Implemented Interfaces:

java.lang.Runnable

Description

AQxmlServlet - this is the AQ xml servlet which handles HTTP POST requests from clients. This servlet can be deployed in any servlet engine that implements Javasoft's Servlet2.2 standard. Users are required to extend this servlet and define a AQ data source (to connect to the database instance) before deploying it

Member Summary
Methods
doGet(HttpServletRequest, HttpServletResponse)	this method handles HTTP GET requests.
doPost(HttpServletRequest, HttpServletResponse)	this method handles HTTP POST requests. This is the main entry point for the AQ xml servlet.
getAQDataSource()	get the AQ data source that will be used by this servlet to the database
getEmailServerAddr()	Get the IP address of the email server
getEmailServerHost()	Get the email server host name
getUserCallback()	get the callback registered by the user
setAQDataSource(AQxmlDataSource)	Subclasses must call this method in the init method of the servlet to specify the database connect parameters (username/password, sid, portno etc)
setAQSchemaLocation(String)	setAQxmlSchemaLocation - set the location of the AQ IDAP schema.
setEmailServerAddr(String)	Set the IP address of the Email server.
setLdapContext(DirContext)	Set the LDAP context for the servlet.
setSessionMaxInactiveTime(int)	Set the maximum time a session can remain inactive.
setStyleSheet(String, String)	Set StyleSheet for responses.
setStyleSheetProcessingInstr(String)	Set StyleSheet processing instruction for responses.
setUserCallback(AQxmlCallback)	setUserCallback - set the user callback.

Methods

doGet(HttpServletRequest, HttpServletResponse)

protected void doGet(oracle.AQ.xml.HttpServletRequest request, 
oracle.AQ.xml.HttpServletResponse response)

This method handles HTTP GET requests. This is just used to test whether the servlet has been deployed successfully. In general all AQ operations must be sent as HTTP POST requests.

doPost(HttpServletRequest, HttpServletResponse)

protected void doPost(oracle.AQ.xml.HttpServletRequest request, 
oracle.AQ.xml.HttpServletResponse response)

This method handles HTTP POST requests. This is the main entry point for the AQ xml servlet. This routine expects the incoming stream to be of type text/xml which contains an XML message conforming to he IDAP schema

Parameters:

request - - the http post request

response - - the response object. The output is written to this stream

Throws:

ServletException, - IOException

getAQDataSource()

public synchronized AQxmlDataSource getAQDataSource()

get the AQ data source that will be used by this servlet to the database

getEmailServerAddr()

public java.lang.String getEmailServerAddr()

Get the IP address of the email server

getEmailServerHost()

public java.lang.String getEmailServerHost()

Get the email server host name

getUserCallback()

public final AQxmlCallback getUserCallback()

get the callback registered by the user

setAQDataSource(AQxmlDataSource)

public final synchronized void setAQDataSource(AQxmlDataSource data_source)

Subclasses must call this method in the init method of the servlet to specify the database connect parameters (username/password, sid, portno etc)

Parameters:

data_source - the AQ data source

setAQSchemaLocation(String)

public synchronized void setAQSchemaLocation(java.lang.String schema_location)

setAQxmlSchemaLocation - set the location of the AQ IDAP schema. By default we pick up the schema from the envelope.xsd, aqxml.xsd file in the aqxml.jar file

setEmailServerAddr(String)

public synchronized void setEmailServerAddr(java.lang.String ip_address)

Set the IP address of the Email server.

Parameters:

ip_address - IP address of email server

setLdapContext(DirContext)

public final synchronized void setLdapContext(oracle.AQ.xml.DirContext ctx)

Set the LDAP context for the servlet. This context must be set in the init method of the servlet, if the IDAP messages may contain queue/topic aliases that are to be looked up in an LDAP server.

Parameters:

ctx - LDAP directory context

setSessionMaxInactiveTime(int)

protected synchronized void setSessionMaxInactiveTime(int secs)

Set the maximum time a session can remain inactive. If the session remains inactive for more than this time, the session is destroyed and all operations that have not been committed are rolled back. By default this is set to 120 seconds

Parameters:

secs - time in seconds. This value cannot be set to less than 30secs

setStyleSheet(String, String)

public synchronized void setStyleSheet(java.lang.String type, java.lang.String 
href)

Set StyleSheet for responses. This can be called in the init method of the servlet to set a xml-stylesheet processing instruction for all XML responses sent by the servlet

Parameters:

type - stylesheet type (e.g: "text/xml")

href - stylesheet href (e.g: "http://www.aq.com/AQ/xslt.html" )

Throws:

AQxmlException - if invalid parameters specified

setStyleSheetProcessingInstr(String)

public void setStyleSheetProcessingInstr(java.lang.String proc_instr)

Set StyleSheet processing instruction for responses. This can be called in the init method of the servlet to set a xml-stylesheet processing instruction for all XML responses sent by the servlet

Parameters:

proc_instr - stylesheet processing instruction (e.g: "type=\"text/xsl\" href=\"http://www.oa.com/AQ/xslt23.html\"" )

setUserCallback(AQxmlCallback)

public final void setUserCallback(AQxmlCallback callback)

setUserCallback - set the user callback. The callback methods are invoked before and after AQ operations

Parameters:

callback - user callback

---

AQxmlServlet20

Syntax

public class AQxmlServlet20 implements java.lang.Runnable
 
oracle.AQ.xml.AQxmlServlet20

All Implemented Interfaces:

java.lang.Runnable

Description

AQxmlServlet - this is the AQ xml servlet which handles HTTP POST requests from clients. This servlet can be deployed in any servlet engine that implements Javasoft's Servlet2.0 standard. Users are required to extend this servlet and define a AQ data source (to connect to the database instance) before deploying it

Member Summary
Methods
doGet(HttpServletRequest, HttpServletResponse)	this method handles HTTP GET requests.
doPost(HttpServletRequest, HttpServletResponse)	this method handles HTTP POST requests. This is the main entry point for the AQ xml servlet.
getAQDataSource()	get the AQ data source that will be used by this servlet to the database
getEmailServerAddr()	Get the IP address of the email server
getEmailServerHost()	Get the email server host name
getUserCallback()	get the callback registered by the user
setAQDataSource(AQxmlDataSource)	subclasses must call this method in the init call to specify the database connect parameters (username/password, sid, portno etc)
setAQSchemaLocation(String)	setAQxmlSchemaLocation - set the location of the AQ IDAP schema.
setEmailServerAddr(String)	Set the IP address of the Email server.
setLdapContext(DirContext)	Set the LDAP context for the servlet.
setManualInvalidation(boolean)	Set flag to turn on/off manual session invalidation For Servlet2.0 implementations we start a thread to automatically invalidate sessions that have stayed inactive beyond the max inactive time.
setSessionMaxInactiveTime(int)	Set the maximum time a session can remain inactive.
setStyleSheet(String, String)	Set StyleSheet for responses.
setStyleSheetProcessingInstr(String)	Set StyleSheet processing instruction for responses.
setUserCallback(AQxmlCallback)	setUserCallback - set the user callback.

Methods

doGet(HttpServletRequest, HttpServletResponse)

protected void doGet(oracle.AQ.xml.HttpServletRequest request, 
oracle.AQ.xml.HttpServletResponse response)

This method handles HTTP GET requests. This is just used to test whether the servlet has been deployed successfully. In general all AQ operations must be sent as HTTP POST requests.

doPost(HttpServletRequest, HttpServletResponse)

protected void doPost(oracle.AQ.xml.HttpServletRequest request, 
oracle.AQ.xml.HttpServletResponse response)

This method handles HTTP POST requests. This is the main entry point for the AQ xml servlet. This routine expects the incoming stream to be of type text/xml which contains an XML message conforming to he IDAP schema

Parameters:

request - - the http post request

response - - the response object. The output is written to this stream

Throws:

ServletException, - IOException

getAQDataSource()

public synchronized AQxmlDataSource getAQDataSource()

get the AQ data source that will be used by this servlet to the database

getEmailServerAddr()

public java.lang.String getEmailServerAddr()

Get the IP address of the email server

getEmailServerHost()

public java.lang.String getEmailServerHost()

Get the email server host name

getUserCallback()

public final AQxmlCallback getUserCallback()

get the callback registered by the user

setAQDataSource(AQxmlDataSource)

public final synchronized void setAQDataSource(AQxmlDataSource data_source)

Subclasses must call this method in the init method of the servlet to specify the database connect parameters (username/password, sid, portno etc)

Parameters:

data_source - the AQ data source

setAQSchemaLocation(String)

public synchronized void setAQSchemaLocation(java.lang.String schema_location)

setAQxmlSchemaLocation - set the location of the AQ IDAP schema. By default we pick up the schema from the envelope.xsd, aqxml.xsd file in the aqxml.jar file

setEmailServerAddr(String)

public synchronized void setEmailServerAddr(java.lang.String ip_address)

Set the IP address of the Email server.

Parameters:

ip_address - IP address of email server

setLdapContext(DirContext)

public final synchronized void setLdapContext(oracle.AQ.xml.DirContext ctx)

Set the LDAP context for the servlet. This context must be set in the init method of the servlet, if the IDAP messages may contain queue/topic aliases that are to be looked up in an LDAP server.

Parameters:

ctx - LDAP directory context

setManualInvalidation(boolean)

protected synchronized void setManualInvalidation(boolean flag)

Set flag to turn on/off manual session invalidation For Servlet2.0 implementations we start a thread to automatically invalidate sessions that have stayed inactive beyond the max inactive time. If your servlet runner does its own invalidation of sessions, you may set this flag to false.

Parameters:

flag - true => indicates manual session invalidation is turned on false => indicates manual session invalidation is turned off

setSessionMaxInactiveTime(int)

protected synchronized void setSessionMaxInactiveTime(int secs)

Set the maximum time a session can remain inactive. If the session remains inactive for more than this time, the session is destroyed and all operations that have not been committed are rolled back. By default this is set to 120 seconds

Parameters:

secs - time in seconds. This value cannot be set to less than 30secs

setStyleSheet(String, String)

public synchronized void setStyleSheet(java.lang.String type, java.lang.String 
href)

Set StyleSheet for responses. This can be called in the init method of the servlet to set a xml-stylesheet processing instruction for all XML responses sent by the servlet

Parameters:

type - stylesheet type (e.g: "text/xml")

href - stylesheet href (e.g: "http://www.aq.com/AQ/xslt.html" )

Throws:

AQxmlException - if invalid parameters specified

setStyleSheetProcessingInstr(String)

public void setStyleSheetProcessingInstr(java.lang.String proc_instr)

Set StyleSheet processing instruction for responses. This can be called in the init method of the servlet to set a xml-stylesheet processing instruction for all XML responses sent by the servlet

Parameters:

proc_instr - stylesheet processing instruction (e.g: "type=\"text/xsl\" href=\"http://www.oa.com/AQ/xslt23.html\"" )

setUserCallback(AQxmlCallback)

public final void setUserCallback(AQxmlCallback callback)

setUserCallback - set the user callback. The callback methods are invoked before and after AQ operations

Parameters:

callback - user callback

---

AQxmlDebug

Syntax

public class AQxmlDebug extends java.lang.Object
 
java.lang.Object
  |
  +--oracle.AQ.xml.AQxmlDebug

Description

This class has static methods to set trace levels for the AQ Servlet. Do not use unless instructed by Oracle Support

Member Summary
Methods
getLogStream()	Get log stream to which trace information is written
getPrintWriter()	Get print stream
getTraceLevel()	Get trace level
setDebug(boolean)	Set debug flag
setLogStream(OutputStream)	Set log stream to which trace information is written
setTraceLevel(int)	Set trace level - AQ_ORA_TR1..5

Inherited Member Summary
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods

getLogStream()

public static java.io.OutputStream getLogStream()

Get log stream to which trace information is written

getPrintWriter()

public static java.io.PrintWriter getPrintWriter()

Get print stream

getTraceLevel()

public static int getTraceLevel()

Get trace level

setDebug(boolean)

public static void setDebug(boolean val)

Set debug flag

setLogStream(OutputStream)

public static void setLogStream(java.io.OutputStream output_stream)

Set log stream to which trace information is written

Parameters:

output - log stream

setTraceLevel(int)

public static void setTraceLevel(int level)

Set trace level

0 - no tracing (default)

1 - fatal errors

2 - other errors, imp messages

3 - exception trace, other trace info

4 - method entry/exit

5 - print stack traces, variables

---

AQxmlException

Syntax

public class AQxmlException extends java.lang.Exception
 
java.lang.Object
  |
  +--java.lang.Throwable
        |
        +--java.lang.Exception
              |
              +--oracle.AQ.xml.AQxmlException

All Implemented Interfaces:

java.io.Serializable

Description

AQ XML Exception

Member Summary
Methods
getErrorCode()	Get the Oracle Error code for the exception
getNextException()	Get the exception linked to this one.
setNextException(Exception)	Set the linked exception

Inherited Member Summary
Methods inherited from class java.lang.Throwable
fillInStackTrace, getLocalizedMessage, getMessage, printStackTrace, printStackTrace, printStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods

getErrorCode()

public int getErrorCode()

Get the Oracle Error code for the exception

getNextException()

public java.lang.Exception getNextException()

Get the exception linked to this one.

setNextException(Exception)

protected void setNextException(java.lang.Exception exc)

Set the linked exception

Parameters:

exc - linked exception