11 Using XDK and SOAP

Provider Interface

The provider interface allows the SOAP server to uniformly invoke service methods regardless of the type of provider (Java class, stored procedure, or some other provider type). There is one provider interface implementation for each type of service provider, and it encapsulates all provider-specific information. The provider interface makes SOAP implementation easily extensible to support new types of service providers.

Provider Deployment Administration

Oracle SOAP provides the provider deployment administration client to manage provider deployment information.

SOAP Services Provided

SOAP application developers provide SOAP services. These services are made available using the supplied default Java class provider or custom providers. Oracle SOAP includes a service deployment administration client that runs as a service to manage SOAP services. SOAP services, including Java services, represent user-written applications that are provided to remote SOAP clients.

Setting Up the Tables and the SOAP Service

To store inventory data, log messages, and perform message queuing, run the createdb.sql script from the downloaded source files to set up database schemas for headquarters and a branch. This script calls a set of SQL scripts that creates a headquarters user and a branch user with proper privileges. It also creates tables and triggers for storing inventory information and messages and inserts sample data in both schemas.

In the headquarters user schema, create a table named message_out_type. This stores the inventory information update broadcast messages from headquarters to the branches. There are three columns in the table: ID, MESSAGE, and CREATE_TIME. The MESSAGE column datatype is XMLType.

Next, run the PL/SQL procedure, CREATE_QUEUE, that sets up message queues at both headquarters and the branches. This procedure uses functions in the DBMS_AQADM package to create the queue table, create the queue, and start the queue. Once the queue is started, enqueuing and dequeuing operations on the message queue are enabled.

The following PL/SQL procedure uses the SYS.AQ$_JMS_BYTES_MESSAGE message type to manage the compressed SOAP messages. This creates a queue called broadcastb_queue at the headquarters location:

begin  
    create_queue('broadcastb_queue_tbl',
    'broadcastb_queue',
    'SYS.AQ$_JMS_BYTES_MESSAGE');
end;

The inventoryBranchServer Java class is the branch's service for inserting a new item into the branch inventory. When this service program receives a SOAP request, it decompresses the request content and saves it in the inventory_item table, using Oracle XML SQL Utility (XSU) to insert the item into the database. Oracle XSU creates canonical mappings between the XML document and database schema to perform SQL data operations. See the file

client/src/oracle/xml/pm/demo/branch/service/inventoryServer.java

in the downloaded software.

Requesting SOAP Service

The application makes requests to the headquarters SOAP service using a servlet called insertItemServlet, a Java class that extends HttpServlet. This servlet inserts a new item in the headquarters inventory.

The servlet request uses XSQL pages and the user's input in the application's Web interface (click "New Items") to generate an XML document. Oracle XSU then directly inserts the XML content into the database. The insertItemServlet performs several actions. For example, to broadcast an update message to the branches, it:

• Initializes the Message Dispatcher process.

• Compresses the XML document by calling the CompressionAgent class.

• Creates a SOAP message and stores it in the message logging table.

• Pushes the compressed XML document onto the message queue (enqueue).

Initializing the MessageDispatcher Process

When it is first called, insertItemServlet initializes the MessageDispatcher object. This object is stored in the ServletContext when the process is successfully initialized. This code initializes the MessageDispatcher object:

ServletContext context = getServletContext();
MessageDispatcher msgDispatcher =
    (MessageDispatcher)context.getAttribute("Dispatcher");

if (msgDispatcher == null) {
   System.out.println("Initialize Receiver.");
   msgDispatcher = new MesageDispatcher();
   context.setAttribute("Dispatcher",msgDispatcher);
   }

The MessageDispatcher Java class creates a MessageBroker, which in turn, creates a MessageClient to monitor each message queue and dispatch messages to the registered branches.

Compressing the XML Document

The following code from insertItemServlet creates the Compression Agent:

CompressionAgent cagent = new
   CompressionAgent("oracle:compression");
