How to create a Document Style Web Service

Date: 02-Jun-2003

After reading this how-to document you should be able to:

• Write a Document Style Web Service and invoke it using a JSP client.

Introduction

This document demonstrates how to create a Document Style Web Service, deploy it to OC4J and access it from a JavaServer Page client.

Software Requirements

• Oracle9iAS Containers for J2EE (OC4J) version 9.0.3 or later. You can download the OC4J from Oracle Technology Network. 

• JDK1.2.x or above This can be downloaded here .

Description

The Web Services provide two types of models for clients to interact with them.

• RPC Style Web Services
• Document Style Web Services.

RPC Style Web Services

RPC is essentially a Remote Procedure call in which the client sends a SOAP request to execute an operation on the Web Service. The SOAP request contains the name of method to be executed and the parameter it takes. The server running the Web Service converts this request to appropriate objects (java method call, EJB method call etc with parameters of defined type), executes the operation and sends the response as SOAP message to client. At the client side, this response is used to form appropriate objects and return the required information (output) to the client. RPC-style Web Services are tightly coupled because the sending parameters and return values are as described in WSDL (Web Service Description Language ) file and are wrapped in the SOAP body. Following is an example SOAP Body of RPC-style Web Service, which invokes GetStockQuote method with input parameter "ORCL".

Document-style Web Service

Document Style Web Service are loosely coupled and the request / response are in the form of XML documents. The client sends the parameter to the Web Service as XML document, instead of discrete set of parameter values. The Web Service processes the document, executes the operation and constructs & sends the response to the client as an XML document . There is no direct mapping between the server objects (parameters, method calls etc) and the values in XML documents. The application has to take care of mapping the XML data values. The SOAP Body of a document style carries one or more XML documents, within its body. The protocol places no constraint on how that document needs to be structured, which is totally handled at the application level. Document-style Web Service follows asynchronous processing. Following is an example SOAP body for Document style Web Service.

The parameters of the methods which are to be exposed by the document style Web Service should be of type XML Element only. The return type of the method can be either an XML Element or void.

Oracle9iAS supplies Servlets to access the Java classes or Stateless EJB which you write to implement a Web Service. The Servlets handle messages generated by Web Services clients and dispatch them to run the Java methods that implement Document Style Web Services. After a Web Service is deployed, when a client makes a service request (uses a service) the Oracle9iAS Web Services runtime, using an automatically generated Web Services Servlet invokes the methods that you implement to support the Document Style Web Service.

The servlet used is oracle.j2ee.ws.StatelessJavaDocWebService for a stateless Document Style Web Service and oracle.j2ee.ws.JavaDocWebService for a stateful Document style Web Service.

In this how to we will create a stateless Document style Web Service which exposes a method to test the primality of a number. It takes in a number and returns a message indicating whether the number is prime or not. This Web Service will be deployed to OC4J and we will also develop a JSP client to access this Web Service. Fig 3 shows the definition of the method, for finding the primality of number, that will be exposed by our Web Service.

public Element isPrime(Element e){


	// define an XML Element that will be returned to the client

  Element processedEl;
  try{
    // get the first clild of input element
    Node enode = e.getFirstChild();


    //get the value of input element and parse it
    String value=  enode.getNodeValue();
    double  number = Double.parseDouble(value);
    String answer=null;

    // check if the input number is prime
    answer = checkPrime(number);


    // create element from the answer
    processedEl  =createElement(answer);

  }catch(Exception ex){
    ex.printStackTrace();

  }
  // return output to client
  return processedEl;
}

The complete definition of PrimeNumberServiceImpl class can be seen here

An interface is provided to expose only the isPrime() method of the PrimeNumberServiceImpl class. The interface is as shown if Fig 4.

import  org.w3c.dom.*;


interface PrimeNumberService
{

     //method to check the primality of the number passed in Element variable
     public Element isPrime(Element e) ;

}

The complete code for Web Service and the client is provided in a zip file named PrimeNumberService.zip and can be downloaded here.

Preparing and Running the Web Service

1. Extract the PrimeNumberService.zip using Winzip utility. This will result in a directory named PrimeNumberService.

2. Navigate to PrimeNumberService directory on the command prompt and compile the Java classes as follows :

   javac -d classes src/*.java

   Make Sure you have <OC4J>/lib/xmlparserv2.jar, <OC4J>/soap/lib/soap.jar, <OC4J>/j2ee/home/lib/mail.jar, <OC4J>/j2ee/home/lib/activation.jar, <OC4J>/j2ee/home/lib/http_client.jar in your system CLASSPATH variable.

   where <OC4J> is the directory where OC4J is installed.

   Note : If you are setting the CLASSPATH on Windows system, replace "/" with "\" in directory paths of jar files.

3. Create EAR file for Web Service using WebServiceAssembler tool provided by OC4J. This tool uses information provided in the cofig.xml file to create an EAR file that can be deployed to OC4J. Open PrimeNumberService/config.xml and change the http://localhost:8888 to the host and port on which your OC4J is running. Leave it as is if you are running OC4J on local host and default port (8888).

4. Create EAR file as follows :

   java -jar <OC4J>/webservices/lib/WebServicesAssembler.jar -config config.xml 

   The EAR file will be created in PrimeNumberService directory.

5. Start up the OC4J. Navigate to <OC4J>/j2ee/home on command prompt and execute the following command :

java -jar oc4j.jar

6. Deploy the EAR file to OC4J. Open a new command prompt window and execute the following commands from PrimeNumberService directory :

   java -jar <OC4J>/j2ee/home/admin.jar ormi://host:port admin welcome -deploy
     -file PrimeNumberService.ear -deploymentName DocStyleWebService

   Bind the Web Service as follows :

   java -jar <OC4J>/j2ee/home/admin.jar ormi://host:port admin welcome -bindWebApp
     DocStyleWebService PrimeNumberService_web http-web-site /docws

   Change host and port for your OC4J in above commands.

7. Check if Web Service is up and running from the browser as follows :

   http://yourhost.com:8888/docws/prime

Preparing and Executing the Client JSP

1. The client JSP is provided in PrimeNumberService/client directory. Copy this Client.jsp to <OC4J>/j2ee/home/default-web-app directory.

2. Get the Web Service's proxy class for accessing Web Service as follows from the browser:

   http://yourhost:8888/docws/prime?proxy_jar

   Save the proxy jar file (prime.zip) in <OC4J>/j2ee/home/lib directory. Restart the OC4J so that prime.zip is available in the classpath.

   If you are using OC4J 9.0.4, the file prime.zip should be copied to <OC4J>/j2ee/home/applib directory ( create applib directory if it does not exist already).

3. Access the Client.jsp from browser

   http://yourhost:8888/Client.jsp

Resources

• Developing Document Style Web Services at Web Services Developer's Guide
• Web Sevices Sample Corner on OTN

Summary

This how-to document explained how to create a Document Style Web Service with OC4J and access it using a JSP client.

Please enter your comments about this how-to in the OTN Sample Code Discussion Forum