25
Oracle XML DB Case Study: Web Services Retrieve and Display XML Documents

This chapter describes how you can access XML documents stored in Oracle XML DB Repository through Web Services. It contains the following sections:

XML DB Web Services Case Study: Overview

This case study illustrates how you can use Web Services to fetch XML purchase order (PO) documents stored in XML DB. Based on the PO number you enter from the Browser, the application uses a Java servlet to invoke a Web Service that in turn accesses XML DB and invokes Java API for XMLType.SQL queries are processed and the application retrieves XML documents from XML DB as Java strings for displaying on a Browser.

Note:

This case study is intended to run on Internet Explorer 6.0 or higher.
See also Chapter 26, "Oracle XML DB Basic Demo" for further examples of how PO XML documents can be stored, accessed, and processed in Oracle XML DB.

What Happens When You Enter a PO Number?

This application is invoked when you enter a PO number from a Browser. See Figure 25-1.

Figure 25-1 Entering a Purchase Order (PO) Number

Text description of websvc1.gif follows.

Text description of the illustration websvc1.gif

Oracle XML Db Web Services: Main Components

Figure 25-2 shows the main components used in the XML DB Web Services application:

A Browser
SOAP client
Web Services Server
Oracle XML DB on Oracle9i

Figure 25-2 XML DB Web Services Case Study: Main Components

Text description of adxdb044.gif follows

Text description of the illustration adxdb044.gif

Running XML DB Web Services Case Study: Implementation Steps

Follow these steps when running the XML DB Web Services case study.

Before You Run this Case Study Demo

Before you run this XML DB Web Services case study, carry out the following:

Ensure that you have Internet Explorer 6.0 or higher installed.
Use Oracle9i JDeveloper to generate the Web Services files you need. Figure 25-3 shows Oracle9i JDeveloper Java Bean Wizard. Use this to generate the following three files used to access Web Services:
- WSDL document, XDBServicesService.wsdl. See "XDBServicesService.wsdl".
- Deployment Description, XDBServicesDeploymentDescriptor.dd. See "XDBServicesDeploymentDescriptor.dd".
- Web Services client stub, XDBServicesStub.java. See "XDBServicesStub.java".

Listings of these three files are provided in the following paragraphs.

Figure 25-3 Using Oracle9i JDeveloper Java Bean Wizard

Text description of JDev9i1.jpg follows.

Text description of the illustration JDev9i1.jpg

XDBServicesService.wsdl

<?xml version="1.0" ?> 
- <!-- Generated by the Oracle9i JDeveloper Web Services WSDL Generator --> 
- <!-- Date Created: Mon Jul 15 16:34:24 PDT 2002--> 
- <definitions name="XDBServices"
   targetNamespace="http://www.oracle.com/jdeveloper/generated/XDBServices"
   xmlns="http://schemas.xmlsoap.org/wsdl/" 
   xmlns:xsd="http://www.w3.org/2001/XMLSchema"
   xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
   xmlns:tns="http://www.oracle.com/jdeveloper/generated/XDBServices"
   xmlns:ns1="http://www.oracle.com/jdeveloper/generated/XDBServices/schema"> 
- <types> 
 <schema 
 targetNamespace="http://www.oracle.com/jdeveloper/generated/XDBServices/schema"
 xmlns="http://www.w3.org/2001/XMLSchema" 
xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" /> 
</types> 
- <message name="getPOFromNumber0Request"> 
    <part name="PONumber" type="xsd:string" /> 
  </message> 
- <message name="getPOFromNumber0Response"> 
    <part name="return" type="xsd:string" /> 
  </message> 
- <message name="getPOXML1Request"> 
    <part name="PONumber" type="xsd:string" /> 
  </message> 
- <message name="getPOXML1Response"> 
    <part name="return" type="xsd:string" /> 
  </message> 
