11
Simple Object Access Protocol (SOAP) for Java

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.

SOAP is a transport protocol for sending and receiving requests and responses across the Internet. It is based on XML and HTTP. SOAP is transport protocol-independent and operating system-independent. It provides the standard XML message format for all applications. SOAP uses the XML Schema standard of the World Wide Web Consortium (W3C).

Oracle SOAP APIs are contained in these packages and classes:

• oracle.soap.server Package
• oracle.soap.transport Package
• oracle.soap.transport.http Package
• oracle.soap.util.xml Package

  See Also: http://www.w3.org/TR/SOAP/ http://xml.apache.org/soap/ Oracle9i XML Developer's Kits Guide - XDK Oracle9i Supplied Java Packages Reference

---

oracle.soap.server Package

---

Description of oracle.soap.server

Package oracle.soap.server contains the interfaces and classes that implement the API for SOAP administrative clients and the provider implementation for Java classes. These include the Service Manager and the Provider Manager. These administrative clients are services that support dynamic deployment of new services and new providers.

Table 11-1 lists the interfaces and classes that provide support for Oracle SOAP in the XDK for Java.

Table 11-1 Summary of Classes and Interfaces of oracle.soap.server  

Class/Interface	Description
Handler Interface	Defines the interface for a pluggable handler in the SOAP server.
Provider Interface	Defines the capabilities that must be supported for each type of service provider.
ProviderManager Interface	Defines the Provider Manager used by the SOAP engine to deploy providers, undeploy providers, and access provider deployment information.
ServiceManager Interface	Defines the Service Manager used by the SOAP engine to deploy services, undeploy services, and to access service deployment information.
ContainerContext Class	Defines the context of the container in which the SOAP server is running
Class Logger	Defines the capabilities that must be supported by a logger implementation; the logger is used to persistently record error and informational messages.
ProviderDeploymentDescriptor Class	Defines the deployment information for a specific provider.
RequestContext Class	Defines all of the context for a SOAP request, including information that is passed to the provider and information that the provider must set before returning.
ServiceDeploymentDescriptor Class	Defines the deployment information for a SOAP service, independent of its provider type.
UserContext Class	Defines the user context for a SOAP service request.

---

Handler Interface

---

Description of Handler

Handler defines the interface for a pluggable handler in the SOAP server. This class does not imply any policies about when the handler in invoked.

A handler implementation must:

• provide a no-args constructor
• be thread-safe

---

Syntax of Handler

oracle.soap.server.Handler

public interface Handler

---

Fields of Handler

Table 11-2 Fields of Handler  

Field	Syntax	Description
REQUEST_TYPE	public static final int REQUEST_TYPE	Handler invocation is part of request chain.
RESPONSE_TYPE	public static final int RESPONSE_TYPE	Handler invocation is part of response chain.
ERROR_TYPE	public static final int ERROR_TYPE	Handler invocation is part of error chain.

---

Methods of Handler

Table 11-3 Summary of Methods of Handler  

Method	Description
destroy()	Cleans-up handler (one time only).
getName()	Returns this handler's name.
getOptions()	Returns options that are specific to the handler implementation.
init()	Initializes handler (one-time only).
invoke()	Invokes the requested handler as part of the specified chain type.
setName()	Sets the name of the handler. This method must be called before init().
setOptions()	Sets the options for the handler for subsequent use by init.

destroy()

Description

Cleans-up handler (one time only). This method will be invoked by the SOAP server exactly once before the server shuts down. This gives the handler the opportunity to do cleanup of global state. Throws SOAPException if unable to destroy.

Syntax

public abstract void destroy();

getName()

Description

Returns this handler's name.

Syntax

public abstract String getName();

getOptions()

Description

Returns options that are specific to the handler implementation.

Syntax

public abstract Properties getOptions();

init()

Description

Initializes handler (one-time only). This method will be invoked by the SOAP server exactly once before the server makes any invocations on the handler, allowing the handler to set up any global state. It uses any options that were set previously through setOptions(). Throws SOAPException if unable to initialize the handler.

Syntax

public abstract void init( SOAPServerContext ssc);

Parameter	Description
ssc	The SOAP server context, which contains the logger for informational messages.

