/
/ $Header: aqxmlREADME.txt 08-apr-2002.11:57:57 rbhyrava Exp $
/
/ aqxmlREADME.txt
/
/ Copyright (c) Oracle Corporation 2001. All Rights Reserved.
/
/   NAME
/     aqxmlREADME.txt 
/
/   DESCRIPTION
/     This document contains the list and description of aqxml 
/     provided 
/   NOTES
/     <other useful comments, qualifications, etc.>
/
/   MODIFIED   (MM/DD/YY)
/   rbhyrava    04/08/02 - 
/   rbhyrava    03/20/02 - comments
/   rbhyrava    02/26/02 - params
/   rbhyrava    02/20/02 - httpd.conf
/   rbhyrava    02/07/02 - remove initaqhp.sql, rmaqhp.sql
/   rbhyrava    01/18/02 - 9iR2 updates
/   rbhyrava    07/20/01 - add jssl jar for ssl
/   rbhyrava    06/20/01 - nt specific
/   rbhyrava    04/29/01 - comments
/   rbhyrava    04/23/01 - JAVA_COMPILER
/   rbhyrava    04/12/01 - Merged rbhyrava_aqxmldemos
/   rbhyrava    03/30/01 - Creation
/

The following files are required for running AQXML samples

 aqxmlusr.sql - Set up database users/internet AQ agents 
 aqxmldmo.sql - Create Queue tables and Queues
 aqxmldrp.sql - Drop/Cleanup AQ xml demo objects(users/queue tables/queues)

 aqxml01.xml  AQXmlSend
              Enqueue to ADT single consumer queue with piggyback commit

 aqxml02.xml  AQXmlReceive
              Dequeue from ADT Single consumer queue with piggyback commit

 aqxml03.xml  AQXmlPublish
              Enqueue to ADT (with LOB) multi consumer queue

 aqxml04.xml  AQXmlReceive
              Dequeue from ADT multi consumer queue

 aqxml05.xml  AQXmlCommit
              commit previous operation

 aqxml06.xml  AQXmlSend
              Enqueue to JMS Text single consumer queue with piggyback commit

 aqxml07.xml  AQXmlReceive
              Dequeue from JMS Text single consumer queue with piggyback commit

 aqxml08.xml  AQXmlPublish
              Enqueue JMS MAP message with recipient into multi consumer queue

 aqxml09.xml  AQXmlReceive
              Dequeue JMS MAP message from multi consumer queue

 aqxml10.xml  AQXmlRollback
              rollback previous operation

 aqxmlhtp.sql HTTP Propagation

 AQHttp.java , AQHttpRq.java - Helpers to Post XML Request using HTTPClient

 AQDemoServlet.java - Servlet to Post AQ XML files (for Jserv) 
 AQPropServlet.java  - Servlet for AQ HTTP Propagation 

For additional demos using E-business examples unzip 
aqbzdemo.tar (aqbzdemo.zip for Windows).

Steps to run demos:
===================

1. Users Authentication setup for restricted access
    
   Create users file for aq agents:

    cd $ORACLE_HOME/rdbms/demo
    $ORACLE_HOME/Apache/Apache/bin/htpasswd -cb users_passwds  john welcome
    
    This file should already exist in the $ORACLE_HOME/rdbms/demo directory.

