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

• Writing Java Class Based Web Services

• Preparing and Deploying Java Class Based Web Services

• Serializing and Encoding Parameters and Results for Web Services

Using Oracle9iAS Web Services With Java Classes

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 a Web Service client, run the Java method that implements the Web Service and returns results back to Web Services clients.

See Also: Chapter 2, "Oracle9iAS Web Services" Chapter 4, "Developing and Deploying EJB Web Services" Chapter 5, "Developing and Deploying Stored Procedure Web Services" Chapter 8, "Building Clients that Use Web Services"

Writing Java Class Based Web Services

Writing Java class based Web Services involves building a Java class that includes one or more methods. When a Web Services client makes a service request, Oracle9iAS Web Services invokes a Web Services Servlet that runs the method that implements the 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/webservices/demo/basic/java_services on UNIX or in %ORACLE_HOME%\webservices\demo\basic\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, as follows:

• For a stateful Java implementation, Oracle9iAS Web Services uses 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

• Defining an Interface for Explicit Method Exposure

• Writing a WSDL File (Optional)

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. In the expanded .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 StatefulExampleImpl.

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

package oracle.j2ee.ws_example;

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

package oracle.j2ee.ws_example;

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. Example 3-1 shows the public constructor StatelessExampleImpl() and Example 3-2 shows StatefulExampleImpl().

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 to view the logs of Servlet errors for a 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 3-1 lists the supported types for parameters and return values for Java methods that implement Web Services.

Note: See Table 3-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

package oracle.j2ee.ws_example;

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

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

package oracle.j2ee.ws_example;

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.

Note: 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 3-1 lists the supported types for parameters and return values for Java methods that implement Web Services.

   See Also: "Using Supported Data Types for Java Web Services"

Writing a WSDL File (Optional)

The WebServicesAssembler supports the <wsdl-gen> and <proxy-gen> tags to allow a Web Service developer to generate WSDL files and client-side proxy files. You can use these tags to control whether the WSDL file and the client-side proxy are generated. Using these tags you can also specify that the generated WSDL file or a WSDL file that you write is packaged with the Web Service J2EE .ear.

A client-side developer either uses the WSDL file that is obtained from a deployed Web Service, or the client-side proxy that is generated from the WSDL to build an application that uses the Web Service.

See Also: "Generating WSDL Files and Client Side Proxies"

Using Supported Data Types for Java Web Services

Table 3-1 lists the supported data types for parameters and return values for Oracle9iAS Web Services.

Table 3-1  Web Services Supported Data Types

Primitive Type	Object Type
Boolean	java.lang.Boolean
byte	java.lang.Byte
double	java.lang.Double
float	java.lang.Float
int	java.lang.Integer
long	java.lang.Long
short	java.lang.Short
string	java.lang.String
	java.util.Date
	org.w3c.dom.Element
	org.w3c.dom.Document
	org.w3c.dom.DocumentFragment
	Java Beans (whose property types are listed in this table or are another supported Java Bean)
	Single-dimensional arrays of types listed in this table.

Note: Oracle9iAS Web Services does not support Element[], (arrays of org.w3c.dom.Element).

A Bean, for purposes of Web Services, is any Java class which conforms to the following restrictions:

• It must have a constructor taking no arguments.

• It must expose all interesting state through properties.

• It must not matter what order the accessors for the properties, for example, the setX or getX methods, are in.

Oracle9iAS Web Services allows Beans to be returned or passed in as arguments to J2EE Web Service methods, as long as the Bean only consists of property types that are listed in Table 3-1 or are another supported Java Bean.

When Java Beans are used as parameters to Oracle9iAS Web Services, the client-side code should use the generated Bean included with the downloaded client-side proxy. This is because the generated client-side proxy code translates Simple Object Access Protocol (SOAP) structures to and from Java Beans by translating SOAP structure namespaces to and from fully qualified Bean class names. If a Bean with the specified name does not exist in the specified package, the generated client code will fail.

However, there is no special requirement for clients using Web Services Description Language (WSDL) to form calls to Oracle9iAS Web Services, rather than the client-side proxy. The generated WSDL document describes SOAP structures in a standard way. Application development environments, such as JDeveloper, which work directly from WSDL documents can correctly call Oracle9iAS Web Services with Java Beans as parameters.

Note: When Web Service proxy classes and WSDL are generated, all Java primitive types in the service implementation on the server-side are mapped to Object types in the proxy code or in the WSDL. For example, when the Web Service implementation includes parameters of primitive Java type int, the equivalent parameter in the proxy is of type java.lang.Integer. This mapping occurs for all primitive types.