- <portType name="XDBServicesPortType"> 
- <operation name="getPOFromNumber"> 
<input name="getPOFromNumber0Request" message="tns:getPOFromNumber0Request" /> 
<output name="getPOFromNumber0Response" message="tns:getPOFromNumber0Response" 
/> 
</operation> 
- <operation name="getPOXML"> 
   <input name="getPOXML1Request" message="tns:getPOXML1Request" /> 
   <output name="getPOXML1Response" message="tns:getPOXML1Response" /> 
  </operation> 
</portType> 
- <binding name="XDBServicesBinding" type="tns:XDBServicesPortType"> 
  <soap:binding style="rpc" transport="http://schemas.xmlsoap.org/soap/http" /> 
- <operation name="getPOFromNumber"> 
  <soap:operation soapAction="" style="rpc" /> 
- <input name="getPOFromNumber0Request"> 
  <soap:body use="encoded" namespace="urn:POFetcher" 
encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" /> 
</input> 
- <output name="getPOFromNumber0Response"> 
<soap:body use="encoded" namespace="urn:POFetcher" 
encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" /> 
</output> 
</operation> 
- <operation name="getPOXML"> 
   <soap:operation soapAction="" style="rpc" /> 
- <input name="getPOXML1Request"> 
   <soap:body use="encoded" namespace="urn:POFetcher"
    encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" /> 
  </input> 
- <output name="getPOXML1Response"> 
  <soap:body use="encoded" namespace="urn:POFetcher"
    encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" /> 
</output> 
</operation> 
</binding> 
- <service name="XDBServices"> 
- <port name="XDBServicesPort" binding="tns:XDBServicesBinding"> 
   <soap:address
    location="http://dlsun653.us.oracle.com:7070/soap/servlet/rpcrouter" /> 
  </port> 
 </service> 
</definitions>

XDBServicesDeploymentDescriptor.dd

<?xml version="1.0" ?> 
- <!-- Generated by the Oracle9i JDeveloper Web Services Deployment Descriptor 
Generator --> 
- <!-- This Deployment Descriptor file is for use with the Oracle9iAS Release 2 
/ Apache 2.2 SOAP Server SOAP Server --> 
- <!-- Date Created: Mon Jul 15 16:34:26 PDT 2002--> 
   - <isd:service id="urn:POFetcher"
         xmlns:isd="http://xml.apache.org/xml-soap/deployment"> 
     - <isd:provider type="java" methods="getPOFromNumber getPOXML"
         scope="Request"> 
          <isd:java class="XDBServices" static="false" /> 
       </isd:provider> 
<isd:faultListener>org.apache.soap.server.DOMFaultListener</isd:faultListener> 
</isd:service>

XDBServicesStub.java

package mypackage;
import oracle.soap.transport.http.OracleSOAPHTTPConnection;
import java.net.URL;
import org.apache.soap.Constants;
import org.apache.soap.Fault;
import org.apache.soap.SOAPException;
import org.apache.soap.rpc.Call;
import org.apache.soap.rpc.Parameter;
import org.apache.soap.rpc.Response;
import java.util.Vector;
import java.util.Properties;
/**
 * Generated by the Oracle9i JDeveloper Web Services Stub/Skeleton Generator.
 * Date Created: Mon Jul 15 16:36:21 PDT 2002
 */

public class XDBServicesStub 
{
  public String endpoint = "http://localhost:7070/soap/servlet/rpcrouter";
  private OracleSOAPHTTPConnection m_httpConnection = null;

  public XDBServicesStub()
  {
    m_httpConnection = new OracleSOAPHTTPConnection();
  }

