
Setting Up and Running the AC4J Demo
------------------------------------

   It is assumed that OC4J and the Oracle database have been installed
   and that the environment variable $J2EE_HOME points to the OC4J J2EE home 
   directory (<OC4J_base_dir>/j2ee/home).

   The commands shown below for each step are in UNIX/Solaris format.
   On Windows, the same commands can be executed, using the corresponding
   Windows syntax. (Changing '/' to '\' being the only required change in
   most cases.)

Install Required Archives
-------------------------

0) Set the environment variable $AC4J_DEMO_DIR to the path to the top level
   directory of the AC4J demo (the directory that contains the files
   common.xml, README.txt and the directories src and dist.)
   The recommended directory for installing the AC4J demo is
   $J2EE_HOME/demo/ac4j.

setenv AC4J_DEMO_DIR <path to AC4J demo>

1) Unpack the AC4J SQL scripts from $J2EE_HOME/sql/ac4j-sql.jar, in
   a new sub-directory $AC4J_DEMO_DIR/sql:

cd $AC4J_DEMO_DIR
mkdir sql/databus
cd sql/databus
jar xvf $J2EE_HOME/sql/ac4j-sql.jar

Initialize the AC4J Databus
---------------------------

2) The AC4J database users, tables and other artifacts (that together
   comprise the AC4J 'Databus') can be initialized by executing the script 
   createall.sql that was unpacked in step 2.

   Note : Before running the script, check that the arguments to the two
          calls in createall.sql are correct for you database configuration.

          The meaning of the arguments are as follows :

   createjem.sql <sys user> <sys pwd> <DB instance> <table space>

            <sys user> = database system user. Script default = sys
            <sys pwd> = databse sys password. Script default = knl_test7
            <DB instance> = database instance. Usually = inst1
            <table space> = tablespace for AC4J tables. Usually = system

   createclient.sql <sys user> <sys pwd> <AC4J user> <AC4J pwd> <table space>

            <sys user> = database system user. Script default = sys
            <sys pwd> = databse sys password. Script default = knl_test7
            <AC4J user> = database AC4J user. Script default = JEMCLIUSER
            <AC4J pwd> = databse AC4J password. Script default = JEMCLIPASSWD
            <table space> = tablespace for AC4J tables. Usually = system

          In particular, the system user and password may be different
          for your installation.

          Change the arguments accordingly, and then:

cd $AC4J_DEMO_DIR/sql/databus
sqlplus /nolog @createall.sql

   Note : The first time the script is run, it is normal to see four error
   messages, reporting that one synonym and three database links cannot be
   dropped because they do not exist. No other error messages should be seen.

Initialize the Demo Database
----------------------------

3) The database tables required for the demo are created and populated by
   running the createTables.sql script.

cd $AC4J_DEMO_DIR/sql
sqlplus /nolog @createTables.sql

Edit Configuration Files
------------------------

4) The data sources used by the demo must be set up in the file
   $J2EE_HOME/config/data-sources.xml

   Before modifying it, it is recommended that a copy of the original file
   be saved, perhaps as follows:

cd $J2EE_HOME/config
cp data-sources.xml data-sources.xml.orig

   Then, the following two data sources should _replace_ the data source(s)
   currently specified:

--------------- replace from <data-sources> to </data-sources> ------------
<data-sources>

   <!-- NON-Emulated DataSources: used for JEM server -->
   <data-source
       class="com.evermind.sql.OrionCMTDataSource"
               name="nonEmulatedDS"
               location="jdbc/nonEmulatedDS"
               connection-driver="oracle.jdbc.driver.OracleDriver"
       username="jemuser"
       password="jempasswd"
       url="jdbc:oracle:thin:@<host>:<port>:<sid>"
       inactivity-timeout="30" >
   </data-source>

   <!-- Emulated DataSources: used for JEM client -->
   <data-source
        class="com.evermind.sql.DriverManagerDataSource"
        name="OracleDS"
        location="jdbc/OracleCoreDS"
        xa-location="jdbc/xa/OracleXADS"
        ejb-location="jdbc/OracleDS"
        connection-driver="oracle.jdbc.driver.OracleDriver"
        username="jemuser"
        password="jempasswd"
        url="jdbc:oracle:thin:@<host>:<port>:<sid>"
        inactivity-timeout="30" >
   </data-source>

