11
Using XDK and SOAP

This chapter contains the following sections:

What Is SOAP?

The term Web services is used for the functionality made available by an entity over the Web. It is an application that uses XML standards and is published, located and executed through the Web.

The Simple Object Access Protocol (SOAP) is a protocol for sending and receiving requests and responses across the Internet. Because it is based on XML and simple transport protocols such as HTTP, it is not blocked by firewalls and is very easy to use. SOAP is independent of operating system, independent of implementation language, and independent of any single object model.

SOAP supports remote procedure calls. Its messages are only of the three types:

A request for a service, including input parameters
A response to the requested service, including return value and output parameters
A fault containing error codes and information

SOAP messages consist of:

an envelope that contains the message, defines how to process the message, who should process the message, and whether processing is optional or mandatory.
encoding rules that describe the data types for the application. These rules define a serialization mechanism that converts the application data types to XML and XML to data types.
remote procedure call definitions

SOAP 1.1 specification is a W3C note. (The W3C XML Protocol Working Group has been formed to create a standard that will supersede SOAP.)

SOAP is transport protocol-independent and operating system-independent. It provides the standard XML message format for all applications. SOAP uses the W3C XML Schema standard of the World Wide Web Consortium (W3C).

See Also:

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

A SOAP client writes a request for service in a conforming XML document, using either an editor or the Oracle SOAP client API.
The client sends the document to a SOAP Request Handler running as a servlet on a Web server.
The Web Server dispatches the message as a service request to an appropriate server-side application providing the requested service.
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.

What Are UDDI and WSDL?

The Universal Description, Discovery and Integration (UDDI) specification provides a platform-independent framework using XML to describe services, discover businesses, and integrate business services on the Internet. The UDDI business registry is the public database where companies are registered. The UDDI business registration is an XML file with three sections:

white pages that include address, contact, and known identifiers
yellow pages include industrial categorization
green pages containing the technical information about exposed services

The Web Services Description Language (WSDL) is a general purpose XML language for describing the interface, protocol bindings, and deployment details of Web services. WSDL provides a method of describing the abstract interface and arbitrary network services. A WSDL service is registered or embedded in the UDDI registry.

The stack of protocols used in Web services is summarized in the following table:

Protocol Stack
Universal Service Interoperability Protocols (WSDL, and so on.)
Universal Description, Discovery Integration (UDDI)
Simple Object Access Protocol (SOAP)
XML, XML Schema
Internet Protocols (HTTP, HTTPS, TCP/IP)

What Is Oracle SOAP?

Oracle SOAP is an implementation of the Simple Object Access Protocol. Oracle SOAP is based on the SOAP open source implementation developed by the Apache Software Foundation.

How Does SOAP Work?

Consider this example: a GetLastTradePrice SOAP request is sent to a StockQuote service. The request takes a string parameter, the company stock symbol, and returns a float in the SOAP response. The XML document represents the SOAP message. The SOAP envelope element is the top element of the XML document. XML namespaces are used to clarify SOAP identifiers from application-specific identifiers. The following example uses HTTP as the transport protocol. The rules governing XML payload format in SOAP are independent of the fact that the payload is carried in HTTP. The SOAP request message embedded in the HTTP request is:

POST /StockQuote HTTP/1.1
Host: www.stockquoteserver.com
Content-Type: text/xml; charset="utf-8"
Content-Length: nnnn
SOAPAction: "Some-URI"
<SOAP-ENV:Envelope  xmlns:SOAP-   ENV="http://schemas.xmlsoap.org/soap/
envelope/"  SOAP-
ENV:encodingStyle="http://schemas.xnlsoap.org/soap/encoding/">
<SOAP-ENV:Body>
<m:GetLastTradePrice xmlns:m="Some-URI">
<symbol>ORCL</symbol>
<m:GetLastTradePrice>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Here is the response HTTP message:

HTTP/1.1 200 OK
Content-Type: text/xml; charset="utf-8"
Content-Length: nnnn