  public String getPOFromNumber(String PONumber) throws Exception
  {
    String returnVal = null;

    URL endpointURL = new URL(endpoint);
    Call call = new Call();
    call.setSOAPTransport(m_httpConnection);
    call.setTargetObjectURI("urn:POFetcher");
    call.setMethodName("getPOFromNumber");
    call.setEncodingStyleURI(Constants.NS_URI_SOAP_ENC);
    Vector params = new Vector();
    params.addElement(new Parameter("PONumber", String.class, PONumber, null));
    call.setParams(params);

    Response response = call.invoke(endpointURL, "");

    if (!response.generatedFault())
    {
      Parameter result = response.getReturnValue();
      returnVal = (String)result.getValue();
    }
    else
    {
      Fault fault = response.getFault();
      throw new SOAPException(fault.getFaultCode(), fault.getFaultString());
    }

    return returnVal;
  }

  public String getPOXML(String PONumber) throws Exception
  {
    String returnVal = null;

    URL endpointURL = new URL(endpoint);
    Call call = new Call();
    call.setSOAPTransport(m_httpConnection);
    call.setTargetObjectURI("urn:POFetcher");
    call.setMethodName("getPOXML");
    call.setEncodingStyleURI(Constants.NS_URI_SOAP_ENC);
    Vector params = new Vector();
    params.addElement(new Parameter("PONumber", String.class, PONumber, null));
    call.setParams(params);

    Response response = call.invoke(endpointURL, "");

    if (!response.generatedFault())
    {
      Parameter result = response.getReturnValue();
      returnVal = (String)result.getValue();
    }
    else
    {
      Fault fault = response.getFault();
      throw new SOAPException(fault.getFaultCode(), fault.getFaultString());
    }

    return returnVal;
  }

  public void setMaintainSession(boolean maintainSession)
  {
    m_httpConnection.setMaintainSession(maintainSession);
  }

  public boolean getMaintainSession()
  {
    return m_httpConnection.getMaintainSession();
  }

  public void setTransportProperties(Properties props)
  {
    m_httpConnection.setProperties(props);
  }

  public Properties getTransportProperties()
  {
    return m_httpConnection.getProperties();
  }
}

Steps for Implementing the XML DB Web Services Case Study

Figure 25-4 lists the steps needed to implement this application.

Figure 25-4 Oracle XML DB Web Services Case Study: Implementation Steps

Text description of adxdb045.gif follows

Text description of the illustration adxdb045.gif

1. Run XDBServices.java

XDBServices.java accesses XML DB using Java DOM API for XMLType. This Java Bean also:

Formats the XMLType query string
Connects to XML DB using a JDBC thick driver
Retrieves an XMLType instance
Returns the required XML PO document as a Java string

XDBServices.java implements the following actions:

Imports the Java DOM API for XMLType:
```
import oracle.xdb.XMLType;
```
Java DOM API for XMLType handles all kinds of valid XML documents. It presents to the application a uniform view of the XML document regardless of whether it is XML schema-based or non- schema-based, whatever the underlying storage in Oracle XML DB. Java DOM API works on client and server.

Formats the resulting query string:

static String qryXMLStr = "select value(x) from purchaseorder x where 
existsNode(value(x),'/PurchaseOrder[Reference=\"PO_NUMBER\"]') = 1 ";

 public String getPOXML(String PONumber) throws Exception
  {
    String res = null;
    XMLType xt = null;
    XMLType xt1 = null;

Connects to XML DB using JDBC thick driver:

System.out.println("Driver registering...");
    DriverManager.registerDriver(new oracle.jdbc.driver.OracleDriver());
    System.out.println("Driver registered");

    System.out.println("Connecting...");
    Connection conn = DriverManager.getConnection(conStr, user, pass);
    Hashtable map = (Hashtable) ((OracleConnection)conn).getTypeMap ();
    map.put ("SYS.XMLTYPE", Class.forName ("oracle.xdb.XMLTypeFactory"));
    System.out.println("Connection obtained");

Retrieves an XMLType instance:

//retrieve PurchaseOrder xml documnet from database
      System.out.println("Generating XMLType object ...");
      xt = (XMLType)orset.getObject(1);
      res = xt.getStringVal();
      System.out.println("Print out xt as String ...");
      System.out.println(res);
      System.out.println("##Results printed");
    }

