B
AQ Lite Sample Application

This document describes the use and development of the Oracle AQ Lite sample application. Topics include:

• Setting Up the AQ Lite Sample Application

• Installing the JFC Swing Package

• Using the AQ Lite Sample Application

Setting Up the AQ Lite Sample Application

To set up the AQ Lite sample application, perform the following procedures:

Install AQ Lite

See the Oracle8i Lite Installation Guide for instructions on installing AQ Lite. After you install AQ Lite, the sample application is available in the ORACLE_HOME\Mobile\SDK\\AQLite\AQLSAMP directory.

Set Up the Oracle8i Server

1. Ensure that Oracle8i AQ is installed and available on the server.

2. Run the SQL script AQLiteO8.sql on the Oracle8i server as user SYSTEM (default password, MANAGER), if you have not done so already. This script is located in the ORACLE_HOME/Mobile/SDK//AQLite/SQL directory.

3. Run java program setupDeplMsgQ.class (in aqsample.jar) located in the AQLiteSamp directory.

   java setupDeplMsg [o8UserID]  [o8Passwd]  [o8ConnStr]
   
   e.g., java setupDeplMsgQ AQUSER AQUSER my_machine.mydomain.com:1521:orcl
   

Argument	Description	Example
o8UserId	Oracle8i user ID	"system"
o8Passwd	Oracle8i user password	"manager"
o8ConnStr	Oracle8i connection string	"my_machine.mydomain.com:1521:orcl"

Set Up the Oracle Lite Site

1. Create a valid Oracle Lite database.

2. Run java program setupServer.class (in aqlsample.jar) located in the AQLiteSamp directory:

   java setupServer [o8UserId] [o8Passwd] [o8ConnStr]
   
   e.g., java setupServer AQUSER AQUSER my_machine.my domain.com:1521:orcl
   

Argument	Description	Example
o8UserId	Oracle8i user ID	"system"
o8Passwd	Oracle8i user password	"manager"
o8ConnStr	Oracle8i connection string	"my_machine.mydomain.com:1521:orcl "

3. Run java program setupClient.class (in aqlsample.jar) located in the AQLiteSamp directory.

   java SetupClient [o8UserId]  [o8Passwd]  [o8ConnStr]  [option]  [oliteSiteName]
   
   e.g., java setup client AQUSER AQUSER my_machine.mydomain.com:1521:orcl ORD 
   C:\ORANT\OLDB40\politeProc.odb oliteSite 1
   or
   java setupClient AQUSER AQUSER my_machine.mydomain.com:1521:orcl PROC 
   C:\ORANT\OLDB40\politeProc.odb oliteSite 2
   

Argument	Description	Example
o8UserId	Oracle8i user ID	"system"
o8Passwd	Oracle8i user password	"manager"
option	"ORD" to set up local database for order entry "PROC" to set up local database for order processing	"ORD" " PROC"
o8ConnStr	path of the Oracle Lite database file	"C:\ORANT\OLDB40\politeOrd.odb" for Order Entry "C:\ORANT\OLDB\politePROC.odb" for Order Processing
oliteSiteName	Oracle Lite database ID.	"oliteSite 1" for Order Entry; "oliteSite 2" for Order Processing

Installing the JFC Swing Package

If you do not have Java Foundation Class (JFC) Swing package installed, inclde the jar file swing.jar (located in the AQLiteSamp directory) to your CLASSPATH.

Using the AQ Lite Sample Application

The AQ Lite Sample Application consists of the following modules:

• New Order

• View Order

• Process Order

The New Order and View Order modules represent two components of an order entry application residing on an AQ Lite client. Using the New Order module, you can create sales orders and send them to the data center (Oracle8i server) and for retrieval from the Process Order module. Using the View Order module you can view information in processed orders.

The Process Order module represents an order processing application residing on another AQLite client. This module retrieves new orders from the data center (Oracle8i server) and processes them.

Starting the Sample Application

To start the sample application, run AQLiteSample.class by typing java AQLiteSample. The main screen displays .

Using the New Order Module

To open the New Order module:

1. Click the New Order button on the main screen of the Sample Application. The dialog box to connect to the Oracle Lite database displays.

