6 Developing and Deploying Document Style Web Services

6.2.1.1 Passing Null Values for Document Style Web Services

A null could be passed as an input Element or as the Element that the Document Style Web Service returns.

6.2.1.2 Arrays of Elements

Oracle Application Server Web Services does not support Element[] (arrays of org.w3c.dom.Element).

6.2.3.1 Defining Methods in a Document Style Web Service

Create a Document Style Web Service by writing or supplying a Java class with methods that are deployed as a Document Style Web Service. The stateful and stateless sample directories contain sample stateless and stateful Document Style Web Services. In the src directories, the file StatefulDocImpl.java provides the implementation of the sample stateful Java service and StatelessDocImpl.java provides the implementation of the stateless Document Style Web Service. These examples use interface classes; the use of interface classes is optional when implementing Document Style Web Services.

A Java class that implements a Document Style Web Service has the following limitations:

• The Java class should define public methods that conform to the method signatures shown in Table 6-1. If you use an interface, then only the public methods specified in the interface need to conform to the method signature restrictions. If you do not include an interface, then all the public methods in the class must conform to the method signature restrictions shown in Table 6-1.

• The Java class implementation must include a public constructor that takes no arguments.

There are very few restrictions on what actions a Document Style Java class based web service can perform. At a minimum, the service performs some action to handle an incoming message (Element) or to generate an outgoing message (Element).

The StatelessDoc Web Service sample is implemented with StatelessDocImpl, a public class and the interface StatelessDoc. The StatelessDocImpl class defines two public methods: displayElement(), that displays the incoming message on the server where the web service runs, and processElement(), that takes an incoming message and returns a transformed message to the client. The private method applyXSLtoXML() is a helper method that transforms the incoming message, as specified in the converter.xsl file.

Example 6-1 shows the method signatures for the StatelessDocImpl class (see the src directory to view the complete source code for StatelessDocImpl).

import org.w3c.dom.*;
import oracle.xml.parser.v2.*;
import java.io.*;

public class StatelessDocImpl implements StatelessDoc

{
    public StatelessDocImpl()
    {  }

  // Display the Element that was sent
  public void displayElement(Element e)
  {  }
 
 //method to process the input xml doc
  public Element processElement(Element e) 
  {  }

 /**
 * This Method Transforms an XML Document into another using the provided
 * Style Sheet: converter.xsl.  Note : This Method makes use of XSL 
 *  Transformation capabilities of Oracle XML Parser Version 2.0
 **/
 private Element applyXSLtoXML(Element e)
  throws Exception
  {}

import org.w3c.dom.*;
import oracle.xml.parser.v2.*;

public class StatefulDocImpl implements StatefulDoc
  private Element e ;
  public void startShopping(Element e) 
  {
  }
  public Element makePurchase()
  {
  }
  private void  processElement(Element e) {
 }

6.2.3.2 Defining an Interface for Explicit Method Exposure

Oracle Application Server Web Services allows you to limit the methods you expose as Document Style Web Services by supplying a public interface. To limit the methods exposed in a Web Service, include a public interface that lists the method signatures for the methods that you want to expose. Example 6-3 shows an interface for the methods in the class StatelessDocImpl. Example 6-4 shows an interface for the methods in the class StatelfulDocImpl.

When an interface is included with a Document Style Web Service, then only the public methods specified in the interface need to conform to the method signature restrictions shown in Table 6-1. If you do not include an interface, then all the public methods in the class must conform to the method signature restrictions. Using an interface, for example StatelessDoc shown in Example 6-3, only the methods with the specified method signatures are exposed when the Java class is prepared and deployed as a Document Style Web Service.

Use a Document Style Web Service interface for the following purposes:

1. To limit the exposure of methods to a subset of the public methods within a class.

2. To expand the set of methods that are exposed to include methods within the superclass of a class.

3. To limit the exposure of methods to a subset of the public methods within a class, where the subset contains only the methods that use supported method signatures. Table 6-1 lists the supported signatures for Java methods that implement Document Style Web Services.

import  org.w3c.dom.*;

public interface StatelessDoc
{
     //method to display the element
     public void displayElement(Element e) ;

     //method to process the input xml doc
     public Element processElement(Element e) ;
}

import org.w3c.dom.Element;

// Interface that implements getElement and setElement
public interface StatefulDoc {

  // Set the Element
  public void startShopping(Element e);