Returns the XML PO document as a Java string:
```
return res;
```
See Also:
"XDBServices.java" for the detailed listing of XDBServices.java.

2. Implement GetPOXMLServlet.java

GetPOXMLServlet.java performs the following tasks:

Accepts the user's PO number entered at the Browser
Calls XDBServiceStub.java
Fetches the PO by invoking Web Service through XDBServices.java
Sends the PO to be displayed on the Browser

See Also:
"getPOXMLServlet.java" for the detailed listing of getPOXMLServlet.java.

3. Deploy XDBServices Class to the Oracle9iAS/Web Services (SOAP) Server

To run this application you need to actually deploy the XDBServicesDeploymentDescriptor.dd.

XDBServicesDeploymentDescriptor.dd

<?xml version="1.0" ?> 
- <!-- Generated by the Oracle9i JDeveloper Web Services Deployment Descriptor 
Generator --> 
- <!-- This Deployment Descriptor file is for use with the Oracle9iAS Release 2 
/ Apache 2.2 SOAP Server SOAP Server --> 
- <!-- Date Created: Mon Jul 15 16:34:26 PDT 2002--> 
   - <isd:service id="urn:POFetcher"
         xmlns:isd="http://xml.apache.org/xml-soap/deployment"> 
     - <isd:provider type="java" methods="getPOFromNumber getPOXML"
         scope="Request"> 
          <isd:java class="XDBServices" static="false" /> 
       </isd:provider> 
<isd:faultListener>org.apache.soap.server.DOMFaultListener</isd:faultListener> 
</isd:service>

See Also:

Oracle9i Java Developer's Guide for a detailed description on how to deploy a Web Service.

Web Services: Deployed Service Information for POFetcher Service

Table 25-1 lists the Web Services POFetcher properties. The application uses one of POFetcher's method getPOXML. It uses XDBServices class to access Oracle XML DB.

Table 25-1 urn:POFetcher Service Deployment Descriptor

Property	Details
ID	urn:POFetcher
Scope	Application
Provider Type	java
Provider Class	XDBServices
Use Static Class	false
Methods	getPOFromNumber, getPOXML

4. Deploy displayPOXML.html to Display Results on Client-Side Web Server

Deploy displayPOXML.html and Java classes, GetPOXMLServlet and XDBServicesStub, to any client-side web server with a JSP/Servlet engine. See Figure 25-5.

Figure 25-5 Results of Deploying displayPOXML.html

Text description of websvc_html.gif follows.

Text description of the illustration websvc_html.gif

5. Enter a PO Number and See the Retrieved PO Displayed

From your Internet Explorer Browser window, enter a PO number and click Submit Query. Figure 25-6 shows the PO number entry field.

Figure 25-6 Entering a Purchase Order (PO) Number

Text description of the illustration websvc1.gif

The requested PO is retrieved through the POFetcher Web Service and displayed in XML on your Internet Explorer Browser.

XML DB Web Services: Calling Sequence

Figure 25-7 illustrates schematically XML DB Web Service application's calling sequence.

Figure 25-7 XML DB Web Services: Calling Sequence

Text description of adxdb046.gif follows

Text description of the illustration adxdb046.gif

XDBServices.java

Here is full code listing for XDBServices.java. Its calling sequence was explained in the preceding paragraphs:

/*
   XDBServices.java:

   DESCRIPTION:
    The server Java bean that provides the XML DB web services to fetch
    a user-specified PO.
  
   MODIFIED     (MM/DD/YYYY) 
    Geoff Lee    07/15/2002 - Cleaned up for viewlet recording
  
 */

import java.sql.*;
import java.io.*;
import java.util.Hashtable;

import oracle.jdbc.driver.*;
import oracle.sql.*;

import oracle.xdb.XMLType;

public class XDBServices
{
  static String conStr = "jdbc:oracle:oci8:@";
  static String user = "scott";
  static String pass = "tiger";

