Internet Access to Advanced Queuing, 5 of 9

Deploying the AQ XML Servlet

The AQ XML servlet is a Java class that extends the oracle.AQ.xml.AQxmlServlet class. The AQxmlServlet class extends the javax.servlet.http.HttpServlet class.

Creating the AQ XML Servlet Class

The AQ servlet creates a JDBC OCI connection pool to connect to the Oracle9i server. The init() method of the servlet must specify an AQxmlDataSource object that encapsulates the database connection parameters and the username and password. See the Oracle9i Supplied Java Packages Reference for information on the AQxmlDataSource class.

The user specified in the AQxmlDataSource is the AQ servlet super-user. This user must have CREATE SESSION privilege and EXECUTE privilege on the DBMS_AQIN package.

Example:

Create a user AQADM as the AQ servlet super-user as follows:

connect sys/change_on_install as sysdba;
grant connect, resource to aqadm identified by aqadm;
grant create session to aqadm;
grant execute on dbms_aqin to aqadm;

A sample servlet can be created using this superuser as follows:

import javax.servlet.*;
import javax.servlet.http.*;
import oracle.AQ.xml.*;

/**
 * This is a sample AQ Servlet.  
 */
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);
      }
      catch (Exception ex)
      {
          System.out.println("Exception in init: " + ex);
      }
}

The superclass oracle.AQ.xml.AQxmlServlet implements the doPost() and doGet() methods in javax.servlet.http.HttpServlet. The doPost() method handles incoming IDAP requests and performs the requested AQ operations.

Note:

The example assumes that the AQ servlet is installed in a Web server that implements Javasoft's Servlet2.2 specification (such as Tomcat 3.1). For a Web server that implements the Servlet 2.0 specification (such as Apache Jserv), you should extend the oracle.AQ.xml.AQxmlServlet20 class instead of the AQxmlServlet class and override the appropriate write() method.

Compiling the AQ XML Servlet

The AQ servlet can be deployed with any Web server or servlet-runner that implements Javasoft's Servlet2.0 or Servlet2.2 interfaces (for example, Apache Jserv or Tomcat). Note the following considerations:

Because the servlet uses JDBC OCI drivers to connect to the Oracle9i server, the Oracle9i client libraries must be installed on the machine hosting the servlet, as follows:

The LD_LIBRARY_PATH must contain $ORACLE_HOME/lib

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

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

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

After setting the CLASSPATH, compile the servlet using javac or any other Java compiler.

User Authentication

After the servlet is installed, the Web server must be configured to authenticate all users that send POST requests to the AQ servlet. The AQ servlet allows only authenticated users to access the servlet. If the user is not authenticated, an error is returned by the servlet.

The Web server can be configured in multiple ways to restrict access. Some of the common techniques are basic authentication (username/password) over SSL and client certificates. Consult your Web server documentation to see how you can restrict access to servlets.

Using HTTP

In the context of the AQ servlet, the user name that is used to connect to the Web server is known as the AQ HTTP agent or AQ Internet user.

Example:

In Apache, the following can be used to restrict access (using basic authentication) to servlets installed under aqserv/servlet. In this example, all users sending POST requests to the servlet are authenticated using the users file in /apache/htdocs/userdb.

<Location /aqserv/servlet>
  <Limit POST>	
    AuthName "AQ restricted stuff"
    AuthType Basic	
    AuthUserFile /apache/htdocs/userdb/users
    require valid-user	
  </Limit>
</Location>

User Authorization

After authenticating the users who connect to the AQ servlet, you establish which operations the users are authorized to perform by doing the following:

Register the AQ agent for Internet access.
Map the AQ agent to one or more database users.

Registering the AQ Agent

To register the AQ agent for Internet access, use DBMS_AQADM.CREATE_AQ_AGENT. The CREATE_AQ_AGENT procedure takes an agent_name. You specify which protocols the user can use to access the servlet--HTTP, SMTP, or both. For agents accessing the AQ servlet using SMTP, an LDAP certificate_location must also be specified. See "Setup for Receiving AQ XML Requests Using SMTP (Email)" for more information.

Example

Create an AQ agent JOHN to access the AQ servlet using HTTP.

DBMS_AQADM.CREATE_AQ_AGENT(agent_name => 'JOHN', enable_http => true);

The procedures ALTER_AQ_AGENT and DROP_AQ_AGENT for altering and dropping AQ agents function similarly to CREATE_AQ_AGENT. These procedures are documented in the Oracle9i Supplied PL/SQL Packages and Types Reference.