byte [] input = cagent.compression(m_content);

Creating a SOAP Message

The message is stored in a column defined as XMLType. The code from insertItemServlet that creates the SOAP message and stores it in the MESSAGE_OUT_XMLTYPE table is:

OraclePreparedStatement pstmt =
    (OraclePreparedStatement) conn.prepareStatement (
          "Insert into message_out_xmltype(message) values(?)");

m_content=createSOAPMessage(m_content);
oracle.xdb.XMLType xt = oracle.xdb.XMLType.createXML(conn,m_content);

pstmt.setObject(1, xt);
pstmt.execute();

Using XMLType lets us use XPATH with the sys.XMLType.extract() member function to query the portions of the message documents:

select e.message.extract('//item_info')
   .getStringVal() as result
from message_out_xmltype;

Enqueuing the XML Document

The following code from insertItemServlet creates the MessageBroker and enqueues the message:

MessageBroker mesgBroker =
   new MessageBroker("host_name",
   "Oracle_SID", "port_num",
   "thin", "cm", "cm", "broadcastb_queue");
mesgBroker.enqueueMessage(input);

When insertItemServlet finishes, the message is pushed onto the message queue and the Oracle AQ and MessageDispatcher processes update the branch inventory information. This ensures that the headquarters inventory system is not blocked during the branch system updates.

Listing of the Java Source File inserItemServlet.java

This file is found at ./server/src/insertItemServlet.java:

/**
 * FileName: insertItemServlet.java
 * Description: 
 *   Insert new Inventory Item into HQ database and broadcase the message to 
 *   the branches.
 */
import java.io.*;
import java.util.*;
import java.sql.*;
import javax.servlet.*;
import javax.servlet.http.*;

// XSU
import org.w3c.dom.*;
import oracle.xml.parser.v2.*;
import oracle.xml.sql.dml.OracleXMLSave;

// XMLType
import oracle.xdb.XMLType.*;
import oracle.jdbc.driver.*;
import oracle.sql.*;

// SOAP Message
import oracle.AQ.*;
import oracle.xml.pm.queue.*;
import oracle.xml.pm.compression.CompressionAgent;

// Configuration
import oracle.xml.pm.util.ConfigManager;

/**
 * This class implements Message Borker
 */
public class insertItemServlet extends HttpServlet
{
  String m_content=null;
  String m_dblink = null;
  String m_usr = null;
  String m_passwd = null;
  String m_hostname = null;
  String m_sid = null;
  String m_port = null;
  
  /**
   * Initialize global variables
   * @param config - ServletConfig 
   * @exeception - ServletException thrown if super.init fails
   */
  public void init(ServletConfig config) throws ServletException 
  {
    super.init(config);

    // Initialize the JDBC Connection from Configuration Files
    try
    {
      ConfigManager xml_config = new ConfigManager("DEMOConfig.xml","cm");  
      m_dblink = xml_config.dblink;
      m_usr= xml_config.usr;
      m_passwd = xml_config.passwd;
      m_hostname = xml_config.hostname;
      m_sid = xml_config.db_sid;
      m_port = xml_config.db_port;
    }
    catch(Exception ex)
    {
      // ex.printStackTrace();
      throw new ServletException(ex.getMessage());
    }
  }

  /**
   * HTTP Get 
   * @param req - HttpServletRequest
   * @param res - HttpServletResponse 
   * @exeception - IOException, ServletException
   */
   public void doGet(HttpServletRequest req, HttpServletResponse res)
       throws IOException, ServletException
  {
     doPost(req,res);
  }