  static String qryXMLStr = "select value(x) from purchaseorder x where 
existsNode(value(x),'/PurchaseOrder[Reference=\"PO_NUMBER\"]') = 1 ";

  static String qryStr = "select 
x.transform(xdburitype('/public/SCOTT/xsl/po.xsl').getXML()) from purchaseorder 
x where existsNode(value(x),'/PurchaseOrder[Reference=\"PO_NUMBER\"]') = 1 ";

 public String getPOFromNumber (String PONumber) throws Exception
  {
    String res = null;
    XMLType xt = null;
    XMLType xt1 = null;

    try{

        // Replace the PO_NUMBER placeholder with the input
        int po_start = qryStr.indexOf ("PO_NUMBER");
        String poQryStr = new StringBuffer(qryStr).replace(po_start, po_start + 
9, PONumber).toString();
        System.out.println("poQryStr="+ poQryStr);

        System.out.println("Driver registering...");
        DriverManager.registerDriver(new oracle.jdbc.driver.OracleDriver());
        System.out.println("Driver registered");

        System.out.println("Connecting...");
        Connection conn = DriverManager.getConnection(conStr, user, pass);
        Hashtable map = (Hashtable) ((OracleConnection)conn).getTypeMap ();
        map.put ("SYS.XMLTYPE", Class.forName ("oracle.xdb.XMLTypeFactory"));
        System.out.println("Connection obtained");

        System.out.println("Statement preparing...");
        OraclePreparedStatement stmt  = 
(OraclePreparedStatement)conn.prepareStatement (poQryStr);
        System.out.println("Statement prepared");

        System.out.println("Query executing...");
        ResultSet rset = stmt.executeQuery(poQryStr);
        System.out.println("Query executed");
        OracleResultSet orset = (OracleResultSet) rset;
        System.out.println("ResultSet casted");

        while (orset.next())
        {
          //retrieve PurchaseOrder xml documnet from database
          System.out.println("Generating XMLType object ...");
          xt = (XMLType)orset.getObject(1);
          res = xt.getStringVal();

          System.out.println("Print out xt as String ...");
          System.out.println(res);
          System.out.println("##Results printed");
        }

      //close the result set, statement, and the connection
      rset.close();
      stmt.close();
      conn.close();


    }
    catch( Exception e )
    {
      e.printStackTrace(System.out);
    }
          
          return res;

  }
 //
 // This method returns the PO in XML format
 //
 public String getPOXML (String PONumber) throws Exception
  {
    String res = null;
    XMLType xt = null;
    XMLType xt1 = null;

    try{
        // Replace the PO_NUMBER placeholder with the input
        int po_start = qryXMLStr.indexOf ("PO_NUMBER");
        String poQryStr = new StringBuffer(qryXMLStr).replace(po_start, po_start 
+ 9, PONumber).toString();
  
        System.out.println("poQryStr="+ poQryStr);

        System.out.println("Driver registering...");
        DriverManager.registerDriver(new oracle.jdbc.driver.OracleDriver());
        System.out.println("Driver registered");

        System.out.println("Connecting...");
        Connection conn = DriverManager.getConnection(conStr, user, pass);
        Hashtable map = (Hashtable) ((OracleConnection)conn).getTypeMap ();
        map.put ("SYS.XMLTYPE", Class.forName ("oracle.xdb.XMLTypeFactory"));
        System.out.println("Connection obtained");

        System.out.println("Statement preparing...");
        OraclePreparedStatement stmt  = 
(OraclePreparedStatement)conn.prepareStatement (poQryStr);
        System.out.println("Statement prepared");

        System.out.println("Query executing...");
        ResultSet rset = stmt.executeQuery(poQryStr);
        System.out.println("Query executed");
        OracleResultSet orset = (OracleResultSet) rset;
        System.out.println("ResultSet casted");

        while (orset.next())
        {
          //retrieve PurchaseOrder xml documnet from database
          System.out.println("Generating XMLType object ...");
          xt = (XMLType)orset.getObject(1);
          res = xt.getStringVal();

          System.out.println("Print out xt as String ...");
          System.out.println(res);
          System.out.println("##Results printed");
        }
      //close the result set, statement, and the connection
      rset.close();
      stmt.close();
      conn.close();

    }
    catch( Exception e )
    {
      e.printStackTrace(System.out);
    }
          
          return res;
  }
}