invoke()

Description

Invokes the requested handler as part of the specified chain type. Note that execution of a chain of request handlers or response handlers will terminate immediately if any handler throws a SOAPException. In contrast, all handlers in an error chain will be invoked, regardless of whether or not any handler throws an exception. In the case of an exception in an error handler, the exception is logged and discarded. Throws SOAPException if handler invocation failed.

Syntax

public abstract void invoke( int chainType,
                             RequestContext requestContext);

Parameter	Description
chainType	The following chainTypes are supported: Handler.REQUEST_TYPE if the handler is being invoked as part of a request chain, before the service is invoked Handler.RESPONSE_TYPE if the handler is being invoked as part of a response chain, after the service has been invoked Handler.ERROR_TYPE if the handler is being invoked as part of an error chain, in case of an error during any one of request chain, service invocation, or response chain
requestContext	The relevant request context.

setName()

Description

Sets the name of the handler. This method must be called before init().

Syntax

public abstract void setName( String name);

Parameter	Description
name	The name of the handler instance.

setOptions()

Description

Sets the options for the handler for subsequent use by init. This method must be called before init().

Syntax

public abstract void setOptions( Properties options);

Parameter	Description
options	Options that are specific to the handler implementation.

---

Provider Interface

---

Description of Provider

Provider defines the capabilities that must be supported for each type of service provider, such as Java class or stored procedure. Providers are responsible for service authorization, and parameter unmarshalling/marshalling.

Providers, aka provider instances, must be deployed to the SOAP handler. Each provider deployment must define the provider name, Java classname that implements the provider (which must be an implementation of this interface), and any number of provider-specific key-value pairs. Given the provider deployment information, the SOAP handler will interact with the providers solely through this interface.

The SOAP handler will create one instance for each deployed provider instance. It is possible to have one or more instances of each provider implementation (which is not to say that is necessarily recommended). In any event, each instance of a provider must be able to handle requests concurrently.

A provider implementation must:

• provide a no-args constructor
• be thread-safe

---

Syntax of Provider

public interface Provider

Interface oracle.soap.server.Provider

---

Methods of Provider

Table 11-4 Summary of Methods in Provider  

Method	Description
destroy()	Cleans up provider instance (one time only).
getId()	Returns this providers name, which is unique within the SOAP handler.
init()	Initializes provider instance (one time only).
invoke()	Invokes the requested method in the specified service, where the SOAP request is completely described in the request context.

destroy()

Description

Cleans up provider instance (one time only). This method will be invoked by the SOAP handler exactly once before the handler shuts down. This gives the provider the opportunity to do cleanup of provider-global state. Throws SOAPException if unable to destroy.

Syntax

public abstract void destroy();

getId()

Description

Returns this providers name, which is unique within the SOAP handler.

Syntax

public abstract String getId();

init()

Description

Initializes provider instance (one time only). This method will be invoked by the SOAP handler exactly once before the handler makes any requests to services supported by the provider, allowing the provider to set up any provider-global context. Throws SOAPException if unable to initialize and therefore unable to provide services.

Syntax

public abstract void init( ProviderDeploymentDescriptor pd,
                           SOAPServerContext ssc);

Parameter	Description
pd	The provider descriptor which contains the provider deployment information.
ssc	The SOAP server context, which contains the logger for informational messages.

invoke()

Description

Invokes the requested method in the specified service, where the SOAP request is completely described in the request context. Throws SOAPException if error during method invocation for any number of reasons, including user does not have permission, method does not exist.

Syntax

public abstract void invoke( RequestContext requestContext);

Parameter	Description
requestContext	The RequestContext that contains everything the provider needs to process the request.

---

ProviderManager Interface

---

Description of ProviderManager

Provider Manager defines the interface to manage providers. The provider manager is used by the SOAP engine to deploy providers, undeploy providers, and access provider deployment information. The provider manager may cache deployment information and is responsible to maintain the cache.

The HTTP server provides security for the provider manager. The provider manager can be configured with a URL that requests must be made to in order for the request to be accepted. If a SOAP request for the provider manager is made to any other URL, the request will be rejected. This URL should be an alias to the SOAP servlet, and HTTP security can be set to control which users can post to the URL.

