2
Using Oracle SOAP with Java Services

This chapter provides an introduction to the procedures you use to write a SOAP Java service, to deploy the service, and to write a SOAP Java client that uses the service. Code examples in this chapter, use the simple clock sample supplied with the Oracle SOAP installation. Very little setup is required before you can use Oracle SOAP with Java clients. Using Oracle SOAP, you can easily make requests for SOAP services and generate replies from SOAP services.

A Java service runs on a SOAP server as part of the Oracle SOAP Java Provider. The Java service handles requests generated by a SOAP client.

This chapter covers the following topics:

• Writing a SOAP Java Service

• Deploying a SOAP Java Service

• Writing a SOAP Java Client

• SOAP Troubleshooting

Note: This chapter does not cover the SOAP message envelope, the HTTP protocol used for transport, or the XML that the Oracle SOAP Java Provider and the SOAP Request Handler Servlet pass from or to a SOAP client. Rather, the focus here is on the service request that the client generates using Java, and the return value that the service generates.

Writing a SOAP Java Service

Writing a SOAP Java service involves building a Java class that includes one or more methods that generate data used as responses to incoming calls. Normally a service is a method that can run independently of SOAP. There are very few restrictions on what actions a SOAP service can perform. At a minimum, most SOAP services generate some data or perform an action.

This section shows how to build a service that returns the current date and time. The clock service takes a SOAP request for a service and generates a response with a return value representing the date (a String).

The complete simple clock service is supplied with Oracle SOAP in the directory $SOAP_HOME/samples/simpleclock on UNIX or in %SOAP_HOME%\samples\simpleclock on Windows NT.

Developing a SOAP Java service consists of the following steps:

• Specifying a Package Name for the Service

• Defining Java Methods

• Returning a Result

Specifying a Package Name for the Service

Create a SOAP Java service by writing a class with methods that are deployed as a SOAP service. The Oracle SOAP Java Provider runs these methods in response to a request issued by the SOAP Request Handler Servlet. When looking at the simple clock service supplied with Oracle SOAP, note that the single jar file, samples.jar, contains a package, samples, that includes several samples. For the SOAP server installation the jar file is in the directory $SOAP_HOME/webapps/soap/WEB-INF/lib on UNIX or in %SOAP_HOME%\webapps\soap\WEB-INF\lib on Windows NT. For the SOAP client installation, the jar file is in the directory $SOAP_HOME/lib on UNIX or in %SOAP_HOME%\lib on Windows NT.

The class MySimpleClockService provides the simple clock service methods. If you want to place the Java service in a package, use the Java package specification to name the package. The first line of MySimpleClockService.java specifies the package name as follows:

package samples.simpleclock;

See Also: "Deploying a SOAP Java Service"

Defining Java Methods

The simple clock service is implemented with SimpleClockService, a public class. The service defines a single public method, getDate(), that supplies a date as a String. In general, a SOAP Java service defines one or more methods. As Example 2-1 shows, the SimpleClockService uses one public method, getDate().

Note: A Java implementation of a SOAP service must be a Java class that defines a public method for each SOAP method that is exposed as a SOAP service.

Example 2-1 Defining Simple Clock Service Methods

public class SimpleClockService extends Object
{
   public SimpleClockService()
   {
   }
   public static String getDate()
   {
   .
   .
   }
}

Serializing and Encoding Parameters and Results

The getDate() method returns a String value. Parameters and results sent between a client and a service go through the following steps:

1. Parameters are serialized and encoded in XML when sent from the client to a service.

2. Parameters are deserialized and decoded from XML when the SOAP Request Handler Servlet receives a service invocation request.

3. Parameters or results are serialized and encoded in XML when a request returns from the SOAP Request Handler Servlet to a SOAP client.

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

Oracle SOAP supports a prepackaged implementation for handling these four steps for serialization and encoding, and deserialization and decoding, of scalar and user-defined types. Additionally, you can implement your own serialization and encoding mechanism.

The prepackaged mechanism makes the four serialization and encoding steps easy both for SOAP client-side applications, and for implementation of SOAP Java services. Using the prepackaged mechanism, Oracle SOAP, as specified in the SOAP client, supports the following encoding mechanisms:

• Standard SOAP v.1.1 encoding: Using standard SOAP v1.1 encoding, the Java Provider handles serialization and encoding internally for supported primitive types supported by Oracle SOAP. Table 2-1 lists the primitive types. For serializing and encoding complex types and user-defined types not found in Table 2-1, the application programmer can use JavaBeans to support the supplied BeanSerializer.