getPOXMLServlet.java

Here is the detailed listing of getPOXMLServlet.java:

/*
   GetPOServlet.java:

   DESCRIPTION:
    The Java servlet that
    1. Accepts a user-specified PO number
    2. Calls the client Java bean of the web service
    3. Display the PO fetched from the XML DB by the 'POFetched' web service
  
 */

import javax.servlet.*;
import javax.servlet.http.*;
import java.io.*;
import java.util.*;
import XDBServicesStub;

public class GetPOServlet extends HttpServlet 
{
  private static final String CONTENT_TYPE = "text/html; charset=windows-1252";
  public void init(ServletConfig config) throws ServletException
  {
    super.init(config);
  }

  public void doGet(HttpServletRequest request, HttpServletResponse response) 
throws ServletException, IOException
  {
    String PONumber = "";
    String poResult = "";
    try
    {
      PONumber = request.getParameter("PONumberSelect");
      XDBServicesStub poBean = new XDBServicesStub();
      poResult = poBean.GetPO(PONumber);
    }
    catch(Exception e)
    {
      e.printStackTrace();
    }

    response.setContentType(CONTENT_TYPE);
    PrintWriter out = response.getWriter();
    out.println(poResult);
    out.close();
  }

  public void doPost(HttpServletRequest request, HttpServletResponse response) 
throws ServletException, IOException
  {
    String PONumber = "";
    String poResult = "";
    try
    {
      PONumber = request.getParameter("PONumberSelect");
      XDBServicesStub poBean = new XDBServicesStub();
      poResult = poBean.GetPO(PONumber);
    }
    catch(Exception e)
    {
      e.printStackTrace();
    }

    response.setContentType(CONTENT_TYPE);
    PrintWriter out = response.getWriter();
    out.println(poResult);
    out.close();
  }
}

25 Oracle XML DB Case Study: Web Services Retrieve and Display XML Documents

XML DB Web Services Case Study: Overview

What Happens When You Enter a PO Number?

Figure 25-1 Entering a Purchase Order (PO) Number

Oracle XML Db Web Services: Main Components

Figure 25-2 XML DB Web Services Case Study: Main Components

Running XML DB Web Services Case Study: Implementation Steps

Before You Run this Case Study Demo

Figure 25-3 Using Oracle9i JDeveloper Java Bean Wizard

XDBServicesService.wsdl

XDBServicesDeploymentDescriptor.dd

XDBServicesStub.java

Steps for Implementing the XML DB Web Services Case Study

Figure 25-4 Oracle XML DB Web Services Case Study: Implementation Steps

1. Run XDBServices.java

2. Implement GetPOXMLServlet.java

3. Deploy XDBServices Class to the Oracle9iAS/Web Services (SOAP) Server

XDBServicesDeploymentDescriptor.dd

Web Services: Deployed Service Information for POFetcher Service

Table 25-1 urn:POFetcher Service Deployment Descriptor

4. Deploy displayPOXML.html to Display Results on Client-Side Web Server

Figure 25-5 Results of Deploying displayPOXML.html

5. Enter a PO Number and See the Retrieved PO Displayed

Figure 25-6 Entering a Purchase Order (PO) Number

XML DB Web Services: Calling Sequence

Figure 25-7 XML DB Web Services: Calling Sequence

XDBServices.java

getPOXMLServlet.java

25
Oracle XML DB Case Study: Web Services Retrieve and Display XML Documents