See Also: Chapter 8, "Building Clients that Use Web Services"

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 includes the Java class that supplies the Java implementation. This section describes how to use the Oracle9iAS Web Services tool, WebServicesAssembler. WebServicesAssembler takes an XML configuration file that describes the Java Class Web Service and produces a J2EE .ear file that can be deployed under Oracle9iAS Web Services.

This section contains the following topics.

• Creating a Configuration File to Assemble Java Class Web Services

• Running WebServicesAssembler To Prepare Java Class Web Services

Creating a Configuration File to Assemble Java Class Web Services

The Oracle9iAS Web Services assembly tool, WebServicesAssembler, assists in assembling Oracle9iAS Web Services. This section describes how to create a configuration file to use with Java Class Web Services.

Create a WebServicesAssembler configuration file by adding the following:

• Adding Web Service Top Level Tags

• Adding Java Stateless Service Tags

• Adding Java Stateful Service Tags

• Adding WSDL and Client-Side Proxy Generation Tags

Adding Web Service Top Level Tags

Table 3-2 describes the top level WebServicesAssembler configuration file tags. Add these tags to provide top level information describing the Java Stateless Web Service or a Java Stateful Web Service. These tags are included within a <web-service> tag in the configuration file.

Example 3-5 shows a complete config.xml file, including the top level tags.

Table 3-2  Top Level WebServicesAssembler Configuration Tags

Tag	Description
<context> context </context>	Specifies the context root of the Web Service. This tag is required.
<datasource-JNDI-name> </datasource-JNDI-name>	Specifies the datasource associated with the Web Service.
<description> description </description>	Provides a simple description of the Web Service. This tag is optional.
<destination-path> dest_path </destination-path>	Specifies the name of the generated J2EE .ear file output. The dest_path specifies the complete path for the output file. This tag is required.
<display-name> disp_name </display-name>	Specifies the Web Service display name. This tag is optional.
<option name="source-path"> path <option>	Includes a specified file in the output .ear file. Use this option to include java resources. This resource is added to the lib directory in the generated WAR component of the J2EE .ear file. The path specifies the path to the file to include.
<stateless-java-service> sub-tags </stateless-java-service>	Use this tag to add a Java Web Services that defines a stateless service. See Table 3-3 for a description of valid sub-tags.
<stateful-java-service> sub-tags </stateful-java-service>	Use this tag to add a Java Web Services that defines a stateful service. See Table 3-3 for a description of valid sub-tags.
<temporary-directory> temp_dir </temporary-directory>	Specifies a directory where the assembler can store temporary files. This tag is optional.

Adding Java Stateless Service Tags

Prepare Java Stateless Web Services using the WebServicesAssembler <stateless-java-service> tag. This tag is included within a <web-service> tag in the configuration file. Add this tag to provide information required for generating a Stateless Java Web Service.

Table 3-3 shows the <stateless-java-service> sub-tags and the <stateful-java-service> sub-tags. As noted in Table 3-3, some of the sub-tags listed only apply when using a <stateful-java-service>.

Example 3-5 shows a complete config.xml file, including <stateless-java-service>.

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.

Adding Java Stateful Service Tags

Prepare Java Stateful Web Services using the WebServicesAssembler <stateful-java-service> tag. This tag is included within a <web-service> tag in the configuration file. Add this tag to provide information required for generating a Stateful Java Web Service.

To support a clustered environment, for stateful Java Web Services with serializable java classes, the WebServicesAssembler adds a <distributable> tag in the web.xml of the Web Service's generated J2EE.ear file.

Table 3-3 shows the <stateful-java-service> sub-tags.

Example 3-5 shows a complete config.xml file, including <stateful-java-service>.

Table 3-3  Stateless and Stateful Java Service Sub-Tags