Mapping the AQ Agent to Database Users

To map an AQ agent to one or more database users, use DBMS_AQADM.ENABLE_DB_ACCESS. With the ENABLE_DB_ACCESS procedure, you give an AQ agent the privileges of a particular database user. This allows the agent to access all queues that are visible to the database users to which the agent is mapped.

Example

Map the AQ Internet agent JOHN to database users OE (overseas shipping) and CBADM (customer billing administrator).

DBMS_AQADM.ENABLE_DB_ACCESS(agent_name =>'JOHN', db_username => 'OE');
DBMS_AQADM.ENABLE_DB_ACCESS(agent_name =>'JOHN', db_username => 'CBADM');

Database Sessions

When the user sends a POST request to the servlet, the servlet parses the request to determine which queue/topic the user is trying to access. Accordingly, the AQ servlet creates a database session as one of the database users (db_user) that maps to the AQ agent. The db_user selected has privileges to access the queue specified in the request.

Example

AQ agent JOHN sends an enqueue request to OE.OE_NEW_ORDERS_QUE. The servlet sees that JOHN can map to db_users OE and CBADM. Since OE.OE_NEW_ORDERS_QUE is in the OE schema, it does a CREATE SESSION as OE to perform the requested operation.

The AQ servlet creates a connection pool to the Oracle server using the AQ servlet super-user. This super-user creates sessions on behalf of db_users that the AQ Internet agent maps to. Hence the super-user must have privileges to create proxy sessions for all the users specified in the ENABLE_DB_ACCESS call. See "Creating the AQ XML Servlet Class" for how to create the AQ servlet super-user.

The AQ servlet super-user can be granted CREATE PROXY session privileges as follows:

connect sys/change_on_install as sysdba
rem grant super-user AQADM privileges to create proxy sessions as OE
alter user OE grant CONNECT THROUGH AQADM;

rem grant super-user AQADM privileges to create proxy sessions as CBADM
alter user CBADM grant CONNECT THROUGH AQADM;

If an AQ Internet agent is mapped to more than one db_user, then all the db_users must have the FORCE ANY TRANSACTION privilege:

grant FORCE ANY TRANSACTION to OE; 
grant FORCE ANY TRANSACTION to CBADM;

To disable the mapping between an agent and a database user, use DBMS_AQADM.DISABLE_DB_ACCESS.

The SYSTEM.AQ$INTERNET_USERS view lists AQ agents, the protocols they are enabled for, and the mapping between AQ agents and database users. Example entries in this view are shown in Table 17-8.

agent_name	db_username	http_enabled	smtp_enabled
scott	cbadmin	YES	NO
scott	buyer	YES	NO
aqadmin	OE	YES	YES
aqadmin	seller	YES	YES
bookstore		NO	YES

Table 17-8

agent_name db_username http_enabled smtp_enabled

scott

cbadmin

YES

NO

scott

buyer

YES

NO

aqadmin

OE

YES

YES

aqadmin

seller

YES

YES

bookstore

NO

YES

The SYSTEM.AQ$INTERNET_USERS View

Using an LDAP Server with an AQ XML Servlet

An LDAP server is required if:

The AQ agent is accessing the AQ servlet using SMTP. (See "Setup for Receiving AQ XML Requests Using SMTP (Email)" for details.)
The lookup_type destination attribute is specified as LDAP. In this case the destination name is resolved to a schema.queue_name using the LDAP server.
You use agent_alias instead of (agent_name, address, protocol). If an agent_alias is specified in a client request, it is resolved to agent_name, address, protocol using the LDAP server.

The LDAP context must be specified by the setLDAPContext(DirContext) call, as follows:

public void init()
{
		      Hashtable env = new Hashtable(5, 0.75f);
		      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);

           env.put(Context.INITIAL_CONTEXT_FACTORY, 
                   "com.sun.jndi.ldap.LdapCtxFactory");
           env.put(Context.PROVIDER_URL, "ldap://yow:389");
           env.put(SEARCHBASE, "cn=server1,cn=dbservers,cn=wei");
           env.put(Context.SECURITY_AUTHENTICATION, "simple");
           env.put(Context.SECURITY_PRINCIPAL, "cn=orcladmin");
           env.put(Context.SECURITY_CREDENTIALS, "welcome");

	           DirContext inictx = new InitialDirContext(env);
	           String searchbase = (String)env.get("server_dn");
	           lctx = (DirContext)inictx.lookup(searchbase);

	           // Set up LDAP context
	           setLdapContext(lctx);

	           // Set the EMAIL server address (if any)
	           setEmailServerAddr("144.25.186.236");
      }
      catch (Exception ex)
      {
	         System.err.println("Servlet init exception: " +ex) ;
      }
 }