  /**
   * HTTP POST 
   * @param req - HttpServletRequest
   * @param res - HttpServletResponse 
   * @exeception - IOException, ServletException
   */
  public void doPost(HttpServletRequest req, HttpServletResponse res)
  throws IOException, ServletException
  {
    ServletContext context = getServletContext();

    // Initialize MessageDispatcher for broadcast messages
    MessageDispatcher msgDispatcher =
      (MessageDispatcher) context.getAttribute("MessageDispatcher");
 
    if(msgDispatcher == null)
    {
        msgDispatcher = new MessageDispatcher("broadcastb_queue",m_hostname,
        m_sid, m_port, m_usr,m_passwd,m_dblink);
        context.setAttribute("MessageDispatcher",msgDispatcher);
     }

    // Initialize MessageBroker for broadcasting messages
    MessageBroker msgBroker = (MessageBroker) 
                                  context.getAttribute("MessageBroker");
    if(msgBroker == null)
    {
      try
      {
        msgBroker = new MessageBroker(m_hostname, m_sid, m_port, "thin",m_usr,
                                      m_passwd,"broadcastb_queue",m_dblink);
        context.setAttribute("MessageBroker",msgBroker);
      }
      catch(Exception ex)
      {
        System.out.println("Error:"+ex.getMessage());
      }
    }
    
    PrintWriter out = res.getWriter();
    m_content = req.getParameter("content");

    // Save new Item information into database
    try 
    {
      Connection conn = getConnection();
      
      OracleXMLSave sav = new OracleXMLSave(conn,"inventory_item_view");
      sav.insertXML(m_content);
      sav.close();
      conn.close();
        
      out.println("Insert Successful\n");
    }
    catch(Exception e)
    {
      out.println("Exception caught "+e.getMessage());
      return;
    }

    // Create and Enqueue the Message
    byte[] input = createMessage(m_content);
    msgBroker.enqueueBytesMessage(input); 

    return;
  }

  // Subject to change to validate and using XML Update language
  // Since this message is not public we keep it with simplified SOAP format
  public byte[] createMessage(String content)
  {
     String message = null;

     message="<Envelope>"+
            "<Header>"+
            "<branch_sql>"+"select id,soapurl from branch"+"</branch_sql>"+
            "<objURI>"+"inventoryServer"+"</objURI>"+
            "<method>"+"addItem"+"</method>"+
            "</Header>"+
            "<Body>"+content+"</Body>"+    
            "</Envelope>";
     
    // Compress the Message Content
    CompressionAgent cagent = new CompressionAgent("oracle:xml:compression");
    byte [] input = cagent.compress(message);

    return input;
  }

  /**
   * Get JDBC Connection
   * @return Connection - JDBC Connection 
   * @exception SQLException - thrown if the connection can't be gotten.
   */
  public Connection getConnection() throws SQLException
  {
    DriverManager.registerDriver(new oracle.jdbc.driver.OracleDriver());
    Connection conn =DriverManager.getConnection (m_dblink,m_usr,m_passwd);
    return conn;
  }
}

Queuing Messages with AQ

The MessageBroker class is the agent that communicates with the message queue and invokes SOAP Remote Procedure Call (RPC).

The MessageBroker provides the following functionality:

XML Compression

To make the messaging system more efficient, use XML compression. This lets you compress or decompress a message by using Java object serialization, such as:

XMLDocument.writeExternal(...);
XMLDocument.readExternal(...);

Our sample application uses the CompressionAgent Java class to provide the compress and decompress functionality. CompressionAgent includes both compress and decompress methods. The compress method returns a byte array and the decompress method returns an XML document.

Listing of the Java Source File MessageBroker.java

This lengthy source file is found at ./xmlagents/src/oracle/xml/pm/queue

Some of the more important functions are sendSOAPMessage(), which sends SOAP files and dequeueTextMessage(), which dequeues information for each inventory item.

Summary of the SOAP Example

Using AQ and XDK in a SOAP messaging system can greatly improve reliability and performance. Inventory update messages are delivered quickly. If they cannot be delivered, they are stored and logged for sending again. These features provide reliable and asynchronous message queuing and speed the transfer of XML message data.