Tag	Description
<class-name> class </class-name>	Specifies the fully qualified class name for the class that supplies the Web Service implementation. This tag is required
<interface-name> interface </interface-name>	Specifies the fully qualified name of the interface that tells the Web Service Servlet generation code which methods should be exposed as Web Services. This tag is optional
<ejb-resource> ejb-resource </ejb-resource>	This is a backwards compatibility tag. See Also: the top level <option name="source-path"> tag in Table 3-2. This tag is optional
<java-resource> resource </java-resource>	This is a backwards compatibility tag. See Also: the top level <option name="source-path"> tag in Table 3-2. This tag is optional
<message-style> rpc </message-style>	Sets the message style. When defining a Java Web Service, if you include the <message-style> tag you must specify the value rpc. Valid Values: doc, rpc This tag is optional Default value: rpc (when the <message-style> tag is not supplied)
<scope> scope </scope>	Sets the scope of the session for stateful services. The <scope> tag only applies for stateful services. Use this tag only within the <stateful-java-service> tag. This tag is optional Valid Values: application, session Default Value: session
<session-timeout> value </session-timeout>	Sets the session timeout for a stateful session. The <session-timeout> tag only applies for stateful services. Use this tag only within the <stateful-java-service> tag. Specify value with an integer that defines the timeout for the session in seconds. The default value for the session timeout for stateful Java sessions where no session timeout is specified is 60 seconds. This tag is optional
<uri> URI </uri>	Specifies servlet mapping pattern for the Servlet that implements the Web Service. The path specified as the URI is appended to the <context> to specify the Web Service location. This tag is required

Example 3-5 Sample WebServicesAssembler Configuration File

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

    <!-- Specifies the web service will be stateless -->
    <stateless-java-service>
        <interface-name>oracle.j2ee.ws_example.StatelessExample</interface-name>
        <class-name>oracle.j2ee.ws_example.StatelessExampleImpl</class-name>
        <!-- Specifies the web service will be accessed in the uri named
             "statelessTest" within the servlet context. -->
        <uri>/statelessTest</uri>
        <!-- Specifies the location of Java class files are under
             ./src -->
        <java-resource>./src</java-resource>
    </stateless-java-service>

    <stateful-java-service>
        <interface-name>oracle.j2ee.ws_example.StatefulExample</interface-name>
        <class-name>oracle.j2ee.ws_example.StatefulExampleImpl</class-name>
        <!-- Specifies the web service will be accessed in the uri named
             "statefullTest" within the servlet context. -->
        <uri>/statefulTest</uri>
        <!-- Specifies the location of Java class files are under
             ./src -->
        <java-resource>./src</java-resource>
    </stateful-java-service>
</web-service>

Adding WSDL and Client-Side Proxy Generation Tags

The WebServicesAssembler supports the <wsdl-gen> and <proxy-gen> tags to allow a Web Service developer to generate WSDL files and client-side proxy files. You can use these tags to control whether the WSDL file and the client-side proxy are generated. Using these tags you can also specify that the generated WSDL file or a WSDL file that you supply is packaged with the Web Service J2EE .ear.

A client-side developer can use the WSDL file that is obtained from a deployed Web Service, or the client-side proxy that is generated from the WSDL to build an application that uses the Web Service.

See Also: "Generating WSDL Files and Client Side Proxies"

Running WebServicesAssembler To Prepare Java Class Web Services

After you create the WebServicesAssembler configuration file, you can generate a J2EE .ear file for the Web Service. The J2EE .ear file includes the Java Web Service servlet configuration information, including the file web.xml, and the Java classes and interfaces that you supply.

Run the Oracle9iAS Web Services assembly tool, WebServicesAssembler as follows:

java -jar WebServicesAssembler.jar -config config_file

Where: config_file is the configuration file that contains the <stateless-java-service> or the <stateful-java-service> tags.

See Also: "Creating a Configuration File to Assemble Java Class Web Services" "Running the Web Services Assembly Tool"

Deploying Java Class Based Web Services

After creating the J2EE .ear file containing the 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:

• Standard SOAP v.1.1 encoding: Using standard SOAP v1.1 encoding, the server side Web Services Servlet that calls the Java class implementation handles serialization and encoding internally for the types supported by Oracle9iAS Web Services. Table 3-1 lists the supported Web Services parameter and return value types when using standard SOAP v.1.1 encoding.

• Literal XML encoding. Using Literal XML encoding, a Web Service client can pass as a parameter, or a Java service can return as a result, a value that is encoded as a conforming W3C Document Object Model (DOM) org.w3c.dom.Element. When an Element passes as a parameter to a Web Service, the server side Java implementation processes the org.w3c.dom.Element. For return values sent from a Web Service, the Web Services client parses or processes the org.w3c.dom.Element.

  Note: For parameters to a Web Service or results that the Web Service generates and returns to Web Services clients, the Oracle9iAS Web Services implementation supports either the Standard SOAP encoding or Literal XML encoding but not both, for any given Web Service (Java method).

  See Also: Chapter 8, "Building Clients that Use Web Services"