13 Using SOAP with the Java XDK

Prerequisites

This chapter assumes that you have working knowledge of the following technologies:

• HTTP. SOAP is independent of any transport protocol, but HTTP is the most commonly used.

• XML Namespaces. Namespaces are a mechanism for differentiating element and attribute names.

If you are unfamiliar with these technologies or need to refresh your knowledge, you can consult the XML resources in "Related Documents" of the preface.

Standards and Specifications

Oracle Database 10g Release 2 implements SOAP 1.1, which is defined in a W3C Note. SOAP 1.2 is a W3C Recommendation. You can find the SOAP specifications at the following URLs:

• http://www.w3.org/TR/2000/NOTE-SOAP-20000508/ for the SOAP 1.1 W3C Note

• http://www.w3.org/TR/soap12-part1/ for the SOAP 1.2 W3C Recommendation

The Universal Description Discovery & Integration (UDDI) standard defines services supporting the description and discovery of data relating to Web services. You can find the UDDI Version 3 specification at the following URL:

http://uddi.org/pubs/uddi_v3.htm

Web Services Description Language (WSDL) is an XML format for describing network services. You can find the WSDL specifications at the following locations:

• http://www.w3.org/TR/wsdl20 for the WSDL 2.0 W3C Working Draft

• http://www.w3.org/TR/wsdl for the WSDL 1.1 W3C Note

Oracle Database SOAP is based on the Apache SOAP 2.3.1 implementation. The Apache SOAP 2.3.1 documentation is available at the following URL:

http://xml.apache.org/soap/docs/index.html

Subpackages in oracle.soap

Table 13-1 describes the subpackages in the oracle.soap package. Refer to Oracle Database XML Java API Reference for the JavaDoc.

Subpackages in org.apache.soap

Table 13-2 describes the subpackages in the org.apache.soap package. Refer to Oracle Database XML Java API Reference for the JavaDoc.

Using SOAP Providers

SOAP application developers provide SOAP services. SOAP services, including Java services, represent user-written applications provided to remote SOAP clients. Developers make these services available by using the supplied default Java class provider or custom providers.

The oracle.soap.server.Provider interface enables the SOAP server to uniformly invoke service methods regardless of the type of provider: Java class, stored procedure, or some other provider type. There is one Provider interface implementation for each type of service provider that encapsulates all provider-specific information. The Provider interface makes SOAP implementation easily extensible to support new types of service providers.

Oracle Database SOAP includes a service deployment administration client that runs as a service to manage SOAP services. SOAP services, including Java services, represent user-written applications that are provided to remote SOAP clients.

Using SOAP Transports

Oracle Database SOAP supports the following transport protocols:

• HTTP

  This protocol is the basic SOAP transport. The Oracle Database SOAP request handler servlet manages HTTP requests and supplies responses directly over HTTP.

• HTTPS

  The Oracle Database SOAP request handler servlet manages HTTPS requests and supplies responses, with different security levels supported.

Using SOAP Handlers

A SOAP handler intercepts SOAP messages to perform pre- or post-processing as indicated by the SOAP request or response. You can use handlers on the client or server and can add features such as security, error handling, and so on. All SOAP handlers are scripts that live in the user.soap.handlers package namespace.

A SOAP service remote procedure call (RPC) request and response sequence includes the steps:

1. A SOAP client writes a request for service in a conforming XML document, using either an editor or the Oracle Database SOAP client API.

2. The client sends the document to a SOAP Request Handler running as a servlet on a Web server.

3. The Web Server dispatches the message as a service request to an appropriate server-side application providing the requested service.

4. The application must verify that the message contains supported parts. The response from the service is returned to the SOAP Request Handler servlet and then to the caller using the SOAP payload format.

Using the SOAP Request Handler

Oracle Database also supplies the SOAP Request Handler, which is a Java servlet that performs the following actions:

1. Receives SOAP requests

2. Looks up the appropriate service provider

3. Handles the service provider that invokes the requested method (service)

4. Returns the SOAP response, if any

The Oracle Database SOAP Request Handler uses an XML configuration file to set required servlet parameters. By default, this file is named soap.xml and is located in the soap.war file. The WAR file is located in the soap.ear file in the directory $ORACLE_HOME/oc4j/soap/webapps.

The XML namespace for the soap.xml file is the following:

http://xmlns.oracle.com/soap/2001/04/config 

Oracle Database SOAP and IDAP

IDAP is an XML-based specification to perform AQ operations. SOAP defines a generic mechanism to invoke a service. IDAP defines these mechanisms to perform AQ operations.

IDAP has the following key properties not defined by SOAP:

• Transactional behavior

  You can perform AQ operations in a transactional manner. Your transaction can span multiple IDAP requests.

• Security

  The IDAP operations can be performed only by authorized and authenticated users.

• Character set transformations

  Transformations are an important requirement for any communication. The computer used by an Internet client may have different character set ID from the server computer.

• Extensible AQ Servlet for AQ Internet operations

  The AQ servlet performing AQ operations is extensible. You can specify time-out, connection pooling, TAF, apply XML stylesheets, perform post AQ and pre-AQ database operations in the AQ Servlet.

There is no difference between SOAP and IDAP access to AQ except the line specifying the namespace for the envelope.

For IDAP the line specifying the namespace is as follows:

<Envelope xmlns="http://ns.oracle.com/AQ/schemas/envelope">

For SOAP the line specifying the namespace is as follows:

<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">

Oracle Database SOAP Security Features

Oracle Database SOAP uses the security capabilities in the transport to support secure access and to support other security features. For example, using HTTPS, Oracle Database SOAP provides confidentiality, authentication, and integrity over the Secure Sockets Layer (SSL). Other security features such as logging and authorization are provided by the service provider.