13 Using SOAP with the Java XDK

This chapter contains these topics:

See Also:

Oracle Application Server Web Services Developer's Guide at http://www.oracle.com/technology/documentation for more information about OracleAS SOAP and Web Services

Introduction to SOAP

This section introduces the Simple Object Access Protocol (SOAP).


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:

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:


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

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:


See Also:

Chapter 29, "XDK Standards" for a summary of the standards supported by the XDK

Using SOAP and the Java XDK: Overview

SOAP only defines how to encode and transmit method calls and responses. To use SOAP in your business environment, you must write code that does the following:

  • Builds and sends the SOAP request from the client

  • Interprets the SOAP request on the server, invokes the specified method, builds the response message, and returns it to the client.

The SOAP specification is silent on the implementation details. That is, the language bindings are not part of the SOAP standard itself.

The SOAP implementation in the Java XDK is based on Apache SOAP 2.3.1, which is an open-source implementation of the SOAP 1.1 and SOAP Messages with Attachments specifications in Java. Most of the documentation that applies to Apache SOAP 2.3.1 also applies to OracleAS SOAP. The Apache SOAP 2.3.1 documentation is available at the following URL:


The XDK SOAP API is located in the following JAR file in your Oracle Database installation:


The JAR file contains the base packages oracle.soap and org.apache.soap. Table 13-1 and Table 13-2 provide an overview of these packages.

See Also:

Oracle Database XML Java API Reference for complete API information for Oracle Database SOAP

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.

Table 13-1 oracle.soap Subpackages

Subpackages Description
client Contains classes that talk to the XML SOAP ProviderManager and ServiceManager.
encoding.soapenc Contains serializers and deserializers for XML data using SOAP-ENC encoding style.
handlers.audit Implements the Filter interface. See "Using SOAP Handlers".




Contains classes that provide SOAP services. The oracle.soap.providers.JavaProvider class implements the Provider interface. See "Using SOAP Providers".





Contains classes and interfaces for implementing a SOAP server. For example, the SOAPServlet class in the server.http subpackage handles SOAP requests through pluggable providers. The server.impl subpackage contains classes for service and provider managers. The server.internal subpackage contains the OracleServerConstants class, which provides SOAP server constants. The server.util subpackage contains the ServerUtils class, which provides server-side utility methods.


Contains the OracleSOAPHTTPConnection class, which implements Oracle-specific transport extensions. See "Using SOAP Transports".
util.xml Contains the XmlUtils class, which creates and parses XML documents.

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.

Table 13-2 org.apache.soap Subpackages

Subpackages Description



Contains serializers and deserializers for XML data.
messaging Contains the Message class, whose instances represent one-way messages in SOAP.
rpc Contains classes for RPC messaging. The Call object is the main interface to the underlying SOAP RPC code. A Call object represents an RPC call, whereas a Response object represents an RPC response. RPCMessage is a superclass for Call and Response: work common to both Call and Response occurs here.


Contains the SOAPEventListener and SOAPFaultListener interfaces.



Contains the SOAPTransport interface, which is an abstraction of the transport layer that's carrying the SOAP messages. The http subpackage contains the SOAPHTTPConnection class, which provides HTTP get and set methods. The smtp subpackage contains the SOAPSMTPConnection class, which enables you to send and receive a SOAP envelope through SMTP and POP3.




Contains a variety of utility classes. For example, org.apache.soap.util.xml.DOM2Writer is a utility class for serializing a DOM node as XML.

Developing SOAP Applications with the Java XDK

This section contains the following topics:

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.


    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:


Tips and Techniques for Using SOAP with the Java XDK

This section contains the following topics:

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.

See Also: