Skip Headers

Oracle9i Application Server Web Services Developer's Guide
Release 2 (9.0.2)
Part Number A95453-01
Go To Documentation Library
Home		 Go To Product List
Solution Area		 Go To Table Of Contents
Contents		 Go To Index
Index

Go to previous page Go to next page

3
Developing and Deploying Java Class Web Services

This chapter describes the procedures you use to write and deploy Oracle9iAS Web Services that are implemented as Java classes.

This chapter covers the following topics:

Using Oracle9iAS Web Services With Java Classes

Oracle9iAS Web Services can be implemented as any of the following:

This chapter shows sample code for writing Web Services implemented with Java classes and describes the difference between writing stateful and stateless Java Web Services.

Oracle9iAS supplies Servlets to access the Java classes which implement a Web Service. The Servlets handle requests generated by Web Services clients, run the Java methods that implement the Web Services and return results back to Web Services clients.

See Also:

Writing Java Class Based Web Services

Writing Java class based Web Services involves building a Java class that includes one or more methods that a Web Services Servlet running under Oracle9iAS Web Services invokes when a Web Services client makes a service request. There are very few restrictions on what actions Web Services can perform. At a minimum, Web Services generate some data that is sent to a client or perform an action as specified by a Web Service request.

This section shows how to write a stateful and a stateless Java Web Service that returns a string, "Hello World". The stateful service also returns an integer running count of the number of method calls to the service. This Java Web Service receives a client request and generates a response that is returned to the Web Service client.

The sample code is supplied with Oracle9iAS Web Services in the directory $ORACLE_HOME/j2ee/home/demo/web_services/java_services on UNIX or in %ORACLE_HOME%\j2ee\home\demo\web_services\java_services on Windows.

Writing Stateless and Stateful Java Web Services

Oracle9iAS Web Services supports stateful and stateless implementations for Java classes running as Web Services. For a stateful Java implementation, Oracle9iAS Web Services allows a single Java instance to serve the Web Service requests from an individual client.

For a stateless Java implementation, Oracle9iAS Web Services creates multiple instances of the Java class in a pool, any one of which may be used to service a request. After servicing the request, the object is returned to the pool for use by a subsequent request.

Note:

It is the job of the Web Services developer to make the design decision to implement a stateful or stateless Web Service. When packaging Web Services, stateless and stateful Web Services are handled slightly differently. This chapter describes these differences in the section, "Preparing and Deploying Java Class Based Web Services".

Building a Sample Java Class Implementation

Developing a Java Web Service consists of the following steps:

Defining a Java Class Containing Methods for the Web Service

Create a Java Web Service by writing or supplying a Java class with methods that are deployed as a Web Service. In the sample supplied in the java_services sample directory, the .ear file, ws_example.ear contains the Web Service source, class, and configuration files. If you expand the .ear file, the class StatefulExampleImpl provides the stateful Java service and StatelessExampleImpl provides the stateless Java service.

When writing a Java Web Service, if you want to place the Java service in a package, use the Java package specification to name the package. The first line of StatefulExampleImpl.java specifies the package name, as follows: 

package oracle.j2ee.ws_example;

The stateless sample Web Service is implemented with StatelessExampleImpl, a public class. The class defines a public method, helloWorld(). In general, a Java class for a Web Service defines one or more public methods. Example 3-1 shows StatelessExampleImpl.

The stateful sample Web Service is implemented with StatefulExampleImpl, a public class. The class initializes the count and defines two public methods, count() and helloWorld(). Example 3-2 shows StatelessExampleImpl.

Example 3-1 Defining A Public Class with Java Methods for a Stateless Web Service

public class StatelessExampleImpl {
    public StatelessExampleImpl() {
  }
  public String helloWorld(String param) {
    return "Hello World, " + param;
  }
}

Example 3-2 Defining a Public Class with Java Methods for a Stateful Web Service

public class StatefulExampleImpl {
  int count = 0;
  public StatefulExampleImpl() {
  }
  public int count() {
    return count++;
  }
  public String helloWorld(String param) {
    return "Hello World, " + param;
  }
}

A Java class implementation for a Web Service must include a public constructor that takes no arguments. For example, Example 3-1 shows the public constructor StatelessExampleImpl().

When an error occurs while running a Web Service implemented as a Java class, the Java class should throw an exception. When an exception is thrown, the Web Services Servlet returns a Web Services (SOAP) fault. Use the standard J2EE and OC4J administration facilities for logging Servlet errors for the Web Service that uses Java classes for its implementation.

When you create a Java class containing methods that implement a Web Service, the method's parameters and return values must use supported types, or you need to use an interface class to limit the methods exposed to those methods using only supported types. Table 4-1 lists the supported types for parameters and return values for Java methods that implement Web Services.

Note:

See Table 4-1 for the list of supported types for parameters and return values.

Defining an Interface for Explicit Method Exposure

Oracle9iAS Web Services allows you to limit the methods you expose as 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 3-3 shows an interface to the method in the class StatelessExampleImpl. Example 3-4 shows an interface to the methods in the class StatefulExampleImpl.

Example 3-3 Using a Public Interface to Expose Stateless Web Services Methods

public interface StatelessExample {
String helloWorld(String param);
}

Example 3-4 Using a Public Interface to Expose Stateful Web Services Methods

public interface StatefulExample {
int count();
String helloWorld(String param);
}

When an interface class is not included with a Web Service, the Web Services deployment exposes all public methods defined in the Java class. Using an interface, for example StatelessExample shown in Example 3-3 or StatefulExample shown in Example 3-4, exposes only the methods listed in the interface. Using an interface, only the methods with the specified method signatures are exposed when the Java class is prepared and deployed as a Web Service.

Use a Web Services 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 as Web Services 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 types for parameters or return values. Table 4-1 lists the supported types for parameters and return values for Java methods that implement Web Services.

    See Also:

Writing a WSDL File or Client-Side Proxy (Optional)

When writing a Java class based Web Service, this step is optional. If you do not perform this step, the Oracle9iAS Web Services runtime generates a WSDL file and the client-side proxies for deployed Web Services. These files allow Oracle9iAS Web Services to supply a Web Service client with the WSDL or the client-side proxies that a client-side developer can use to build an application that uses a Web Service.

When you do not want to use the Oracle9iAS Web Services generated WSDL file or client-side proxies and you want to supply your own versions of these files, perform the following steps:

  1. Manually create either the WSDL file or the client-side proxy Jar file, or both files for your service.

  2. Name the supplied WSDL file or client-side proxy Jar file and place it in the appropriate location. The WSDL file must have a .wsdl extension. The client-side proxy Jar must have an _proxy.jar extension.The extension is placed after the service name.

    For example, 

    simpleservice.wsdl
simpleservice_proxy.jar
  3. Add the manually created WSDL file or client-side Jar file to the .war file that contains the service implementation. There are several choices for adding the files to the .war file:

Preparing and Deploying Java Class Based Web Services

To deploy a Java class as a Web Service you need to assemble a J2EE .ear file that includes the deployment descriptors for the Oracle9iAS Web Services Servlet and the Java class that supplies the Java implementation. A Web Service implemented using a Java class includes a .war file that provides configuration information for the Web Services Servlet running under Oracle9iAS Containers for J2EE (OC4J). This section describes the procedures you use to assemble the .ear file that contains a Java class to run as a Web Service.

This section covers the following topics:

The Oracle9iAS Web Services assembly tool, WebServicesAssembler, assists in assembling Oracle9iAS Web Services. The Web Services assembly tool takes a configuration file which describes the location of the Java class and interface files and produces a J2EE .ear file that can be deployed under Oracle9iAS Web Services. This section describes how to assemble Oracle9iAS Web Services implemented as Java classes manually, without using WebServicesAssembler.

See Also:

"Running the Web Services Assembly Tool"

Modifying web.xml to Support Java Web Services

To use a Java class as a Web Service, you need to add a <servlet> entry and a corresponding <servlet-mapping> entry in the web.xml file for each Java class that is deployed as a Web Service. The resulting web.xml file is assembled as part of a J2EE .war file that is included in the .ear file that defines the Web Service.

To modify web.xml to support Web Services implemented as Java classes, perform the following steps:

Configure the servlet Tag in web.xml for Java Class Web Services

To add Web Services based on Java classes you need to modify the <servlet> tag in the web.xml file. This supports using the Oracle9iAS Web Services Servlet to access the Java implementation for the Web Service. Table 3-1 describes the <servlet> tag and the values to include in the tag to add a Web Service based on a Java class.

Note:

It is the job of the Web Services developer to make the design decision to implement a stateful or stateless Web Service. When packaging Web Services, stateless and stateful Web Services are handled slightly differently. The <servlet> entry in web.xml must contain a different value for the <servlet-class>, depending on whether the Web Services implantation is stateful or stateless.

Table 3-1  Servlet Tags Supporting Java Class Deployment
Servlet Tag Description

<init-param>

The <init-param> tag contains a name value pair in, <param-name> <param-value>.

class-name: The Web Services Servlet definition requires at least one <param-name> with the value class-name, and a corresponding <param-value> set to the fully qualified name of the Java class used for the Web Service implementation.

session-timeout: An optional <param-name> with the value session-timeout, and a corresponding <param-value> set to an integer value in seconds specifies the timeout for the session. This optional parameter only applies for stateful Java Web Services. The default value for the session timeout for stateful Java sessions where no session timeout is specified is 60 seconds.

interface-name: An optional <param-name> with the value interface-name, and a corresponding <param-value> set to the fully qualified name of the Java interface specifies the methods to include in the Web Service. This init parameter tells the Web Service Servlet generation code which methods should be exposed on the Web Service. If the parameter interface-name is not included in the <servlet> definition, then all public methods on the class are included in the Web Service.

Note: when an interface is used the interface only supplies information to the Web Services support system. The Web Service implementation class specified for the class-name does not actually have to implement the interface.

<servlet-class>

This is always oracle.j2ee.ws.StatelessJavaRpcWebService for all stateless Java Web Services and oracle.j2ee.ws.JavaRpcWebService for all stateful Java Web Services.

<servlet-name>

Specifies the name for the Servlet that runs the Web Service.

Example 3-5 shows a sample <servlet> entry for Web Services implemented as a Java class running as a stateless Web Service. Example 3-6 shows a sample <servlet> entry for a Web Service implemented as a Java class running as a stateful Web Service.

Example 3-5 Sample Stateless <servlet> Entry for a Web Service

<servlet>
  <servlet-name>stateless java web service example</servlet-name>
  <servlet-class>oracle.j2ee.ws.StatelessJavaRpcWebService</servlet-class>
  <init-param>
    <param-name>class-name</param-name>
    <param-value>oracle.j2ee.ws_example.StatelessExampleImpl</param-value>
  </init-param>
  <init-param>
    <param-name>interface-name</param-name>
    <param-value>oracle.j2ee.ws_example.StatelessExample</param-value>
  </init-param>
</servlet>

Example 3-6 Sample Stateful <servlet> Entry for a Web Service

<servlet>
<servlet-name>stateful java web service example</servlet-name>
    <servlet-class>oracle.j2ee.ws.JavaRpcWebService</servlet-class>
    <init-param>
        <param-name>class-name</param-name>
        <param-value>oracle.j2ee.ws_example.StatefulExampleImpl</param-value>
    </init-param>
    <init-param>
        <param-name>interface-name</param-name>
        <param-value>oracle.j2ee.ws_example.StatefulExample</param-value>
    </init-param>
</servlet>

See Also:

Writing Stateless and Stateful Java Web Services

Configure the servlet-mapping Tag in web.xml for Java Class Web Services

To add Web Services based on Java classes, you need to modify the <servlet-mapping> tag in the web.xml file. This tag specifies the URL for the Servlet that implements a Web Service.

Example 3-7 shows sample <servlet-mapping> entries corresponding to the servlet entries shown in Example 3-5 and Example 3-6.

Example 3-7 Sample <servlet-mapping> Entries for Web Services

<servlet-mapping>
     <servlet-name>stateful java web service example</servlet-name>
     <url-pattern>/statefulTest</url-pattern>
</servlet-mapping>

<servlet-mapping>
     <servlet-name>stateless java web service example</servlet-name>
     <url-pattern>/statelessTest</url-pattern>
</servlet-mapping>

Preparing a .war File for Java Class Web Services

Web Services implemented with Java classes use a standard .war file to define J2EE Servlet configuration and deployment information. After modifying the web.xml file, add the implementation classes and any required support classes or Jar files either under WEB-INF/classes, or under WEB-INF/lib (or in a classpath location available to OC4J).

Note:

All the classes that are required for a Web Service implementation must conform to the standard J2EE class loading norms. Thus, the implementation classes and support classes must either be in a .war or .ear file, or they must be available in the OC4J classpath.

Preparing the .ear File for Java Class Web Services

To add Web Services based on Java classes, you need to include an application.xml file and package the application.xml and .war file containing the Java classes into a J2EE .ear file.

Deploying Java Class Based Web Services

After creating the .ear file containing Java classes and the Web Services Servlet deployment descriptors, you can deploy the Web Service as you would any standard J2EE application stored in an .ear file (to run under OC4J).

See Also:

Oracle9iAS Containers for J2EE User's Guide in the Oracle9iAS Documentation Library.

Serializing and Encoding Parameters and Results for Web Services

Parameters and results sent between Web Service clients and a Web Service implementation go through the following steps:

  1. Parameters are serialized and encoded in XML when sent from the Web Service client.

  2. Parameters are deserialized and decoded from XML when the Web Service receives a request on the server side.

  3. Parameters or results are serialized and encoded in XML when a request is returned from a Web Service to a Web Service client.

  4. Parameters or results must be deserialized and decoded from XML when the Web Service client receives a reply.

Oracle9iAS Web Services supports a prepackaged implementation for handling these four steps for serialization and encoding, and deserialization and decoding. The prepackaged mechanism makes the four serialization and encoding steps transparent both for the Web Services client-side application, and for the Java service writer that is implementing a Web Service. Using the prepackaged mechanism, Oracle9iAS Web Services supports the following encoding mechanisms:

Go to previous page Go to next page
Oracle
Copyright © 2002 Oracle Corporation.
All Rights Reserved.
Go To Documentation Library
Home		 Go To Product List
Solution Area		 Go To Table Of Contents
Contents		 Go To Index
Index