• Literal XML encoding. Using Literal XML encoding, a Java client passes as a parameter, or a Java service returns a result, that is encoded as a conforming W3C Document Object Model (DOM) Element. When an Element passes as a parameter to a SOAP service, the service processes the Element. For return values sent from a SOAP service, the client parses and processes the element.

  See Also: "Setting Up a Call to Request a Service" "Serializing Java Parameters and Results Using BeanSerializer" "Writing a SOAP Service Using Literal XML Encoding"

  Table 2-1  Types Supported with SOAP Using Default Java Encoding

  Type	Type
  String	long
  int	short
  boolean	arrays
  double	bytes (byte arrays)
  float	Hashtable
  Vector	Enumeration

Returning a Result

The getDate() code segment shown in Example 2-2 gets a date and returns a String value as a response. The Oracle SOAP Java Provider receives a request from the SOAP Request Handler Servlet and calls the getDate() method. After running, getDate() returns its result to the Oracle SOAP Java Provider. The Oracle SOAP provider processes the return value and produces a SOAP envelope. Finally, the SOAP Request Handler Servlet serializes the reply and sends a response to the SOAP client. Example 2-2 shows that the Java service writer only needs to return a String for the simple date service.

Example 2-2 Generate a Date and Return Result

public static String getDate()
{
   return (new java.util.Date()).toString();
}

When an error occurs while running a Java service, the service should throw an exception, and the SOAP Request Handler Servlet then returns a SOAP fault. The exception is sent to the log file when the logger is enabled and the severity value is set to debug.

See Also: "Setting Configuration Options for Debugging"

Deploying a SOAP Java Service

To deploy a SOAP service, you need to create a service deployment descriptor file and deploy the service using the Service Manager utility.

This section covers the following topics:

• Creating a Java Service Deployment Descriptor

• Adding Service Classes to the SOAP CLASSPATH

• Using the Service Manager to Deploy and Undeploy Java Services

• Using the Service Manager to Verify or Query Java Services

Creating a Java Service Deployment Descriptor

A service deployment descriptor file is an XML file that defines configuration information for the Java service. A service deployment descriptor file defines the following information:

• The service ID

• The service provider type (for example, Java)

• The available methods

Example 2-3 shows the SimpleClock service descriptor file SimpleClockDescriptor.xml. This descriptor file is included in the samples/simpleclock directory. The service descriptor file must conform to the service descriptor schema (the schema, service.xsd, is located in the directory $SOAP_HOME/schemas on UNIX or in %SOAP_HOME%\schemas on Windows NT).

The service descriptor file identifies methods associated with the service in the isd:provider element that uses the methods attribute. The isd:java class element identifies the Java class that implements the SOAP service, and provides an indication of whether the class is static.

Example 2-3 Java Service Descriptor File for Simple Clock Service

<isd:service xmlns:isd="http://xmlns.oracle.com/soap/2001/04/deploy/service"
             id="urn:jurassic-clock"
             type="rpc" >
  <isd:provider
      id="java-provider"
      methods="getDate"
      scope="Application" >
      <isd:java class="samples.simpleclock.SimpleClockService"/>
  </isd:provider>
  <!-- includes stack trace in fault -->
  <isd:faultListener class="org.apache.soap.server.DOMFaultListener"/>
</isd:service>

Note: The service descriptor file does not define the method signature for service methods. SOAP uses reflection to determine method signatures.

Adding Service Classes to the SOAP CLASSPATH

To deploy a SOAP Java service, the class that implements the service must be available when Oracle SOAP starts. To add the class to the CLASSPATH, modify the CLASSPATH for the SOAP Request Handler Servlet. Using the standard installation, modify the file jservSoap.properties in the directory $ORACLE_HOME/Apache/Jserv/etc on UNIX or in %ORACLE_HOME%\Apache\Jserv\etc on Windows NT.

Using the Service Manager to Deploy and Undeploy Java Services

The ServiceManager is an administrative utility that deploys and undeploys SOAP services.

To deploy the simple clock service, first set the SOAP environment, then use the deploy command to deploy the SimpleClockService service. On UNIX, the command is:

cd $SOAP_HOME/bin
source clientenv.csh
cd $SOAP_HOME/samples/simpleclock
ServiceManager.sh deploy SimpleClockDescriptor.xml

For Windows NT, the command is:

cd %SOAP_HOME%\bin
clientenv.bat
cd %SOAP_HOME%\samples\simpleclock
ServiceManager.bat deploy SimpleClockDescriptor.xml

When you are ready to undeploy a service, use the undeploy command with the registered service name as an argument. On UNIX, the command is:

ServiceManager.sh undeploy urn:jurassic-clock

For Windows NT, the command is:

ServiceManager.bat undeploy urn:jurassic-clock

Using the Service Manager to Verify or Query Java Services

The ServiceManager is an administrative utility that lists and queries SOAP services. To list the available services, first set the SOAP environment, then use the list command. One UNIX, the command is:

cd $SOAP_HOME/bin
source clientenv.csh
ServiceManager.sh list

On Windows NT, the command is:

cd %SOAP_HOME%\bin
clientenv.bat
ServiceManager.bat list

To query a service and obtain the descriptor parameters set in the service deployment descriptor file, use the query command. On UNIX, the command is:

ServiceManager.sh query urn:jurassic-clock

On Windows NT, the command is:

ServiceManager.bat query urn:jurassic-clock

Writing a SOAP Java Client

After creating and deploying one or more SOAP services, client-side applications can request service invocations. The example described in this section is a SOAP client-side application that requests a date, using the simple clock service, and the method GetDate().

Developing a Java client-side SOAP application consists of the following steps:

• Specifying a Package Name Java Clients

• Importing for Java Clients

• Defining a Request

• Setting Up a Call to Request a Service

• Invoking a Call to Request a Service

• Waiting for a Response and Handling SOAP Faults

• Running a Client

• Using Security Features with a Client

Specifying a Package Name Java Clients

Use a SOAP Java service by making a SOAP request. The file MySimpleClockClient.java shows a SOAP client that makes a SOAP request. On UNIX, the directory $SOAP_HOME/samples/simpleclock contains this source file; on Windows NT, %SOAP_HOME%\samples\simpleclock.

The first line of MySimpleClockClient.java specifies the package name for the service that is added to samples.jar.

package samples.simpleclock;

Importing for Java Clients

The SOAP client-side application uses the following imports:

import org.apache.soap.rpc.Call;
import org.apache.soap.rpc.Response;
import org.apache.soap.rpc.Parameter;
import org.apache.soap.Constants;
import org.apache.soap.SOAPException;
import java.net.URL;
import java.net.MalformedURLException;
   

The org.apache.soap.rpc imports for the SOAP client-side are discussed in the following sections.

Defining a Request

The MySimpleClockClient class includes the SOAP request for the SOAP getDate Java service. Example 2-4 shows the start of the client's main() routine that processes the command line argument.

Example 2-4 SOAP Client-Side Call Main Routine

public static void main(String[] args)
{
   if (args.length == 0)
   {
     System.out.println(
       "Usage is java samples.simpleclock.MySimpleClockClient SOAP_server_url");
     System.exit(1);
   }
   else
   {
      try
      {
        URL url = new URL (args[0]);
        MySimpleClockClient soapClockClient = new MySimpleClockClient(url);
      }
      catch (MalformedURLException mue)
      {
        mue.printStackTrace();
      }
   }
}

Setting Up a Call to Request a Service

The package org.apache.soap.rpc contains the SOAP Call object. A SOAP client-side request uses a Call object to build a request for a SOAP service. After the SOAP request is created, it is invoked to enable the client API to pass the request on to a SOAP server. Example 2-5 shows the code that builds a request for a SOAP service invocation.

Example 2-5 Building a SOAP RPC Call

Call call = new Call();
call.setTargetObjectURI("urn:jurassic-clock");
call.setMethodName("getDate");
call.setEncodingStyleURI(Constants.NS_URI_SOAP_ENC);

This code performs the following functions:

• Creates the Call object.

• Sets the Call object's target URI which identifies the service.

• Sets the Call object's method name.

• Sets the Call object's encoding style.

• Defines the Call object's parameters. For this service, the Call object does not set any parameters to send with the service request.

In addition, the Call object's setTimeout() method sets the timeout, an integer representing seconds, for a SOAP call. The default Call timeout, implicitly set in this example specifies no timeout. Setting a timeout value of 0 also specifies no timeout.

Serializing and Encoding Java Parameters and Results

Example 2-5 shows the client-side method that sets the default encoding style for the service request setEncodingStyleURI. The simple clock service uses standard SOAP v1.1 encoding.

In a client-side application, the SOAP API uses the encoding style set for the call to serialize and encode any parameters that are sent to the SOAP service, unless a specific encoding style is set for the parameter. For primitive types, the SOAP Java client-side API handles serialization and encoding internally using the standard SOAP encoding. For complex Java types, not found in Table 2-1, the application programmer must supply serialization and encoding methods to the client-side API.