</data-sources>
-------------- (end) replace from <data-sources> to </data-sources> ------------

  Note that <host>, <port> and <sid> must be replaced with the hostname, port
  number and database sid of the Oracle database instance that the AC4J databus 
  has been installed on. Make sure they are replaced for both data sources.


Build the Demo
--------------

5) All three services can be built by running the default ant rule in
   the demo top level directory.

cd $AC4J_DEMO_DIR
ant

Note that they may be cleaned in a similar manner:

cd $AC4J_DEMO_DIR
ant clean

Start OC4J and Deploy Services
------------------------------

6) Start an OC4J instance:

cd $J2EE_HOME
java -Doracle.aurora.jem.aq.close.interval=2 -jar oc4j.jar

7) Deploy the three services.

   See the OC4J documentation for information on the various ways to deploy
   an EJB.
   NOTE: applications MUST be deployed in the following order:
   1-inventoryService, 2-creditService, and finally, 3-purchaseOrderService
   And is shown here:

cd $AC4J_DEMO_DIR
java -jar $J2EE_HOME/admin.jar ormi://localhost admin welcome -deploy \
  -file src/ejb/inventoryService-ejb/lib/inventoryService.ear \
  -deploymentName inventoryService
java -jar $J2EE_HOME/admin.jar ormi://localhost admin welcome -deploy \
  -file src/ejb/creditService-ejb/lib/creditService.ear \
  -deploymentName creditService -parent inventoryService
java -jar $J2EE_HOME/admin.jar ormi://localhost admin welcome -deploy \
  -file src/ejb/purchaseOrderService-ejb/lib/purchaseOrderService.ear \
  -deploymentName purchaseOrderService -parent creditService


   Three messages from the application server should be seen, each saying 
   'JEM Server started' - one for each service that is deployed.

Run Client
----------

8) A purchase order request may be made by invoking the 'reqpo' ant rule
   in the top level demo directory:

cd $AC4J_DEMO_DIR
ant reqpo

    Note : The Credit and Inventory Services do not have clients. The
           user interacts directly only with the PurchaseOrder Service,
           which in turn interacts with the other two services.

    Output of the following form is expected from the application server:

----------- sample of expected app server output from ant reqpo ---------------
=======>PurchaseorderServiceBean.ejbCreate(): begin/end
=======>PurchaseOrderServiceBean.takeOrder(): begin
         : clientName = scott
         : creditCardNumber = 1111-3333-4444-8888
         : (productName, quantity) = pen, 3
         : (productName, quantity) = pencil, 1
=======>PurchaseOrderServiceBean.createPO(): begin
=======>PurchaseOrderBean.ejbCreate(): begin
=======>PurchaseOrderBean.createPONumber(): begin
         : poNum=1
=======>PurchaseOrderBean.createPONumber(): end
=======>PurchaseOrderBean.evaluateTotalCost(): begin
=======>PurchaseOrderBean.evaluateTotalCost(): end---Total Cost = 0.75
=======>PurchaseOrderBean.ejbCreate(): end---poNumber= 1
=======>PurchaseOrderBean.ejbPostCreate(): begin
=======>LineItemBean: ejbCreate:  lineItemName = pen  quantity = 3
=======>LineItemBean: ejbCreate:  lineItemName = pencil  quantity = 1
=======>PurchaseOrderBean.ejbPostCreate(): end---getLineItems().size= 2
       createPO()---poNumber= 1
=======>PurchaseOrderServiceBean.createPO(): end
         : poNumber= 1