2. Apache configuration changes specific to Advanced Queueing 

   (a) Add Servlet mount point to jserv.conf

     ApJServGroupMount /aqserv/servlet balance://group1/root
     ApJservMount /aqserv/servlet /root

   (b) Add the following to httpd.conf to restrict access to 
       /aqserv/servlet Only the to AQ agents registered in <users>.
       Replace /apache/htdocs/userdb/users  below with the absolute 
       location of <users> file created in step(1) above.
       
          <Location /aqserv/servlet/>
          <Limit POST>
              AuthName "AQ restrictions for users"
              AuthType Basic
              AuthUserFile /apache/htdocs/userdb/users_passwds
              require valid-user
          </Limit>
          </Location>

    The above changes are already added to $ORACLE_HOME/rdbms/demo/aqxml.conf.
    aqxml.conf is included in $ORACLE_HOME/Apache/Apache/conf/oracle-apache.conf 

   (c) Add the following to jserv.properties for classpath 
       if they are not already there:
       # Advanced Queuing - XML 
       wrapper.bin.parameters=-Xmx256M 
       wrapper.classpath=$ORACLE_HOME/rdbms/jlib/aqapi.jar
       wrapper.classpath=$ORACLE_HOME/rdbms/jlib/jmscommon.jar
       wrapper.classpath=$ORACLE_HOME/rdbms/jlib/aqxml.jar
       wrapper.classpath=$ORACLE_HOME/rdbms/jlib/xsu12.jar
       wrapper.classpath=$ORACLE_HOME/rdbms/jlib/xdb.jar
       wrapper.classpath=$ORACLE_HOME/lib/xmlparserv2.jar
       wrapper.classpath=$ORACLE_HOME/lib/xschema.jar
       wrapper.classpath=$ORACLE_HOME/lib/servlet.jar
       wrapper.classpath=$ORACLE_HOME/lib/lclasses12.zip
       wrapper.classpath=$ORACLE_HOME/jlib/jndi.jar
       wrapper.classpath=$ORACLE_HOME/jlib/jta.jar
       wrapper.classpath=$ORACLE_HOME/jdbc/lib/classes12.zip
       wrapper.classpath=$ORACLE_HOME/jdbc/lib/nls_charset12.zip

       # Enable the flag below if you are using jdk 1.2.2_05a versions or above
       #wrapper.env=JAVA_COMPILER=NONE;
       
       ## The following are required for SSL (https)
       wrapper.classpath=$ORACLE_HOME/jlib/javax-ssl-1_2.jar 
       wrapper.classpath=$ORACLE_HOME/jlib/jssl-1_2.jar 

       replace $ORACLE_HOME appropriately.
       Also verify env variables ORACLE_SID, ORACLE_HOME, LD_LIBRARY_PATH 
       set in jserv.properties. For NT, make sure the PATH variable is set.

3. User Authorization 

   Run aqxmlusr.sql to setup Database users and grant proxy session

    SQL> @aqxmlusr.sql


4. Make sure classpath include the following:
      For JDK1.2.x: 
       $ORACLE_HOME/jdbc/lib/classes12.zip 
       $ORACLE_HOME/jdbc/lib/nls_charset12.zip
       $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/rdbms/jlib/xdb.jar 
       $ORACLE_HOME/jlib/jndi.jar 
       $ORACLE_HOME/jlib/jta.jar 
       $ORACLE_HOME/jlib/javax-ssl-1_2.jar 
       $ORACLE_HOME/jlib/jssl-1_2.jar 
       $ORACLE_HOME/lib/xmlparserv2.jar 
       $ORACLE_HOME/lib/xschema.jar 
       $ORACLE_HOME/lib/http_client.jar 
       $ORACLE_HOME/lib/servlet.jar 
       $ORACLE_HOME/lib/lclasses12.zip 

       NOTE :
       http_client.jar, jssl-1_2.jar, javax-ssl-1_2.jar 
       are required by HTTPClient used in AQHttp.java AQHttpRq.java.

3. Database Setup:
   Make sure init.ora file contains:
        compatible = 8.1.0 or higher
        aq_tm_processes = 1
        job_queue_processes = 2
   restart database and listener.

4. Modify data source properties in AQDemoservlet in doc root 
   directory location. Modify sid, host, port in AQDemoServlet.java 

5. Compile AQ Demo Servlets
    
   cd $ORACLE_HOME/Apache/Jserv/servlets
   javac AQDemoServlet.java AQPropServlet.java 

   Restart webserver.
 
6. Verify the setup:

    From the browser try,
    If you are using Jserv:
    http://<hostname>:<portnumber>/aqserv/servlet/AQDemoServlet 
    (or)
    If you are using Tomcat:
    http://<hostname>:<portnumber>/aqserv/servlet/AQDemoServlet22

    replace hostname, portnumber with webserver host/port 
    This should display
      Sample AQ Servlet 
      AQxmlServlet is working!

7. Run create queue script to create AQ queuetables and start queues 

   SQL> @aqxmldmo.sql 

8. compile AQHttpRq.java 

   cd $ORACLE_HOME/rdbms/demo
   javac AQHttpRq.java AQHttp.java 
   
10. POST a request:

    Usage: 
    java AQHttpRq <wserv> <wport> <POST> <PROTOCOL> <url> webuser pswd xmlfile xmlfile ..

   
    Example:

    (a) Enqueue to ADT single consumer queue with piggyback commit:
    java AQHttpRq <my-pc> 7777 POST http /aqserv/servlet/AQDemoServlet john welcome aqxml01.xml 

    (b) Dequeue from ADT Single consumer queue with piggyback commit:
    java AQHttpRq <my-pc> 7777 POST http /aqserv/servlet/AQDemoServlet john welcome aqxml02.xml 

    (c) Enqueue to ADT (with LOB) multi consumer queue and Commit 
    java AQHttpRq <my-pc> 7777 POST http /aqserv/servlet/AQDemoServlet john welcome aqxml03.xml  aqxml05.xml 

    (d) Dequeue from ADT multi consumer queue and Commit:
    java AQHttpRq <my-pc> 7777 POST http /aqserv/servlet/AQDemoServlet john welcome aqxml04.xml  aqxml05.xml 

    (e) Enqueue to JMS Text single consumer queue with piggyback commit:
    java AQHttpRq <my-pc> 7777 POST http /aqserv/servlet/AQDemoServlet john welcome aqxml06.xml 

    (f) Dequeue from JMS Text single consumer queue with piggyback commit
    java AQHttpRq <my-pc> 7777 POST http /aqserv/servlet/AQDemoServlet john welcome aqxml07.xml 

    (g) Enqueue JMS MAP message with recipient into multi consumer queue-Commit 
    java AQHttpRq <my-pc> 7777 POST http /aqserv/servlet/AQDemoServlet john welcome aqxml08.xml  aqxml05.xml

    (h) Dequeue JMS MAP message from multi consumer queue and Rollback
    java AQHttpRq <my-pc> 7777 POST http /aqserv/servlet/AQDemoServlet john welcome aqxml09.xml  aqxml10.xml

    (i) Dequeue JMS MAP message from multi consumer queue and Commit 
    to commit dequeue call 
    java AQHttpRq <my-pc> 7777 POST http /aqserv/servlet/AQDemoServlet john welcome aqxml09.xml  aqxml05.xml


11. Additional steps, if you are using Demos with Apache/Tomcat 3.x:

   (a) set the following in apache/conf/httpd.conf
        KeepAliveTimeout 300
        MaxKeepAliveRequests 200

   (b) add the following include directive to httpd.conf
        include $tomcat_homedir/conf/tomcat-apache.conf

   (c) Use AQDemoServlet22.java - Servlet to Post AQ xml files 
          (for servlet 2.2 implementation, eg., Tomcat, OSE) 

   (d) Rename AQPropServlet22.java to AQPropServlet.java in document 
       root directory


12. HTTP Propagation 

   (a) Make sure the AQPropServlet is working.
       From browser try:
       http://<hostname>:<portnumber>/aqserv/servlet/AQPropServlet
       replace hostname, portnumber with webserver host/port 

       This should display
          Sample AQ Servlet 
          AQxmlServlet is working!
   (b) run aqxmldmo.sql to create queues/users etc

   (c) Specify arguments protocol, hostname, portnumber for creating dblink.
       Run AQ http propagation demo.

       SQL>@aqxmlhtp http my-pc 7777
   

13. HTTPS Access/Propagation 

    Create users/queue tables.

   (a)  Specify https for protocol and SSL port for Wport 
 
    java AQHttpRq <my-pc> 443 POST https /aqserv/servlet/AQDemoServlet john welcome aqxml01.xml 
 
   (b) HTTPS propagation 
        -create a new wallet using Oracle Wallet Manager   
        - Import trusted cerificate from file 
           $ORACLE_HOME/Apache/Apache/conf/ssl.crt/demoCAcert.crt 
        - New trustpoint will be added 'FOR TESTING PURPOSES'
        - select AutoLogin button under Wallet menu option 
        - Save the wallet to a directory location (eg: $ORACLE_HOME/rdbms/demo)
        - Verify the two files created under the specified directory
          cwallet.sso, ewallet.p12
          Exit Wallet Manager.

        - add to network/admin/sqlnet.ora (replace $ORACLE_HOME)  
           eg:
           oss.source.my_wallet=
           (SOURCE=(METHOD=FILE)(METHOD_DATA=
              (DIRECTORY=$ORACLE_HOME/rdbms/demo)))

        - restart listener/database/Apache(ssl)

        - from sqlplus 

          SQL>@aqxmlhtp https my-pc 443 
        

14. Cleanup 

   (a) run aqxmldrp.sql to drop users/queues 