---

Syntax of ProviderManager

public interface ProviderManager

Interface oracle.soap.server.ProviderManager

---

Methods of ProviderManager

Table 11-5 Summary of Methods in ProviderManager  

Method	Description
deploy()	Deploys the given provider.
destroy()	Cleans up the provider manager.
getRequiredRequestURI()	Returns the URI that provider manager requests.
init()	Initializes the provider manager.
list()	Returns an array of provider ids for all providers that have been deployed.
query()	Returns the deployment descriptor for the given provider.
setServiceManager()	Makes the service manager available to the provider manager.
undeploy()	Undeploys the given provider.

deploy()

Description

Deploys the given provider. Throws SOAPException if unable to deploy.

Syntax

public abstract void deploy(ProviderDeploymentDescriptor providerId);

Parameter	Description
providerId	The id of the provider to deploy.

destroy()

Description

Cleans up the provider manager. Throws SOAPException if unable to cleanup the provider manager.

Syntax

public abstract void destroy();

getRequiredRequestURI()

Description

Returns the URI that provider manager requests, or NULL if any URI can be used. Request must be made to in order to be accepted. Requests made to any other URI must be rejected.

Syntax

public abstract String getRequiredRequestURI();

init()

Description

Initializes the provider manager. Throws SOAPException if unable to access the deployment information.

Syntax

public abstract void init(Properties options);

Parameter	Description
options	The options required to setup access to the deployment information.

list()

Description

Returns an array of provider ids for all providers that have been deployed. Throws SOAPException if unable to list provider ids.

Syntax

public abstract String[] list();

query()

Description

Returns the deployment descriptor for the given provider. Throws SOAPException if the provider is not found.

Syntax

public abstract ProviderDeploymentDescriptor query( String providerId);

Parameter	Description
providerId	The id of the provider.

setServiceManager()

Description

Makes the service manager that is being used to manage service deployment information available to the provider manager. The provider manager may use the service manager to ensure that a provider is not undeployed as long as any services are deployed under that provider.

Syntax

public abstract void setServiceManager( ServiceManager serviceManager);

Parameter	Description
providerManager	The provider manager that is managing provider deployment information for the SOAP server.

undeploy()

Description

Undeploys the given provider, and returns its descriptor containing the deployment information for the provider that has been undeployed. Throws SOAPException if the provider is not found or failed to undeploy.

Syntax

public abstract ProviderDeploymentDescriptor undeploy( String providerId);

Parameter	Description
providerId	The id of the provider to undeploy.

---

ServiceManager Interface

---

Description of ServiceManager

Service Manager defines the interface to manage services. The Service Manager is used by the SOAP engine to deploy services, undeploy services, and to access service deployment information. The Service Manager may cache deployment information and is responsible for maintaining the cache.

The HTTP server provides security for the service manager. The service manager can be configured with a URL that requests must be made to in order for the request to be accepted. If a SOAP request for the service manager is made to any other URL, the request will be rejected. This URL should be an alias to the SOAP servlet, and HTTP security can be set to control which users can post to the specified URL.

---

Syntax of ServiceManager

public interface ServiceManager

Interface oracle.soap.server.ServiceManager

---

Methods of Servicemanager

Table 11-6 Summary of Methods in ServiceManager  

Method	Description
getRequiredRequestURI()	Returns the URI that service manager requests.
deploy()	Deploys the given service.
destroy()	Cleans up the service manager.
init()	Initializes the service manager.
list()	Returns an array of service ids for all services that have been deployed, regardless of the provider.
query()	Returns the deployment descriptor for the given service.
undeploy()	Undeploys the given service, and returns its descriptor.

getRequiredRequestURI()

Description

Returns the URI that service manager requests, or NUKLL if any URI can be used. Requests must be made to in order to be accepted. Requests made to any other URI must be rejected.

Syntax

public abstract String getRequiredRequestURI();

deploy()

Description

Deploys the given service. Throws SOAPException if unable to deploy.

Syntax

public abstract void deploy(ServiceDeploymentDescriptor sd);

Parameter	Description
sd	The service descriptor for the service to deploy.

destroy()

Description