See Also: "Defining Java Methods Using Parameters with User-Defined Types" "Serializing Java Parameters and Results Using BeanSerializer"

Invoking a Call to Request a Service

Example 2-6 shows the Call object invoke() method that invokes the service at the specified SOAP URL. A Response object handles any response. The URL that you provide on the command line should be the URL for the SOAP Request Handler Servlet. This value depends on where SOAP is deployed. For example, the URL could be composed as follows:

http://machineName:port/soap/servlet/soaprouter

Example 2-6 Making the SOAP RPC Call Invocation

Response resp = call.invoke(url, "");

Note: The second argument to invoke(), the actionURI is empty because the Oracle SOAP Server currently does not use the argument.

Waiting for a Response and Handling SOAP Faults

During invocation, if the Call timeout is not reached, and the invoke() method returns, the Response object holds the SOAP return value or any fault generated. The return value is stored in a Parameter component of the Response object. Use the getValue() method to convert the response to a Java object. Example 2-7 shows how GetDate handles the response to either process a fault or show the date returned from the simple clock service's getDate method.

Example 2-7 SOAP Request Response and Fault Handling

 try
 {
    System.out.println("Calling urn:jurassic-clock");
    Response resp = call.invoke(url, "");
    if (!resp.generatedFault())
    {
      Parameter result = resp.getReturnValue();
      System.out.println(result.getValue());
    }
    else
    {
       System.out.println("FAULT Returned");
       System.out.println(resp.getFault().getFaultString());
    }
}
catch (SOAPException soapE)
{
  soapE.printStackTrace();
}
catch (Exception e)
{
   e.printStackTrace();
}

Running a Client

After writing a SOAP client and setting the SOAP environment, run the client as you would any Java program. On UNIX, use the following commands:

cd $SOAP_HOME/bin
source clientenv.csh
java ${JAXP} samples.simpleclock.MySimpleClockClient ${SOAP_URL}

On Windows NT, use the following commands:

cd %SOAP_HOME%\bin
clientenv.bat
java %JAXP% samples.simpleclock.MySimpleClockClient %SOAP_URL%

Using Security Features with a Client

Oracle SOAP uses the security capabilities of the underlying transport that sends SOAP messages. Oracle SOAP supports the HTTP and HTTPS protocols for sending SOAP messages. HTTP and HTTPS support the following security features:

• HTTP proxies

• HTTP authentication (basic RFC 2617)

• Proxy authentication (basic RFC 2617)

Table 2-2 lists the client-side security properties that Oracle SOAP supports.

In a SOAP client-side application, you can set the security properties shown in Table 2-2 as system properties by using the -D flag at the Java command line. You can also set security properties in the Java program by adding these properties to the system properties (use System.setProperties() to add properties).

Example 2-8 shows how Oracle SOAP allows you to override the values specified for system properties using Oracle SOAP transport specific APIs. The setProperties() method in the class OracleSOAPHTTPConnection contains set properties specifically for the HTTP connection (this class is in the package oracle.soap.transport.http).

Example 2-8 Setting Security Properties for OracleSOAPHHTTPConnection

org.apache.soap.rpc.Call call = new org.apache.soap.rpc.Call(); 
oracle.soap.transport.http.OracleSOAPHTTPConnection conn =    
(oracle.soap.transport.http.OracleSOAPHTTPConnection) call.getSOAPTransport(); 
java.util.Properties prop = new java.util.Properties(); 
// Use client code to set name-value pairs of properties in prop
.
.
.
conn.setProperties(prop);

Note: The property java.protocol.handler.pkgs must be set as a system property.

Table 2-2  SOAP HTTP Transport Security Properties

