Oracle9i Application Developer's Guide - Advanced Queuing Release 1 (9.0.1) Part Number A88890-02 |
|
Internet Access to Advanced Queuing, 5 of 9
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.
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.
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.
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:
The LD_LIBRARY_PATH
must contain $ORACLE_HOME/lib
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
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
CLASSPATH
, compile the servlet using javac
or any other Java compiler.
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.
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.
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>
After authenticating the users who connect to the AQ servlet, you establish which operations the users are authorized to perform by doing the following:
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.
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.
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.
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');
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
) t
hat maps to the AQ agent. The db_user
selected has privileges to access the queue specified in the request.
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 |
An LDAP server is required if:
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.
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) ; } }
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.
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.
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
.
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");
The LDAP server is used to retrieve certificates for the AQ agent and verify the signature in the incoming message.
Internet access to AQ using SMTP requires Oracle Email Server 5.5. Do the following:
DBMS_AQST
is installed on the email server.
The following information is required:
'aqdb1'
;
'welcome'
'acme.com'
'aqdb1@acme.com'
'aqdb1'
http://aq-sun.us.oracle.com:8000/aqserv/servlet/AQTestServlet
ORACLE_SMTP_AGENT
; password is established in "Web Server Setup").
host=ldaphost
, port=389.
'cn=aqdb1, cn=oraclecontext,cn=acme,cn=com'
.
dbms_aqst
:
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;
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
.
|
Copyright © 1996-2001, Oracle Corporation. All Rights Reserved. |
|