Cleans up the service manager. Throws SOAPException if unable to cleanup the service manager.

Syntax

public abstract void destroy();

init()

Description

Initializes the service manager. The implementation should be able to handle a null value for the provider manager. Throws SOAPException if unable to access the service deployment information.

Syntax

public abstract void init( Properties options,
                           ProviderManager providerManager);

Parameter	Description
options	The options required to setup access to the service deployment information.
providerManager	The provider manager that is managing provider deployment information for the SOAP server, or null if the provider manager is not supplied. The service manager may want to use the provider manager to confirm the existence of the provider when a new service is deployed.

list()

Description

Returns an array of service ids for all services that have been deployed, regardless of the provider. Throws SOAPException if unable to list service ids.

Syntax

public abstract String[] list();

query()

Description

Returns the deployment descriptor for the given service. Throws SOAPException if the service is not found.

Syntax

public abstract ServiceDeploymentDescriptor query( String serviceId);

Parameter	Description
serviceId	The unique URI of the service.

undeploy()

Description

Undeploys the given service, and returns its descriptor. Throws SOAPException if the service is not found or failed to undeploy.

Syntax

public abstract ServiceDeploymentDescriptor undeploy( String serviceId);

Parameter	Description
serviceId	The URI of the service to undeploy.

---

ContainerContext Class

---

Description of ContainerContext

ContainerContext class defines the context of the container in which the SOAP server is running. The actual content depends on the environment in which the server is running, such as in a servlet engine. This class should contain only container-specific content.

---

Syntax of ContainerContext

public class ContainerContext extends Object

java.lang.Object
   |
   +----oracle.soap.server.ContainerContext

---

Fields of ContainerContext

Table 11-7 Fields of ContainerContext  

Field	Syntax	Description
SERVLET_CONTAINER	public static final String SERVLET_CONTAINER	The value for a servlet container type.

---

Methods of ContainerContext

Table 11-8 Summary of Methods of ContainerContext  

Method	Description
ContainerContext()	Class constructor.
getAttribute()	Returns the attribute with the given name.
getAttributeNames()	Returns an Enumeration containing the attribute names available within this SOAP context.
getContainerType()	Returns the container type in which the SOAP server is running.
getHttpServlet()	Returns the HTTP servlet that is processing the SOAP request if the container type is SERVLET_CONTAINER.
removeAttribute()	Removes the attribute with the given name from the context.
setAttribute()	Binds an object to a given attribute name in this SOAP context.
setContainerType()	Sets the container type.
setHttpServlet()	Sets the HTTP servlet for a SOAP server running in a SERVLET_CONTAINER type of container.

ContainerContext()

Description

Class constructor.

Syntax

public ContainerContext();

getAttribute()

Description

Returns the attribute with the given name, or NULL if there is no attribute by that name.

Syntax

public Object getAttribute( String name);

Parameter	Description
name	A String specifying the name of the attribute.

getAttributeNames()

Description

Returns an Enumeration containing the attribute names available within this SOAP context.

Syntax

public Enumeration getAttributeNames();

getContainerType()

Description

Returns the container type in which the SOAP server is running.

Syntax

public String getContainerType();

getHttpServlet()

Description

Returns the HTTP servlet that is processing the SOAP request if the container type is SERVLET_CONTAINER, or NULL if the servlet attribute is not set.

Syntax

public HttpServlet getHttpServlet();

removeAttribute()

Description

Removes the attribute with the given name from the context. After removal, subsequent calls to getAttribute(java.lang.String) to retrieve the attribute's value will return NULL.

Syntax

public void removeAttribute( String name);

Parameter	Description
name	A String specifying the name of the attribute to be removed.

setAttribute()

Description

Binds an object to a given attribute name in this SOAP context. If the name specified is already used for an attribute, this method will remove the old attribute and bind the name to the new attribute. Neither the name nor the object may be NULL.

Syntax

public void setAttribute( String name,
                          Object object);

Parameter	Description
name	A non-null String specifying the name of the attribute.
object	An non-null Object representing the attribute to be bound.

setContainerType()

Description

Sets the container type.

Syntax

public void setContainerType( String containerType);