  // Retrieve the element that was set
  public Element makePurchase();
}

6.2.3.3 Handling Messages for Document Style Web Services

It is entirely up to the Web Service developer to determine the processing that occurs for messages associated with a Document Style Web Service.

The message associated with a Document Style Web Service is specified in the Element parameter or the Element return value associated with the Document Style Web Service. It is the Document Style Web Service developer's job to process or generate messages. The only limitation on Document Style Web Service messages is that the Element must conform to must conform to the Document Object Model (DOM) as specified by the W3C (org.w3c.dom.Element).

A Document Style Web Service implementation or the client that uses a service may need to supports null values, since a null could be passed as an input Element or as the Element that is returned.

For example, the following is valid for a Document Style Web Service implementation:

Element get_op () {
    return null;
}

6.3.1.1 Adding Web Service Top Level Tags

Table 6-2 describes the top level WebServicesAssembler configuration file tags. Add these tags to provide top level information describing the Document Style Web Service.

Example 6-5 shows a complete stateless sample configuration file. Example 6-6 shows a complete stateful sample configuration file. The stateless and stateful directories in the java_doc_services demo directory contain the sample config.xml files.

<option name="source-path" contextroot="/test">/myTestArea/ws/src/statefull.war</option>

6.3.1.2 Adding Java Service Tags with Document Message Style Specified

The Document Style Web Service developer determines if the service is stateful or stateless. The configuration file includes different tags depending on the type of the service. This section covers the tags for both cases, including:

• Adding Stateful Document Style Java Service Tags

• Adding Stateless Document Style Java Service Tags

6.3.1.3 Adding WSDL and Client-Side Proxy Generation Tags

The WebServicesAssembler configuration file supports the <wsdl-gen> and <proxy-gen> tags to allow a Web Service developer to generate Web Service description WSDL files and client-side proxy files. You can add these tags to control whether the WSDL file and the client-side proxy are generated. You can also specify that the WSDL file be assembled with the Document Style Web Service .ear. A client-side developer can then obtain the WSDL file from the deployed Web Service and use it to build an application.

<web-service>
    <display-name>Stateful Java Document Web Service</display-name>
    <description>Stateful Java Document Web Service Example</description>
    <!-- Specifies the resulting web service archive will be stored in ./docws.ear -->
    <destination-path>./docws.ear</destination-path>
    <!-- Specifies the temporary directory that web service assembly tool can create temporary files. -->
    <temporary-directory>./temp</temporary-directory>
    <!-- Specifies the web service will be accessed in the servlet context named "/docws". -->
    <context>/statefuldocws</context>

    <!-- Specifies the web service will be stateful -->

    <stateful-java-service>
        <interface-name>StatefulDoc</interface-name>
        <class-name>StatefulDocImpl</class-name>
        <!-- Specifies the web service will be accessed in the uri named "/docService" within the servlet context. -->
        <uri>/docservice</uri>
        <!-- Specifies the location of Java class files ./classes -->
        <java-resource>./classes</java-resource>
        <!-- Specifies that it uses document style SOAP messaging -->
        <message-style>doc</message-style>
   </stateful-java-service>

    <!-- generate the wsdl -->
    <wsdl-gen>
	   <wsdl-dir>wsdl</wsdl-dir>
    <!-- over-write a pregenerated wsdl , turn it 'false' to use the pregenerated wsdl-->
	   <option name="force">true</option>
	   <option name="httpServerURL">http://localhost:8888</option>
    </wsdl-gen>

    <!-- generate the proxy -->

    <proxy-gen>
	   <proxy-dir>proxy</proxy-dir>
	   <option name="include-source">true</option>
    </proxy-gen>
</web-service>

<web-service>
    <display-name>Stateless Java Document Web Service</display-name>
    <description>Stateless Java Document Web Service Example</description>
    <!-- Specifies the resulting web service archive will be stored in ./statelessdocws.ear -->
    <destination-path>./statelessdocws.ear</destination-path>
    <!-- Specifies the temporary directory that web service assembly tool can create temporary files. -->
    <temporary-directory>./temp</temporary-directory>
    <!-- Specifies the web service will be accessed in the servlet context named "/statelessdocws". -->
    <context>/statelessdocws</context>
    <!-- to package the  stylesheet to format input xml --> 
    <option name="source-path">converter.xsl</option> 

    <!-- Specifies the web service will be stateless -->

    <stateless-java-service>
        <interface-name>StatelessDoc</interface-name>
        <class-name>StatelessDocImpl</class-name>
        <!-- Specifies the web service will be accessed in the uri named "/docService" within the servlet context. -->
        <uri>/docservice</uri>
        <!-- Specifies the location of Java class files ./classes -->
        <java-resource>./classes</java-resource>
        <!-- Specifies that it uses document style SOAP messaging -->
        <message-style>doc</message-style>
   </stateless-java-service>

    <!-- generate the wsdl -->
    <wsdl-gen>
	   <wsdl-dir>wsdl</wsdl-dir>
    <!-- over-write a pregenerated wsdl , turn it 'false' to use the pregenerated wsdl-->
	   <option name="force">true</option>
	   <option name="httpServerURL">http://localhost:8888</option>
    </wsdl-gen>

    <!-- generate the proxy -->
    <proxy-gen>
	   <proxy-dir>proxy</proxy-dir>
	   <option name="include-source">true</option>
    </proxy-gen>

</web-service>