<SOAP-ENV:Envelope  xmlns:SOAP- 
ENV=http://schemas.xmlsoap.org/soap//envelope/ SOAP-
ENV:encodingStyle="http://schemas.xnlsoap.org/soap/encoding/"/>
<SOAP-ENV:Body>
<m:GetLastTradePriceResponse xmlns:m="Some-URI">
<Price>34.5</Price>
</m:GetLastTradePriceResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

What Is a SOAP Client?

A SOAP client application represents a user-written application that makes SOAP requests. The SOAP client has these capabilities:

Gathers all parameters that are needed to invoke a service.
Creates a SOAP service request message. This is an XML message that is built according to the SOAP protocol and that contains all the values of all input parameters encoded in XML. This process is called serialization.
Submits the request to a SOAP server using some transport protocol that is supported by the SOAP server.
Receives a SOAP response message.
Determines the success or failure of the request by handling the SOAP Fault element.
Converts the returned parameter from XML to native data type. This process is called deserialization.
Uses the result as needed.

SOAP Client API

SOAP clients generate the XML documents that compose a request for a SOAP service and handle the SOAP response. Oracle SOAP processes requests from any client that sends a valid SOAP request. To facilitate client development, Oracle SOAP includes a SOAP client API that provides a generic way to invoke a SOAP service.

The SOAP client API supports a synchronous invocation model for requests and responses. The SOAP client API makes it easier for you to write a Java client application to make a SOAP request. The SOAP client API encapsulates the creation of the SOAP request and the details of sending the request over the underlying transport protocol. The SOAP client API also supports a pluggable transport, allowing the client to easily change the transport (available transports include HTTP and HTTPS).

What Is a SOAP Server?

A SOAP server has the following capabilities:

The server receives the service request.
The server parses the XML request and then decides to execute the message or reject it.
If the message is executed, the server determines if the requested service exists.
The server converts all input parameters from XML into data types that the service understands.
The server invokes the service.
The return parameter is converted to XML and a SOAP response message is generated.
The response message is sent back to the caller.

Oracle SOAP Security Features

Oracle SOAP uses the security capabilities in the transport to support secure access and to support other security features. For example, using HTTPS, Oracle 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.

SOAP Transports

SOAP transports are the protocols that carry SOAP messages. Oracle SOAP supports the following transports:

HTTP: This protocol is the basic SOAP transport. The Oracle SOAP Request Handler Servlet manages HTTP requests and supplies responses directly over HTTP.This protocol is becoming a standard because of its popularity.
HTTPS: The Oracle SOAP Request Handler Servlet manages HTTPS requests and supplies responses, with different security levels supported.

Administrative Clients

SOAP administrative clients include the Service Manager and the Provider Manager. These administrative clients are services that support dynamic deployment of new services and new providers.

SOAP Request Handler

The SOAP Request Handler is a Java servlet that receives SOAP requests, looks up the appropriate service provider, handles the service provider that invokes the requested method (service), and returns the SOAP response, if any.

SOAP Provider Interface and Providers

Oracle SOAP includes a provider implementation for Java classes. Other providers can be added.

Provider Interface

The provider interface allows 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, and it encapsulates all provider-specific information. The provider interface makes SOAP implementation easily extensible to support new types of service providers.

Provider Deployment Administration

Oracle SOAP provides the provider deployment administration client to manage provider deployment information.

SOAP Services

SOAP application developers provide SOAP services. These services are made available using the supplied default Java class provider or custom providers. Oracle SOAP includes a service deployment administration client that runs as a service to manage services. SOAP services, including Java services, represent user-written applications that are provided to remote SOAP clients.

JDeveloper Support for SOAP

Oracle9i JDeveloper has WSDL, SOAP, and UDDI support.

See the Developer's Guides

Here's how to find the Oracle9iAS SOAP Developer's Guide, Release 1 (v1.0.2.2), May 2001, PN A90297-01 online:

1. Open http://otn.oracle.com/docs/products/ias/content.html

2. Open the Generic Documentation Library for 1.0.2.2.x.

3. Click on the Integrate Users, Applications, and Businesses link.