Parameter	Description
containerType	The type of container in which the SOAP server is running.

setHttpServlet()

Description

Sets the HTTP servlet for a SOAP server running in a SERVLET_CONTAINER type of container.

Syntax

public void setHttpServlet(HttpServlet servlet);

Parameter	Description
servlet	The HttpServlet that is processing the SOAP request.

---

Class Logger

---

Description of Logger

Logger defines the capabilities that must be supported by a logger implementation. The logger is used to persistently record error and informational messages.

Each log request specifies the severity, and the information should be logged iff the severity is at least as high as the specified severity.

The order of severity in increasing order is:

• SEVERITY_ERROR
• SEVERITY_STATUS
• SEVERITY_DEBUG

For example, if the severity is set to SEVERITY_STATUS, any log request with severity of either SEVERITY_STATUS or SEVERITY_ERROR will be logged.

---

Syntax of Logger

Class oracle.soap.server.Logger

public abstract class Logger extends Object

java.lang.Object
   |
   +----oracle.soap.server.Logger

---

Fields of Logger

Table 11-9 Fields of Logger  

Field	Syntax	Description
SEVERITY_ERROR	public static final int SEVERITY_ERROR	Severity level for logging error messages.
SEVERITY_STATUS	public static final int SEVERITY_STATUS	Severity level for logging status messages.
SEVERITY_DEBUG	public static final int SEVERITY_DEBUG	Severity level for logging information for debugging purposes.
SEVERITY_INVALID	protected static final int SEVERITY_INVALID	Indicates an invalid severity setting.
SEVERITY_NAMES	public static String SEVERITY_NAMES[]	Printable names for each severity level, indexed by severity.
DEFAULT_SEVERITY	public static final int DEFAULT_SEVERITY	The default severity level setting for determining which log requests are actually logged. The default is SEVERITY_STATUS.
OPTION_SEVERITY	public static final String OPTION_SEVERITY	Configuration option that specifies the severity for the logger.
m_severity	protected int m_severity	The logger's severity setting.

---

Methods of Logger

Table 11-10 Summary of Methods of Logger  

Method	Description
Logger()	Class constructor.
getSeverity()	Returns the current severity setting for the logger.
getSeverityName()	Returns the severity name associated with the given severity.
getSeverityValue()	Returns the severity value associated with the given severity name.
init()	Initializes of the logger (one-time only) with its configuration parameters.
isLoggable()	Determines if a message would be logged at the given severity level.
log()	Logs messages.
setSeverity()	Sets the current severity.

Logger()

Description

Class constructor.

Syntax

public Logger();

getSeverity()

Description

Returns the current severity setting for the logger.

Syntax

public int getSeverity();

getSeverityName()

Description

Returns the severity name associated with the given severity.

Syntax

protected final String getSeverityName( int severity);

Parameter	Description
severity	The severity level (SEVERITY_xxx).

getSeverityValue()

Description

Returns the severity value associated with the given severity name.

Syntax

protected final int getSeverityValue( String severityName);

Parameter	Description
severityName	The name of the severity level, such as error.

init()

Description

Initializes of the logger (one-time only) with its configuration parameters. Throws SOAPException if unable to initialize the logger.

Syntax

public abstract void init( Properties options,
                           ContainerContext context);

Parameter	Description
options	The configuration options for the logger.
context	The context of the container in which the SOAP server is running, which includes information that may be used by the logger.

isLoggable()

Description

Determines if a message would be logged at the given severity level. Returns TRUE if a message would be logged at the given severity level, FALSE otherwise.

Syntax

public boolean isLoggable( int severity);

Parameter	Description
severity	The severity level to check.

log()

Description

Logs messages. The options are described in the following table.

Syntax	Description
public abstract void log( String msg, int severity);	Logs the given message at the given severity.
public abstract void log( String msg, Throwable t, int severity);	Logs the given message and exception at the given severity.
public abstract void log( Throwable t, int severity);	Logs the given exception at the given severity.

Parameter	Description
msg	The message to log.
severity	The severity at which to log the information.
t	The throwable exception to log.

setSeverity()

Description

Sets the current severity.

Syntax

public void setSeverity(int severity);

Parameter	Description
severity	The new severity setting for the logger.