=======>PurchaseOrderServiceBean.startProcessingPOrder(): begin
=======>PurchaseOrderServiceBean.startProcessingPOrder(): end
=======>PurchaseOrderServiceBean.takeOrder(): end
=======>PurchaseOrderServiceBean.processOrder(): begin---poNumber= 1
=======>PurchaseOrderServiceBean.callCreditService(): begin
=======>PurchaseOrderServiceBean.callCreditService(): end
=======>PurchaseOrderServiceBean.callInventoryService(): begin
=======>PurchaseOrderServiceBean.callInventoryService(): end
=======>PurchaseOrderServiceBean.registerAsyncRespHandler(): begin
=======>PurchaseOrderServiceBean.registerAsyncRespHandler(): end
=======>PurchaseOrderServiceBean.processOrder(): end---status= STATUS_INPROCESS
=======>CreditServiceBean: ejbCreate: begin/end
=======>CreditServiceBean: checkCRED: begin
         : clientName = SCOTT
         : creditCardNumber = 1111-3333-4444-8888
         : amount = 0.75
=======>InventoryServiceBean: ejbCreate: begin/end
=======>InventoryServiceBean: checkINV: begin
         : (product, quantity) = pen, 3
         : (product, quantity) = pencil, 1
         : CreditorRemote found
         : creditorName = SCOTT
         : availableCredit = 5000.0
=======>CreditServiceBean: checkCRED: end--returning  CREDIT APPROVED
         : BEFORE: availableUnits[0] = 700
         : AFTER: availableUnits[0] = 697
         : BEFORE: availableUnits[1] = 600
         : AFTER: availableUnits[1] = 599
         : Returning: 
         : invCheck[0]=true
         : invCheck[1]=true
=======>InventoryServiceBean: checkINV: end
=======>PurchaseOrderServiceBean.processOrderCallback(): begin.credInfo=CREDIT APPROVED
=======>PurchaseOrderServiceBean.callBackMethod(): poNumber= 1
         : invInfo[0] = true
         : invInfo[1] = true
=======>PurchaseOrderServiceBean.callBackMethod(): end---credInfo=CREDIT APPROVED  poNumber=1  currentStatus= STATUS_SHIPPED
=======>PurchaseOrderServiceBean.getStatus(): begin---poNumber= 1
=======>PurchaseOrderServiceBean.getStatus(): end---poNumber= 1  status=STATUS_SHIPPED
-------- (end) sample of expected app server output from ant reqpo ------------

          And output of the following form is expected from the client:

---------------  sample of expected client output from ant reqpo --------------
reqpo:
     [java] Getting AC4J Connection and Session...

     [java] sendRequest: begin
     [java]   customer name = IID = scott
     [java]   credit card number = 1111-3333-4444-8888
     [java]   item names = pen,pencil
     [java]   quantities = 3,1

     [java] takeOrder request made. Process Context is:
     [java]   Interaction Identifier (IID) = scott
     [java]   Activation  Identifier (AID) = AE3D71D56E835817E0340003BA137479

     [java] Execute the following to receive PO response and track status:
     [java]   ant -DAID=AE3D71D56E835817E0340003BA137479 resppo
------------- (end) sample of expected client output from ant reqpo ----------

9)  The response to a purchase order request may be collected using the
    ant rule resppo.

    The Activity ID (AID) of the request must be provided as a property
    (ant -DAID=<AID> resppo). As a convenience, reqpo outputs the required 
    ant command line for that request, as the last line of its output.
    This may be cut and paste to the command line, for quicker entry.

cd $AC4J_DEMO_DIR/src/purchaseOrderService/
ant -DAID=AE3D71D56E835817E0340003BA137479 resppo    // This is just an
                                                     // example, using above AID

    The program automatically terminates when a STATUS_SHIPPED status is
    received.

    The exact output will depend on how soon after the purchase order 
    request is made that ant resppo is executed. Output of the following form 
    is expected:

--------------- sample of expected output from ant resppo -------------------
resppo:
     [java] Getting AC4J Connection and Session...

     [java] receiveResponse: begin
     [java] receiveResponse: receiving async response
     [java] receiveResponse: response received
     [java] receiveResponse: Purchase Order number = 1
     [java] receiveResponse: polling for PO status...
     [java]   status = STATUS_SHIPPED

     [java] receiveResponse: Status = SHIPPED. Done.
------------ (end) sample of expected output from ant resppo ------------------

10) To re-run the client (and submit a different purchase order), simply
    re-run ant reqpo, as described in step 8.