2. Type your user ID, Password, and Oracle Lite database path, and click the OK button. The Enter and Send New Order screen displays:

To create a new order:

1. Type a customer name in the Customer field.

2. Select a product from the drop-down list in the Item field.

3. Type the number of items in the Quantity field.

4. Select a payment type from the drop-down list in the Payment field.

5. Select a shipping method from the drop-down list in the Shipping field.

6. Click the Enter Order button to complete the order. The new order is created and enqueued to the AQ Lite client queue.

7. A message will appear stating that all orders have been entered into the local database successfully. Click OK.

8. Click Send Order in the Enter and Send Order screen. The dialog box to connect to the Oracle8i server displays.

9. In the connection dialog box for the Oracle8i server, Type your user ID, password, and connection string in the corresponding fields and then click OK.

10. After you create your new orders, you can send them to the Process Order module for processing. To send new orders to the Process Order module, click the Send Order button. AQ Lite propagates all new orders in the client queue to the master queue. Once in the master queue, the orders can be dequeued by the Process Order module.

11. A message will appear stating that all orders have been sent to the server for processing. Click OK.

12. Now, the sales department (Oracle Lite Database 1) has sent all new orders to the data center (Oracle8i server) for processing. Exit.

Using the Process Order Module

To open the Process Order module:

1. Click the Process Order button on the main screen of the Sample Application. The connection dialog box for the Oracle Lite database displays.

2. Type your user ID, password, and connection string in the corresponding fields and click OK. The Connection dialog box for the Oracle8i server displays.

3. In the connection dialog box for the Oracle8i server, Type your user ID, password, and connection string in the corresponding fields and then click OK. The Process Order screen displays.

When the Process Order module starts, it dequeues any new order messages, and displays the information in the Process Order screen.

To process an order:

1. Select the order you wish to process and click the Update Order Status button. The Process Order dialog box displays:

2. Select the order status from the drop-down list in the Processing field and click the Done button.

3. Repeat steps 1 and 2 for each order you wish to process.

4. Click the Finish button in the Process Order window. The processed order is propagated to the master queue (Oracle Lite Database 2).

5. Now the processing center has processed and sent orders back to the data center (Oracle8i server). Exit.

Using the View Order Module

To open the View Order module:

1. Click the View Order button on the main screen. The connection dialog box for the Oracle Lite database displays.

2. Type your user ID, password, and connection string in the corresponding fields and click OK.

3. The connection dialog box for the Oracle8i server displays. Type your user ID, password, and connection string in the corresponding fields and then click OK. The View Order screen displays.

When the View Order module is launched, AQ Lite propagates the processed order messages from the master queue (the Oracle8i server at the data center) to the client queue (Oracle Lite Database 1 at the sales/order-entry department). The View Order module dequeues the processed order messages and displays the information.

Removing an order:

Click on the order you wish to remove and then click the Remove Entry button. The order will be dequeued from the local database.

Sample Application Code

This section contains source code used to implement the AQ Lite sample application. Developers may use this code as an example in developing their own queueing applications in Oracle AQ Lite. The complete sample application source code is located in ORACLE_HOME/Mobile/SDK//AQLite/AQLSAMP directory.

Implementing the Sample Application User Interface - AQLiteSample.java

/*
  DESCRIPTION
    Main class - draws AQLite Sample App's main window
 
  NOTES
    Other files in the sample app:

    AQLiteSampQUtil.java     - all AQLite queue operations
    AQLiteSampUtil.java      - miscellaneous GUI and other operations
    AQLiteSampNewOrder.java  - handles "New Order" operations
    AQLiteSampProcOrder.java - handles "Process Order" operations
    AQLiteSampViewOrder.java - handles "View Order" operations

  
  */

import javax.swing.*;
import java.awt.*;
import java.awt.event.*;

public class AQLiteSample implements ActionListener{

  static JFrame frame = null;
 
