Internet Access to Advanced Queuing, 9 of 9

Customizing the AQ Servlet

The oracle.AQ.xml.AQxmlServlet provides the API to set the connection pool size, session timeout, style sheet, and callbacks before and after AQ operations.

Setting the Connection Pool Size

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 data source is represented by the AQxmlDataSource class, which can be set using the setAQDataSource method in the servlet. See the Oracle9i Supplied Java Packages Reference for more information.

The AQ data source creates a pool of 5 connections to the database server by default. If you expect more concurrency, increase the minimum pool size by using the AQxmlDataSource.setCacheSize(size) method. The default cache scheme is OracleConnectionCacheImpl.DYNAMIC_SCHEME.This implies that the number of connections in the cache grows and shrinks dynamically based on the incoming requests. If you wish to set a maximum limit on the number of connections, you must specify a cache size using the AQxmlDataSource.setCacheSize(size) method and set the cache scheme to OracleConnectionCacheImpl.FIXED_WAIT_SCHEME using the AQxmlDataSource.setCacheScheme()method.

Setting the Session Timeout

After a client is authenticated and connects to the AQ servlet, an HTTP session is created on behalf of the user. The first request in the session also implicitly starts a new database transaction. This transaction remains open until it is explicitly committed or aborted.

Each HTTP session has a default timeout of 120 seconds. If the user does not commit or rollback the transaction in 120 seconds after the last request that session, the transaction is automatically aborted. This timeout can be specified in the init() method of the servlet by using setSessionMaxInactiveTime() method.

The servlet is initialized as follows:

public class AQTestServlet extends oracle.AQ.xml.AQxmlServlet
{ 
  /* The init method must be overloaded to specify the AQxmlDataSource */
  public void init()
  {
      AQxmlDataSource  db_drv = null;

      try
      {
        /* Create data source with username, password, sid, host, port */
        db_drv = new AQxmlDataSource("AQADM", "AQADM", 
                                     "test_db", "sun-248", "5521");

	        /* Set the minimum cache size to 10 connections */
			        db_drv.getCacheSize(10);

        this.setAQDataSource(db_drv);

	        /* Set the transaction timeout to 180 seconds */	
	        this.setSessionMaxInactiveTime(180);
      }
      catch (Exception ex)
      {
          System.out.println("Exception in init: " + ex);
      }
}

Setting the Style Sheet for All Responses from the Servlet

The AQ servlet sends back responses in XML. The servlet administrator can specify a style sheet that is to be set for all responses sent back from this servlet. This can be done by invoking the setStyleSheet(type,href)or the setStyleSheetProcessingInstr(proc_instr) in init() method of the servlet.

For example, to include the following style sheet instruction for all responses, do the following:

<?xml-stylesheet type="text/xsl" 
href="http://sun-248/stylesheets/bookOrder.xsl"?>

The servlet is initialized as follows:

public class AQTestServlet extends oracle.AQ.xml.AQxmlServlet
{ 
  /* The init method must be overloaded to specify the AQxmlDataSource */
  public void init()
  {
      AQxmlDataSource  db_drv = null;

      try
      {
        /* Create data source with username, password, sid, host, port */
        db_drv = new AQxmlDataSource("AQADM", "AQADM", 
                                     "test_db", "sun-248", "5521");

        this.setAQDataSource(db_drv);

	        /* Set the bookOrder.xsl style sheet for all responses */
        setStyleSheet("text/xsl", 
"http://sun-248:8000/stylesheets/bookOrder.xsl");
      }
      catch (Exception ex)
      {
          System.out.println("Exception in init: " + ex);
      }
}

Callbacks Before and After AQ Operations

The AQ servlet allows you to register callbacks that will be invoked before and after AQ operations are performed. This allows users to perform AQ and non-AQ operations in the same transaction.

To receive callbacks, users register an object that implements the oracle.AQ.xml.AQxmlCallback interface. The AQxmlCallback interface has the following methods:

public interface AQxmlCallback
{

  /** Callback invoked before any AQ operations are performed by the servlet */
  public void beforeAQOperation(HttpServletRequest request, 				HttpServletResponse 
response, 
                                				AQxmlCallbackContext ctx);
  
  /** Callback invoked after any AQ operations are performed by the servlet */
  public void afterAQOperation(HttpServletRequest request, HttpServletResponse 
response, 
                         			       AQxmlCallbackContext ctx);
}

The callbacks are passed in the HTTP request and response streams and an AQxmlCallbackContext object. The object has the following methods:

The java.sql.Connection getDBConnection() method gives a handle to the database connection that is used by the servlet for performing AQ operations. Users can perform other SQL operations in the callback functions using this connection object.
Note that you cannot call close(), commit() or rollback() methods on this connection object.
org.w3c.org.Document parseRequestStream() gives a DOM document representing the parsed request stream.
The void setStyleSheet(String type,String href)method allows the user to set the style sheet for a particular call. So instead of specifying a single style sheet for all responses from this servlet, users can set style sheets for specific responses.

The style sheet specified in the callback overrides the style sheet (if any) specified for the servlet in the init() method

Example

Before any AQ operation in the servlet, you want to insert a row in the EMP table. Do this by creating a callback class and associating it with a particular servlet as follows:

import javax.servlet.*;
import javax.servlet.http.*;
import oracle.AQ.xml.*;
import java.sql.*;
import javax.jms.*;

/**
 * This is a sample AQ Servlet callback 
 */
public class TestCallback implements oracle.AQ.xml.AQxmlCallback
{ 

   /** Callback invoked before any AQ operations are performed by the servlet */
  public void beforeAQOperation(HttpServletRequest request, 				HttpServletResponse 
response, 
			        AQxmlCallbackContext ctx)
  {
	      Connection conn = null;
      System.out.println("Entering BeforeAQ Callback ...");

	      try
      {
            // Get the connection object from the callback context
 	           conn = ctx.getDBConnection();

            // Insert value in the EMP table
            PreparedStatement pstmt = 
            conn.prepareStatement ("insert into EMP (EMPNO, ENAME) values (100, 
'HARRY')");
            pstmt.execute ();
            pstmt.close();
      }
      catch (Exception ex)
      {
          System.out.println("Exception ex: " + ex);
      } 
  }
  
  /** Callback invoked after any AQ operations are performed by the servlet */
  public void afterAQOperation(HttpServletRequest request,			 HttpServletResponse 
response, 
			       AQxmlCallbackContext ctx)      
  {
      System.out.println("Entering afterAQ Callback ...");
      
      try
      {
	         // Set style sheet for response
         ctx.setStyleSheetProcessingInstr(
	                 "type='text/xsl href='http://sun-248/AQ/xslt23.html'");

      }
      catch (Exception aq_ex)
      {
           	System.out.println("Exception: " + ex);
	
      }
  }
}
 
/* Sample AQ servlet - using user-defined callbacks */ 
public class AQTestServlet extends oracle.AQ.xml.AQxmlServlet
{ 
  
  /* The init method must be overloaded to specify the AQxmlDataSource */
  public void init()
  {
      AQxmlDataSource  db_drv = null;
	      AQxmlCallback    serv_cbk  = new TestCallback();

      try
      {
        /* Create data source with username, password, sid, host, port */
        db_drv = new AQxmlDataSource("AQADM", "AQADM", "test_db", "sun-248", 
"5521");

        this.setAQDataSource(db_drv);

	        /* Set Callback */
	        setUserCallback(serv_cbk);

      }
      catch (Exception ex)
      {
          System.out.println("Exception in init: " + ex);
      }
}