Setup for Receiving AQ XML Requests Using SMTP (Email)

You must set up the database, Web server, LDAP server, and email server to receive AQ XML requests using SMTP.

Database and LDAP Server Setup

To store AQ agents in the LDAP server, the database must be registered to the LDAP server using the Database Configuration Assistant (DBCA), and the value of GLOBAL_TOPIC_ENABLED must be set to TRUE (default is FALSE; reset using alter system set global_topic_enabled=TRUE).

To create AQ agents that can access the servlet using SMTP, use the DBMS_AQADM.CREATE_AQ_AGENT procedure.

Example

Create an AQ agent for the appl application to access the AQ servlet using SMTP and the digital certificate of the application owner, Kurt:

DBMS_AQADM.CREATE_AQ_AGENT(
   agent_name => 'appl',  
   enable_http => true, 
   enable_smtp => true, 
   certificate_location => 'cn=kurt,cn=acme,cn=com');

The certificate_location parameter is required to authenticate the appl application when a message is received.

Web Server Setup

Establish a user called ORACLE_SMTP_AGENT on the Web server that is allowed to access the AQ servlet.

The Oracle email server will connect to the servlet using user ORACLE_SMTP_AGENT.
Specify the email server host name or the IP address in the servlet's init( ) method.

Use setEmailServerHost(hostname) or setEmailServerAddr(ip_address)in the AQxmlServlet to do this.

Example: Specify the email server host as follows:
```
setEmailServerAddr("144.25.186.236");  or 
setEmailServerHost("email-srv.us.oracle.com");
```
Set up an LDAP context in the servlet, as described in "Using an LDAP Server with an AQ XML Servlet".

The LDAP server is used to retrieve certificates for the AQ agent and verify the signature in the incoming message.

Email Server Setup

Internet access to AQ using SMTP requires Oracle Email Server 5.5. Do the following:

Check that DBMS_AQST is installed on the email server.
Create an email account for the destination database, that is, the database against which AQ operations are to be performed using the AQ servlet.

See Also:
Oracle eMail Server 5.5 Administration Guide for how to create an email account on the email server.
Set up an email rule for the destination database email account so that it can handle AQ XML client requests by sending them to the AQ servlet.

The following information is required:
- The email account of the destination database, for example, 'aqdb1';
- The password of the email account, for example, 'welcome'
- The domain in which this email account resides, for example, 'acme.com'
- The complete email address of the destination email address, for example, 'aqdb1@acme.com'
- The name of the destination database, for example, 'aqdb1'
- The URL of the destination database servlet, for example,
```
 http://aq-sun.us.oracle.com:8000/aqserv/servlet/AQTestServlet
```
- The user name and password to access the destination database servlet (user name is ORACLE_SMTP_AGENT; password is established in "Web Server Setup").
- The host and port for LDAP lookup. For example, host=ldaphost, port=389.
- The base distinguished name (DN) for LDAP lookup, that is, the DN of the destination database in the LDAP server, for example, 'cn=aqdb1, cn=oraclecontext,cn=acme,cn=com'.
- The login DN and password for LDAP lookup, for example NULL for anonymous binds.

declare
   status binary_integer;
begin
   status := dbms_aqst.register_db(
      'aqdb1', -- email user account for aqdb1
      'welcome', -- email user password
      'acme.com', -- email user domain
      'aqdb1@acme.com', -- complete email address
      'aqdb1', -- name of destination database
      'http://aq-sun:8000/aqserv/servlet/AQTestServlet', -- URL to access 
the destination database servlet
      'welcome', -- password of ORACLE_SMTP_AGENT
      'ldaphost', -- LDAP host for lookup client certificates
      '389', -- LDAP port for LDAP lookup
      'cn=aqdb1,cn=oraclecontext,cn=acme,cn=com', -- base DN of LDAP lookup
      NULL, NULL -- anonymous bind
      );
   dbms_output.put_line('register DB status: ' || status);
end;

Make sure the operation returns status 0.

After the setup is complete, an AQ agent can send email messages to the database email address to perform AQ operations. The AQ operations should be constructed according to IDAP, signed using the Oracle email S/MIME toolkit, and sent as a binary attachment with the name including IDAP_MESSAGE.