  // Create Components
  public Component createComponents() {


    // GUI initialization
    final JLabel label = new JLabel("AQLite Sample Application");
    
    // create buttons
    JButton button1 = new JButton("New Order");
    JButton button2 = new JButton("View Order");
    JButton button3 = new JButton("Process Order");
    JButton button4 = new JButton("Exit");


    label.setFont(AQLiteSampUtil.fontb);
    button1.setFont(AQLiteSampUtil.fonts);
    button2.setFont(AQLiteSampUtil.fonts);
    button3.setFont(AQLiteSampUtil.fonts);
    button4.setFont(AQLiteSampUtil.fonts);

    // set mnemonic keys for users to stimulate button click. 
    button1.setMnemonic(KeyEvent.VK_N); //(Alt-n)
    button2.setMnemonic(KeyEvent.VK_V); //(Alt-v)
    button3.setMnemonic(KeyEvent.VK_P); //(Alt-p)
    button4.setMnemonic(KeyEvent.VK_E); //(Alt-e)

    // set unique identifier to button
    button1.setActionCommand(AQLiteSampUtil.bn_main_NO);
    button2.setActionCommand(AQLiteSampUtil.bn_main_VO);
    button3.setActionCommand(AQLiteSampUtil.bn_main_PO);
    button4.setActionCommand(AQLiteSampUtil.bn_main_EX);

    button1.addActionListener(this);
    button2.addActionListener(this);
    button3.addActionListener(this);
    button4.addActionListener(this);
    // set button colours
    //button1.setOpaque(true);
    //button1.setBackground(Color.blue);


    // put the contents in a JPanel that has an "empty" border
    // to put space between a top-level container and its contents
    JPanel pane = new JPanel();
    pane.setOpaque(true);
    pane.setBackground(Color.white);
    pane.setBorder(BorderFactory.createEmptyBorder(30, //top 30 pixels
                                                   30, //left 30 pixels
                                                   30, //bottom
                                                   30) //right
                   );

    // set layout manager
    pane.setLayout(new GridBagLayout());

    GridBagConstraints c = new GridBagConstraints();
    c.gridx = 0;
    c.gridy = 0;
    c.gridwidth = 3;
    c.gridheight = 1;
    c.insets = new Insets(3,2,5,2);
    c.weightx = 1.0;
    c.weighty = 1.0;

    // add label to panel
    pane.add(label, c);

    c.gridy = GridBagConstraints.RELATIVE;
    c.fill = GridBagConstraints.HORIZONTAL;
c.gridx = 2;
    c.anchor = GridBagConstraints.CENTER;
    c.gridwidth = 1;
    c.weightx = 0.0;
    c.weighty = 1.0;
    c.insets = new Insets(3,2,3,2);
    // add buttons to panel
    pane.add(button1, c);
    pane.add(button2, c);
    pane.add(button3, c);
    pane.add(button4, c);

    return pane;
  }


  public void actionPerformed (ActionEvent evt) {
    String cmd = evt.getActionCommand();
    // "New Order" button click
    if (cmd.equals(AQLiteSampUtil.bn_main_NO)) {
      AQLiteSampNewOrder newOrder = new AQLiteSampNewOrder();
      newOrder.start();
    }
    // "View Order" button click
    else if (cmd.equals(AQLiteSampUtil.bn_main_VO)) {
      AQLiteSampViewOrder viewOrder = new AQLiteSampViewOrder();
      viewOrder.start();
    }
    // "Process Order" button click
    else if (cmd.equals(AQLiteSampUtil.bn_main_PO)) {
      AQLiteSampProcOrder procOrder = new AQLiteSampProcOrder();
      procOrder.start();
    }
    // "Exit" button click
    else if (cmd.equals(AQLiteSampUtil.bn_main_EX)) {
      String dialog_txt = "Do you really want to quit?";
      String dialog_title = "AQlite Sample Application - Quit";
      int response = JOptionPane.showConfirmDialog(frame,
                                                   dialog_txt,
                                                   dialog_title,
                                                   JOptionPane.YES_NO_OPTION);
      switch (response) {
      case JOptionPane.YES_OPTION:
        System.exit(0);
        break;
      case JOptionPane.NO_OPTION:
        break;
      case JOptionPane.CLOSED_OPTION:
        break;
      }
    }

  }