Property	Description
http.authType	Specifies the HTTP authentication type. The case of the value specified is ignored. Valid values: basic Specifying any value other than basic is the same as not setting the property.
http.password	Specifies the HTTP authentication password.
http.proxyAuthType	Specifies the proxy authentication type. The case of the value specified is ignored. Valid values: basic Specifying any value other than basic is the same as not setting the property.
http.proxyHost	Specifies the hostname or IP address of the proxy host.
http.proxyPassword	Specifies the HTTP proxy authentication password.
http.proxyPort	Specifies the proxy port. The specified value must be an integer. This property is only used when http.proxyHost is defined; otherwise this value is ignored. Default value: 80
http.proxyUsername	Specifies the HTTP proxy authentication username.
http.username	Specifies the HTTP authentication username.
java.protocol. handler.pkgs	Specifies a list of package prefixes used by java.net.URLStreamHandlerFactory. The prefixes should be separated by "|" vertical bar characters. This value should contain: oracle.net.www.protocol This is required by the Java protocol handler framework; it is not defined by Oracle SOAP. This property must be set when using HTTPS. If this property is not set using HTTPS, a java.net.MalformedURLException is thrown. Note: This property must be set as a system property. For example, set this property as shown in either of the following: java.protocol.handler.pkgs=oracle.net.www.protocol java.protocol.handler.pkgs=sun.net.www.protocol| oracle.net.www.protocol
oracle.soap. transport. allowUserInteraction	Specifies the allows user interaction parameter. The case of the value specified is ignored. When this property is set to true and either of the following are true, the user is prompted for a username and password: If any of properties http.authType, http.username, or http.password is not set, and a 401 HTTP status is returned by the HTTP server. If either of properties http.proxyAuthType, http.proxyUsername, or http.proxyPassword is not set and a 407 HTTP response is returned by the HTTP proxy. Valid values: true, false Specifying any value other than true is considered as false.
oracle. wallet.location	Specifies the location of an exported Oracle wallet or exported trustpoints. Note: The value used is not a URL but a file location, for example: /etc/ORACLE/Wallets/system1/exported_wallet (on UNIX) d:\oracle\system1\exported_wallet (on Windows NT) This property must be set when HTTPS is used with SSL authentication, server or mutual, as the transport.
oracle.wallet. password	Specifies the password of an exported wallet. Setting this property is required when HTTPS is used with client, mutual authentication as the transport.

SOAP Troubleshooting

This section lists several techniques for troubleshooting Oracle SOAP, including:

• Tunneling Using the TcpTunnelGui Command

• Setting Configuration Options for Debugging

• Using DMS to Display Runtime Information

Tunneling Using the TcpTunnelGui Command

SOAP provides the TcpTunnelGui command to display messages sent between a SOAP client and a SOAP server. TcpTunnelGui listens on a TCP port, which is different than the SOAP server, and then forwards requests to the SOAP server.

Invoke TcpTunnelGui as follows:

java org.apache.soap.util.net.TcpTunnelGui TUNNEL-PORT SOAP-HOST SOAP-PORT

Table 2-3 lists the command line options for TcpTunnelGui.

Table 2-3  TcpTunnelGui Command Arguments

Argument	Description
TUNNEL-PORT	The port that TcpTunnelGui listens to on the same host as the client
SOAP-HOST	The host of the SOAP server
SOAP-PORT	The port of the SOAP server

For example, suppose the SOAP server is running as follows,

http://system1:8080/soap/servlet/soaprouter

You would then invoke TcpTunnelGui on port 8082 with this command:

java org.apache.soap.util.net.TcpTunnelGui 8082 system1 8080

To test a client and view the SOAP traffic, you would use the following SOAP URL in the client program:

http://system1:8082/soap/servlet/soaprouter

Setting Configuration Options for Debugging

To add debugging information to the SOAP Request Handler Servlet log files, change the value of the severity option for the value debug in the file soapConfig.xml. This file is placed in the directory $SOAP_HOME/webapps/soap/WEB-INF/config on UNIX or in %SOAP_HOME%\webapps\soap\WEB-INF\config on Windows NT.

For example, the following soapConfig.xml segment shows the value to set for severity to enable debugging:

<!-- severity can be: error, status, or debug -->
<osc:logger class="oracle.soap.server.impl.ServletLogger">
    <osc:option name="severity" value="debug" />
</osc:logger>

After modifying the value attribute for the severity option element in soapConfig.xml, perform the following steps to view debug information.

1. Stop SOAP by using the stopSoapJServ command.

2. Restart SOAP by using the startSoapJServ command. You do not need to perform this step if the SOAP Request Handler Servlet is running in auto start mode.

After stopping and restarting the SOAP Request Handler Servlet, you can view debug information in the file jserv.log. The file is in the directory $ORACLE_HOME/Apache/Jserv/logs on UNIX or in
%ORACLE_HOME%\Apache\Jserv\logs on Windows NT.

See Also: "Using Auto Start Mode"

Using DMS to Display Runtime Information

Oracle SOAP is instrumented with DMS to gather information on the execution of the SOAP Request Handler Servlet, the Java Provider, and on individual services.

DMS information includes execution intervals from start to stop for the following:

• Total time spent in SOAP request and response (includes time in providers and services)

• Total time spent in the Java Provider (includes time in services)

• Total time executing services (soap/java-provider/service-URI)

To view the DMS information, go to the following site:

http://hostname:port/soap/servlet/Spy