---

ProviderDeploymentDescriptor Class

---

Description of ProviderDeploymentDescriptor

ProviderDeploymentDescriptor defines the deployment information for a specific provider. Different providers may be deployed using the same implementation and be distinguished only by their provider descriptor.

---

Syntax of ProviderDeploymentDescriptor

public final class ProviderDeploymentDescriptor extends Object implements 
Serializable

java.lang.Object
   |
   +----oracle.soap.server.ProviderDeploymentDescriptor

---

Methods of ProviderDeploymentDescriptor

Table 11-11 Summary of Methods of ProviderDeploymentDescriptor  

Method	Descriptor
ProviderDeploymentDescriptor()	Constructs a new instance of a provider descriptor.
fromXML()	Builds and returns a provider descriptor from the given XML document.
getClassname()	Returns the name of the class that implements this provider.
getId()	Returns the unique id for this provider.
getOptions()	Returns the provider-specific options
getProviderType()	Returns the provider type.
setClassname()	Sets the name of the class that implements this provider.
setId()	Sets the provider id.
setOptions()	Sets the options.
setProviderType()	Sets the provider type.
toString()	Writes out the service deployment descriptor to String.
toXML()	Writes out the service deployment descriptor as XML.

ProviderDeploymentDescriptor()

Description

Constructs a new instance of a provider descriptor.

Syntax

public ProviderDeploymentDescriptor();

fromXML()

Description

Builds and returns a provider descriptor from the given XML document.

Syntax

public static ProviderDeploymentDescriptor fromXML( Element root);

Parameter	Description
root	The root of the document that represents the XML provider descriptor.

getClassname()

Description

Returns the name of the class that implements this provider.

Syntax

public String getClassname();

getId()

Description

Returns the unique id for this provider.

Syntax

public String getId();

getOptions()

Description

Returns the provider-specific options, or value pairs that represent the provider-specific options for this service.

Syntax

public Hashtable getOptions();

getProviderType()

Description

Returns the provider type.

Syntax

public String getProviderType();

setClassname()

Description

Sets the name of the class that implements this provider.

Syntax

public void setClassname( String classname);

Parameter	Description
classname	The name of the implementing class.

setId()

Description

Sets the provider id.

Syntax

public void setId( String id);

Parameter	Description
id	The unique provider id.

setOptions()

Description

Sets the options.

Syntax

public void setOptions( Hashtable options);

Parameter	Description
options	The name-value pairs that represent the provider implementation-specific options for this service.

setProviderType()

Description

Sets the provider type.

Syntax

public void setProviderType( String providerType);

Parameter	Description
providerType	The provider type.

toString()

Description

Writes out the service deployment descriptor to String.

Syntax

public String toString();

toXML()

Description

Writes out the service deployment descriptor as XML.

Syntax

public void toXML( Writer pr);

Parameter	Description
pr	The writer for the XML output.

---

RequestContext Class

---

Description of RequestContext

RequestContext defines all of the context for a SOAP request, including information that is passed to the provider and information that the provider must set before returning. Note that the provider is given the request Envelope and is therefore responsible to unmarshall the request parameters. Similarly, the provider is required to marshall the response, although the response envelope must also be set by the provider, as it may be needed by a pluggable handler. The following information is provided by the SOAP engine to the Provider, meaning that the provider can utilize this information in Provider.invoke():

• getEnvelope - the envelope containing the request
• getServiceDeploymentDescriptor - the service deployment descriptor for the service in which the method is being invoked
• getServiceId - the URI of the service
• getUserContext - the security context describing the user invoking the method in the service
• getMethodName - the name of the method being invoked in the service.

The following information must be given by the Provider to the SOAP engine:

• setResponseBytes - this is the marshalled response. Given a Response, it can be created by building the response envelope and then marshalling the envelope.
• setResponseEnvelope - this is the response envelope, which is logically equivalent to the response bytes.
• getRequestEncodingStyle - the encoding style to use for the response in case of an error (if not set, defaults to Constants.NS_URI_SOAP_ENC, which is SOAP encoding). If the provider cares about this, it should set this value as soon as it can in case of an exception. The provider might use the same encoding as the reques