  /////////////////////////////////////////////////
  public static void main(String[] args) {
    try {
      // Set Look and Feel
      
UIManager.setLookAndFeel(UIManager.getCrossPlatformLookAndFeelClassName());
    } 
    catch (Exception e) { }

    frame = new JFrame("AQLite Sample Application");

    AQLiteSample app = new AQLiteSample();

    // create the components to go into the frame
    // and stick them in a container named contents
    Component contents = app.createComponents();
    frame.getContentPane().add(contents, BorderLayout.CENTER);

    // Window close
    frame.addWindowListener(new WindowAdapter() {
      public void windowClosing(WindowEvent e) {System.exit(0);} 
    });
    // Size
    frame.pack();
    //Finish setting up the frame, and show it.
    frame.setVisible(true);
  }
}

Preparing the Message Queues for Deployment - setupDeplMsgQ.java

The following code is used to prepare the message queues for deployment of the sample application.

import oracle.AQ.*;
import oracle.lite.AQ.*;
import java.util.*;
import java.sql.*;
import java.math.*;

public class setupDeplMsgQ {

  public static final String AQLDeplMsgQT = "AQLITE$_DeplMsgQT";
  public static final String AQLDeplMessages = "AQLITE$_DeplMessages";
  
  public static void main(String[] args) {
    
    if (args.length !=3 || args[0] == null || args[1] == null ||
        args[2] == null) {
      System.err.println("Usage: java setupDeplMsgQ [o8UserId] [o8Passwd] 
[o8ConnStr]");
      System.err.println("\n\n Example:");
      System.err.println("java setupDeplMsgQ AQUSER AQUSER my_machine.my_
domain.com:1521:orcl");
      System.exit(0);
    }
    String orauser = args[0];
    String orapswd = args[1];
    String connstr = "jdbc:oracle:thin:@" + args[2];
    AQSession aqConn = null;

    try {
      // JDBC Thin Driver
        
      DriverManager.registerDriver (new oracle.jdbc.driver.OracleDriver());
      Connection conn = 
        DriverManager.getConnection(connstr,orauser, orapswd);
      conn.setAutoCommit(false);
      AQOracleDriver aqD =   new AQOracleDriver();

      // get connection to Olite database
      aqConn = aqD.createAQSession((Object) conn);

      //prepare a queuetable property
      AQQueueTableProperty AQqtp = new AQQueueTableProperty("RAW");
      AQqtp.setStorageClause("");
      //AQqtp.setAutoCommit(false);
      AQqtp.setComment("AQLITE Queue for deployment messages");
      AQqtp.setCompatible("");
      AQqtp.setMessageGrouping(AQqtp.NONE);
      AQqtp.setMultiConsumer(true);
      AQqtp.setPrimaryInstance(1);
      AQqtp.setSecondaryInstance(0);
      AQqtp.setSortOrder("ENQ_TIME");

      //createQT
      AQQueueTable tqt = null;
      try {
        tqt = aqConn.getQueueTable(orauser, AQLDeplMsgQT);
      }
      catch (AQException e)
      {
        //System.out.println(e);
      }
      try {
        if (tqt != null)
          tqt.drop(true);
      }
      catch (AQException e)
      {
        System.err.println("Ooops: " + e.getMessage());
        e.printStackTrace();
      }
      tqt = aqConn.createQueueTable(orauser, AQLDeplMsgQT, AQqtp);


      //prepare a queue property
      AQQueueProperty AQqp = new AQQueueProperty();
      //AQqp.setAutoCommit(false);
      AQqp.setComment("test Queue");
      //AQqp.setDepTracking(false);
      //AQqp.setMaxRetries(100);
      AQqp.setQueueType(AQqp.NORMAL_QUEUE);
      AQqp.setRetentionTime(0.0) ;
      //AQqp.setRetryInterval(0.0);

      // create Q on the QT
      AQQueue q = aqConn.createQueue(tqt, AQLDeplMessages, AQqp);
      q.start();


      // commit changes
      conn.commit();
    }
    catch (AQException e)
    {
      System.err.println("Ooops: " + e.getMessage());
      e.printStackTrace();
    }
    catch (SQLException e)
    {
      System.err.println("Ooops: " + e.getMessage());
      e.printStackTrace();
    }
  }
}

Preparing the Oracle8i Server for Deployment - setupSever.java

The following code is used to prepare the Oracle Lite server device for deployment of the sample application.

import java.util.*;
import java.sql.*;
//import java.math.*;
import oracle.AQ.*;
import oracle.lite.AQ.*;

public class setupServer{

  public static void main(String[] args) {

    if (args.length !=3 || args[0] == null || args[1] == null ||
        args[2] == null) {
      System.err.println("Usage: java setupServer [o8UserId] [o8Passwd] 
[o8ConnStr]");
      System.err.println("\n\n Example:");
      System.err.println("java setupServer AQUSER AQUSER my_machine.my_
domain.com:1521:orcl");
      System.exit(0);
    }


    String o8UserID = args[0];
    String o8Passwd = args[1];
    String o8ConnStr = "jdbc:oracle:thin:@" + args[2];

    AQSession aqConn;

    try {
      // connect to O8 via JDBC
      DriverManager.registerDriver (new oracle.jdbc.driver.OracleDriver());
      Connection conn = 
DriverManager.getConnection(o8ConnStr,o8UserID,o8Passwd);
      conn.setAutoCommit(false);

    
      // do not change the following if you are not sure
      String[] qn = new String[1];
      qn[0] = "AQLite_SampOrderQ";
      String[] qo = new String[1];
      qo[0] = o8UserID;
      String qt = "AQLite_SampOrderQT";
        
      //create Queue Table and Queue
      AQOracleDriver aqD =   new AQOracleDriver();
      aqConn = aqD.createAQSession((Object) conn);

      //prepare a queuetable property
      AQQueueTableProperty AQqtp = new AQQueueTableProperty("RAW");
      AQqtp.setStorageClause("");
      //AQqtp.setAutoCommit(false);
      AQqtp.setComment("AQLite Sample Application");
      AQqtp.setCompatible("");
      AQqtp.setMessageGrouping(AQqtp.NONE);
      AQqtp.setMultiConsumer(true);
      AQqtp.setPrimaryInstance(1);
      AQqtp.setSecondaryInstance(0);
      AQqtp.setSortOrder("ENQ_TIME");

      //createQT
      AQQueueTable tqt = null;
      try {
        tqt = aqConn.getQueueTable(qo[0], qt);
      }
      catch (AQException e) {
        System.err.println("Oooops. " + e.getMessage());
        e.printStackTrace();
      }
      try {
        if (tqt != null)
        {
          //cleaning
          AQLiteDeploymentAdmin admin = new AQLiteDeploymentAdmin(conn);
          AQLiteDeploymentOliteSite os =admin.getOliteSite("OliteSite1",
                                                           "sampUser");
          //os.deInstantiate("AQLSampQG1");
          try
          {//test here
            AQLiteDeploymentQueueGroup qg = os.getQueueGroup("AQLSampQG1");
            qg.drop();
          }
          catch (AQException e){}
          tqt.drop(true);
        }
      }
      catch (AQException e) {
        System.err.println("Oooops. " + e.getMessage());
        e.printStackTrace();
      }
      tqt = aqConn.createQueueTable(qo[0], qt, AQqtp);


      //prepare a queue property
      AQQueueProperty AQqp = new AQQueueProperty();
      //AQqp.setAutoCommit(false);
      AQqp.setComment("AQLite Sample Application");
      //AQqp.setDepTracking(false);
      AQqp.setQueueType(AQqp.NORMAL_QUEUE);
      AQqp.setRetentionTime(0.0) ;

      // create Q on the QT
      AQQueue q = aqConn.createQueue(tqt, qn[0], AQqp);
      q.start();
        
         
      //deployment
      AQLiteDeploymentAdmin admin = new AQLiteDeploymentAdmin(conn);
        
      AQLiteDeploymentQueueGroup qg = admin.createQueueGroup("AQLSampQG1",
                                                             "order queue",
                                                             qo,
                                                             qn);
                                         
      AQLiteDeploymentOliteSite os = admin.createOliteSite("OliteSite1",
                                                          "sampUser",
                                                          null,
                                                          null,
                                                          true,
                                                          "AQLite Sample 
Application");
                                                          
      os.defineQueueGroup(qg);
      os.instantiate();
      /*
        AQLiteDeploymentAdmin admin = new AQLiteDeploymentAdmin(conn);
        
        AQLiteDeploymentOliteSite os = admin.getOliteSite("OliteSite2",
        "sampProc");
        //os.deInstantiate();
        os.instantiate();
      */
      os =admin.createOliteSite("OliteSite2",
                                "sampProc",
                                null,
                                null,
                                true,
                                "AQLite Sample Application");
                                                          
      os.defineQueueGroup(qg);
      os.instantiate(); 

      // commit changes
      conn.commit();
    }//try
    catch (AQException e) {
      System.out.println("Oooops. " + e.getMessage());
      e.printStackTrace();
    }
    catch (java.sql.SQLException e) {
      System.out.println("Oooops. " + e.getMessage());
      e.printStackTrace();
    }
  }
}

Preparing the Oracle Lite Client Device for Deployment - SetupClient.java

The following code is used to prepare the Oracle Lite client device for deployment of the sample application.

import oracle.AQ.*;
import oracle.lite.jac.*;
import oracle.lite.AQ.*;

public class setupClient{
  public static void main(String[] args) {
    
    if (args.length !=6 || args[0] == null || args[1] == null || 
        args[2] == null || args[3] == null || args[4] == null ||
        args[5] == null) {
      show_usage();

    }
    String o8UserID = args[0];
    String o8Passwd = args[1];
    String o8ConnStr = args[2];
    boolean newDB = true;

    String o8lConnStr = args[4];
    String deqConsumer = null;
    if (args[3].toUpperCase().equals ("ORD"))
      deqConsumer = "sampUser";
    else if (args[3].toUpperCase().equals ("PROC"))
      deqConsumer = "sampProc";
    else {
      System.err.println("ERROR: option must be either 'ORD' or 'PROC'!!\n\n");
      show_usage();
    }
    String olitesite = args[5];

          
    AQSession aqConn;

    try {
      // connect to Olite via Jac
      POLConnection pConn = POLConnection.getConnection(o8lConnStr, 
POLConnection.CONNECT_READ_WRITE);
      AQDriver aqD =  (AQDriver) new AQLiteDriver();

      // get connection to Olite database
      aqConn = aqD.createAQSession((Object) pConn);
        
      //make an O8 connection Object
      AQLitePropOraConn o8_conn = 
        new AQLitePropOraConn("O8AQ", 
                              o8UserID, 
                              o8Passwd, 
                              o8ConnStr);
                            
      AQLitePropagator propagator = new AQLitePropagator();
        
      //make a deployment object
      AQLiteDeploymentClient dc = new AQLiteDeploymentClient((AQSession) aqConn,
                                                             deqConsumer,
                                                             o8_conn,
                                                             propagator,
                                                             olitesite
                                                             ) ;
                                     
      //do a deploymnet
      dc.execDeployment(newDB, false);
                
        
      // commit changes
      pConn.commit();
    }
        
    catch (AQException e) {
        System.err.println("Oooops. " + e.getMessage());
        e.printStackTrace();
    }
    catch (POLException e) {
        System.err.println("Oooops. " + e.getMessage());
        e.printStackTrace();
    }
  }


  static void show_usage() {
    System.err.println("Usage: java setupClient [o8UserId] [o8Passwd] 
[o8ConnStr] [option] [oliteConnStr] [oliteSiteName]");
    System.err.println("");
    System.err.println("option - 'ORD' for Order entry db, 'PROC' for Process 
order db");
    System.err.println("\n\n Example:");
    System.err.println("java setupClient AQUSER AQUSER my_machine.my_
domain.com:1521:orcl ORD C:\\ORANT\\OLDB40\\PoliteOrd.odb OliteSite1\n");
    System.err.println("java setupClient AQUSER AQUSER my_machine.my_
domain.com:1521:orcl PROC C:\\ORANT\\OLDB40\\PoliteProc.odb OliteSite2");
    System.err.println("");
    System.exit(0);
  }

}