Skip Headers
Oracle® Application Server Web Services Developer's Guide
10g Release 2 (10.1.2)
Part No. B14027-01
  Go To Documentation Library
Home
Go To Product List
Solution Area
Go To Table Of Contents
Contents
Go To Index
Index

Previous
Previous
Next
Next
 

A Using Oracle Application Server SOAP

This appendix covers the following topics:

A.1 Understanding Oracle Application Server SOAP

In addition to the Oracle Application Server Web Services previously described in this chapter, that use a unique Servlet interface and J2EE deployment for Web Services, Oracle Application Server also provides Oracle Application Server SOAP (OracleAS SOAP) that is derived from Apache 2.3.1 SOAP and includes a number of enhancements.

The SOAP Message Processor, OracleAS SOAP, provides the following facilities:

A.2 Apache SOAP Documentation

OracleAS SOAP is a modified version of Apache SOAP 2.3.1. Most of the documentation that applies to Apache SOAP 2.3.1 also applies to OracleAS SOAP. The Apache SOAP 2.3.1 documentation can be found at the following site:

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

A.3 Configuring the SOAP Request Handler Servlet

The OracleAS SOAP Request Handler uses an XML configuration file to set required servlet parameters. By default, this file is named soap.xml and is placed in the soap.ear file in the directory $SOAP_HOME/lib on UNIX or %SOAP_HOME%\lib on Windows.

The XML namespace for this file is:

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

To use a different configuration file for SOAP installation, expand the soap.ear file. In the directory webapps/soap/WEB-INF on UNIX or webapps\soap\WEB-INF on Windows, modify the path name specified for the SoapConfig parameter in the soap.properties file. Then, redeploy the updated soap.ear file.

For example, to change the configuration file from the default, soap.xml, to newConfig.xml, modify the value set for soapConfig in soap.properties.

servlet.soaprouter.initArgs=soapConfig=soap_home/soap/webapps/soap/WEB-INF/newConfig.xml

Where soap_home is the full path to the SOAP installation on your system.

The pathAuth boolean attribute, if set to true, enforces that clients must specify the unique service URL in order to post a message to the deployed service. The service URL is the SOAP servlet URL with the service URI appended on at the end. The default value of this attribute (if unspecified) is false.

Table A-1 lists the SOAP Request Handler Servlet XML configuration file elements.

Table A-1 SOAP Request Handler Servlet Configuration File Parameters

Parameter Description
errorHandlers Specifies a list of handlers for the error handler chain.
faultListeners This is an optional element that defines a list of faultListener elements. The faultListener element specifies a class that is invoked when a fault occurs. To cause a stack trace to be added to the SOAP fault that is returned to the user, specify a faultListener of org.apache.soap.server.DOMFaultListener.
handler The handlers element is an optional element that defines a list of handler elements. The handler element defines a global handler that can be configured to be invoked on every SOAP request in one of three contexts: request, response, error. You can define any number of handlers. The handler's name attribute specifies the name of the handler; each handler must have a unique name. The handler's class attribute specifies the Java class that implements the handler, and this class must implement the interface oracle.soap.server.Handler. Each handler may have any number of options, which are name-value pairs. The contexts are configured in the elements: requestHandlers, responseHandlers, and errorHandlers. Each of these elements defines an ordered list of handler names, or a chain of handlers.

Note that SOAP creates one instance of each uniquely identified handler. Every appearance of a specific handler name in any chain refers to the same instance of the handler. Handlers are destroyed when the SOAP servlet is destroyed.

logger Error and informational messages are logged using the class defined in the logger element. The logger class must extend oracle.soap.server.Logger.

OracleAS SOAP includes the class oracle.soap.server.impl.ServletLogger that collects the servlet log methods so that SOAP messages are logged to the servlet log file. ServletLogger is the default logger. For the default logger, the severity option can be to any of the following values: status, error, debug.

If you specify error, you will get both status and error messages. Similarly, if you specify debug, you will get all three types of messages.

OracleAS SOAP includes two logger implementations. To log to the servlet log, use oracle.soap.server.impl.ServletLogger. To log to stdout, use oracle.soap.server.impl.StdOutLogger.

You may implement your own logger by implementing the oracle.soap.server.Logger interface.

providerManager The providerManager is an optional element that allows a configuration manager to be defined. This defines how the server accesses provider deployment information.

The providerManager class attribute specifies a Java class that implements oracle.soap.server.ProviderManager. The default configuration manager, oracle.soap.server.impl.XMLProviderConfigManager, persists the deployed providers to a file in XML format. It accepts a filename option. The filename is the path to the registry filename which may be a simple file name, relative path or an absolute path. If it is not an absolute path, then the path is determined from the filename and the servlet context. The default filename is WEB-INF/providers.xml.

An alternative provider configuration manager, oracle.soap.server.impl.BinaryProviderConfigManager, persists the deployed providers in a file as a serialized object. The default file is WEB-INF/providers.dd.

To specify a different configuration manager add a class attribute to the configManager element. For example:

<osc:configManager class="fully.qualified.classname">.

requestHandlers Specifies a list of handlers for the request handler chain
responseHandlers Specifies a list of handlers for the response handler chain
serviceManager The serviceManager is an optional element that allows a configuration manager to be defined and ServiceManager options to be set. This defines how the server accesses service deployment information. The serviceManager class attribute specifies a Java class that implements oracle.soap.server.ServiceManager.

The default OracleAS SOAP configuration manager class is oracle.soap.server.impl.XMLServiceConfigManager which stores the service deployment information in an XML file. Using XMLServiceConfigManager, the file name is specified with the filename option. The filename is the path to the registry filename which may be a simple file name, relative path or an absolute path. If it is not an absolute path, then the path is determined from the filename and the servlet context. The default filename is WEB-INF/services.xml.

To specify a different configuration manager add a class attribute to the configManager element.

For example:

<osc:configManager class="fully.qualified.classname">.

An alternative service configuration manager, oracle.soap.server.impl.BinaryServiceConfigManager, persists the deployed services in a file as a serialized object. The default file is WEB-INF/services.dd.

The service manager can automatically deploy the provider manager and the service manager as SOAP services. To allow these managers to be exposed as services, set the autoDeploy option to true. By default autoDeploy value is false.


A.4 Using OracleAS SOAP Management Utilities and Scripts

To use the OracleAS SOAP management utilities, you need to set up the execution environment for executing SOAP management utilities using one of the supplied client side scripts. The clientenv scripts set the CLASSPATH and add the $SOAP_HOME/bin directory to the path.

To set the client environment, on UNIX, use the following commands:

cd $SOAP_HOME/bin
source clientenv.csh

On Windows, use the following commands:

cd %SOAP_HOME%\bin
clientenv.bat

The clientenv scripts sets environment variables that are used by the other scripts and the samples. You can override these by setting the environment variables yourself. The variable SOAP_URL is the URL of the SOAP server and JAXP is set to use the DocumentBuilderFactory for the Oracle XML parser.

A.4.1 Managing Providers

The providerMgr script runs the SOAP client that manages providers. Run the script without any parameters for usage information.

On UNIX, use the following command:

providerrMgr.sh options

On Windows, use the following command:

providerMgr.bat options

Where the options for providerMgr are:

deploy ProviderDescriptorFile

This deploys the provider described in the ProviderDescriptorFile and makes the provider available.

undeploy ProviderID

This removes the provider with the supplied ProviderID. The ProviderID is the id attribute specified in the provider descriptor file.

The Java provider is deployed once at installation time with id=java-provider, but any provider you create must be explicitly deployed. For example, on UNIX, to deploy a provider using the provider deployment descriptor provider.xml, use the following command:

providerMgr.sh deploy provider.xml

A.4.2 Using the Service Manager to Deploy and Undeploy Java Services

The ServiceMgr is an administrative utility that deploys and undeploys SOAP services. To deploy a service, first set the SOAP environment, then use the deploy command. On UNIX, the command is:

source clientenv.csh
ServiceMgr.sh deploy ServiceDescriptorFile

For Windows, the command is:

clientenv.bat
ServiceManager.bat deploy ServiceDescriptorFile

The deploy option makes the service specified in ServiceDescriptorFile available.

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 ServiceID

For Windows, the command is:

ServiceManager.bat undeploy ServiceID

This makes the service with the given id unavailable. The ServiceID is the service id attribute specified in the service descriptor file.

The ServiceMgr supports listing and querying SOAP services. To list the available services, first set the SOAP environment, then use the list command. On UNIX, the command is:

source clientenv.csh
ServiceMgr.sh list

On Windows, the command is:

clientenv.bat
ServiceMgr.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:

ServiceMgr.sh query ServiceID

On Windows, the command is:

ServiceMgr.bat query ServiceID

Where ServiceID is the service id attribute set in the service descriptor file.

A.4.3 Generating Client Proxies from WSDL Documents

The wsdl2java script takes as input a WSDL document and returns a Java class which can be used to call the service. The Java class contains methods with the same names as those described in the WSDL document. The generated code make calls to the Apache client side libraries.

On UNIX, use the following command:

wsdl2java.sh options

On Windows, use the following command:

wsdl2java.bat options

Where the options for wsdl2java are:

wsdl2java.sh WsdlDocumentURL OutputDir [-k PackageName] [-s ServiceName] [-p PortName]

Where:

WsdlDocumentURL is the URL of the WSDL document.

OutputDir is the output directory for generated proxy Java code.

-k PackageName is the package name for generated proxy Java code.

-s ServiceName is the service name for which proxy will be generated.

-p PortName the port name of the service. The proxy is generated for the specified port of the service.

The output directory structure is:

output root dir/service name/port name/package name/java proxy source code

By default, the PackageName will be the same as the WSDL service name.

If neither of -s and -p options is specified, proxies for all ports of all services are generated. Without -p option specified, proxies for all ports of the specified service are generated.

A.4.4 Generating WSDL Documents from Java Service Implementations

The java2wsdl script takes as input a Java class and creates as output a WSDL document describing the class as an RPC service. When the Java class is used as a Web Service, the associated WSDL document can be transmitted to developers who might wish to call the service.

On UNIX, use the following command:

java2wsdl.sh options

On Windows, use the following command:

java2wsdl.bat options

Where the options for wsdl2java are:

java2wsdl.sh ClassName OutputFile SoapURL ClassURL1 ClassURL2 ...

Where:

ClassName is the fully qualified path name of a Java .class file that is to be a Web Service.

OutputFile is the output WSDL document name.

SoapURL is the SOAP endpoint.

ClassURL list serves as a class path for searching referenced classes

A.5 Deploying OracleAS SOAP Services

This section covers the following topics related to deploying and undeploying OracleAS SOAP Services:

A.5.1 Creating Deployment Descriptors

Deployment descriptors include service deployment descriptors and provider deployment descriptors. A provider deployment descriptor file is an XML file that describes, to the SOAP servlet, the configuration information for a provider. A service deployment descriptor file is an XML file that describes, to the SOAP servlet, the configuration information for a service.

Services written in Java only require a service descriptor. All Java service descriptors may point to the same Java provider descriptor supplied with the OracleAS SOAP installation.

Each service written as a PL/SQL stored procedure requires one service descriptor and one provider descriptor for each database user. The advantage of this is that when a password or user is changed, only one descriptor needs to be updated, not every service descriptor.

See the Stored Procedure section for more information.

Services written as an EJB require one service descriptor and one provider descriptor for each EJB container user.

See the EJB section of this document for more information.


Note:

For developers who wish to write their own providers, the Apache style provider interface and descriptors are also supported. Apache descriptors contain both service and provider properties in a single file, so common provider information must be duplicated for every service.

A service deployment descriptor file defines the following information:

  • The service ID

  • The service provider type (for example, Java)

  • The available methods

The best way to write a descriptor is to start with a copy of an existing descriptor from one of the sample directories.

Example A-1 shows the Java 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).

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 A-1 Java Service Descriptor File for Sample 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.

A.5.2 Installing a SOAP Web Service in OC4J

Install an OracleAS SOAP Web Service in Oracle Application Server Containers for J2EE (OC4J) by performing the following steps:

  1. Create service and provider deployment descriptors.

  2. Expand the soap.ear file found in $SOAP_HOME/lib on UNIX or %SOAP_HOME\lib on Windows.

  3. Copy Java classes and Jars implementing the service to the correct locations in the expanded soap.ear directories.

    Copy Java .class files to WEB-INF/classes.

    Copy Java .jar files to WEB-INF/libs.

  4. Redeploy the updated soap.ear file.

  5. Deploy the provider descriptor by executing the command:

    providerMgr.sh deploy FileName
    
    

    where FileName is the name of the provider descriptor xml file.

  6. Deploy the service by executing the command:

    serviceMgr.sh deploy FileName
    
    

    Where FileName is the name of the service descriptor xml file.

A.5.3 Disabling an Installed SOAP Web Service

To disable an installed service, run the command:

serviceMgr.sh undeploy ServiceID

where ServiceID is the id attribute of the service element in the service descriptor.

A.5.4 Installing a SOAP Web Service in an OC4J Cluster

It is necessary to install an OracleAS SOAP service on every machine in a cluster. If the service is not installed on all machines in a cluster, the cluster dispatcher might dispatch a service request to a machine that does not have the service, resulting in an error on the service invocation.

A.6 Using OracleAS SOAP Handlers

A handler is a class that implements the oracle.soap.server.Handler interface. A handler can be configured as part of a chain in one of three contexts: request, response, or error. Note that handlers in a chain are invoked in the order they are specified in the configuration file.

A.6.1 Request Handlers

Handlers in the request chain are invoked on every request that arrives, immediately after the SOAP Request Handler Servlet reads the SOAP Envelope. If any handler in the request chain throws an exception, the processing of the chain is immediately terminated and the service is not invoked.

The error chain is invoked if any exception occurs during request chain invocation.

A.6.2 Response Handlers

Handlers in the response chain are invoked on every request immediately after the service completes. If any handler in the response chain throws an exception, processing of the chain is immediately terminated. The error chain is invoked if any exception occurs during response chain invocation.

A.6.3 Error Handlers

When an exception occurs during either request-chain invocation, service invocation, or response-chain invocation, the SOAP Request Handler Servlet invokes the handlers in the error chain. In contrast to the request and response chains, an exception from an error handler is logged and processing of the error chain continues. All handlers in the error chain are invoked, regardless of whether one of the error handlers throws an exception.

A.6.4 Configuring Handlers

Configure handlers and handler chains in the SOAP configuration file. Handlers can be invoked for each service request or response, or when an error occurs. Handlers are global in the sense that they apply to every SOAP request and cannot be configured on a subset of requests, such as all requests for a particular service.

Configure a handler by setting parameters in the SOAP configuration file, soap.xml. Example A-2 shows a sample segment from a SOAP configuration file showing the configuration for a handler.

Example A-2 Handler Configuration

<osc:handlers>
   <osc:handler name="auditor"
      class="oracle.soap.handlers.audit.AuditLogger">
      <osc:option name="auditLogDirectory"
           value="/private1/oracle/app/product/tv02/soap/webapps/soap/WEB-INF"/>
      <osc:option name="filter" value="(!(host=localhost))"/>
   </osc:handler>
</osc:handlers>
 
<osc:requestHandlers names="auditor"/>
<osc:responseHandlers names="auditor"/>
<osc:errorHandlers names="auditor"/>

A.7 Using OracleAS SOAP Audit Logging

The OracleAS SOAP audit logging feature monitors and records SOAP usage. Audit logging maintains records for postmortem analysis and accountability. The SOAP audit logging feature complements the audit logging capabilities available with the OC4J server which hosts the SOAP Request Handler Servlet (SOAP server).

OracleAS SOAP stores audit trails as XML documents. Using XML documents, OracleAS SOAP creates portable audit trails and enables the transformation of complete audit trails or individual audit records to different formats.

By default, OracleAS SOAP audit logging uses an audit logger class that implements the Handler interface (part of the oracle.soap.server package). The audit logger class is invoked conditionally to monitor events including service requests, service responses, and errors.

This section covers the following topics:

A.7.1 Audit Logging Information

Table A-2 lists the audit logging elements available for each audit log record. Individual audit log records may not contain all these elements. In the log file, each audit log record is stored as a SoapAuditRecord element.

Table A-2 Auditable Audit Record Elements

Audit Record Element Description
HostName Specifies the hostname of the client that sent the request.
IpAddress Specifies the IP address of the client that sent the request.
Method Specifies the method name for the SOAP request.
Request Envelope Provides the complete SOAP request message.
Request Envelope Method Name of the Method in the SOAP request envelope
Request Envelope URI Specifies the URI of the service in the SOAP request envelope.
Response Envelope Provides the complete SOAP response message.
ServiceURI Specifies the service URI for the SOAP request.
SoapAuditRecord Contains an individual record. The chainType attribute indicates if the record is generated as part of a request or a response.
TimeStamp Specifies the system time when the SOAP audit record was generated.
User Specifies the username associated with the request. Note, this element is only provided when a user context is associated with the service request or service response.

A.7.1.1 Audit Logging Output

The XML schema for the generated audit log is provided in the file SoapAuditTrail.xsd in the directory $SOAP_HOME/schema on UNIX or %SOAP_HOME%\schema on Windows. Refer to the schema file for complete details on the format of a generated audit log record.

A.7.2 Auditable Events

The audit logger class is invoked when an auditable event occurs and the SOAP Request Handler Servlet is configured to enable auditing for the event. Auditable events include a service request or a service response.

A.7.2.1 Audit Logging Filters

An audit logging filter can be specified in the SOAP configuration file to limit the set of auditable events that are recorded to the audit log. The SOAP server applies event filters to request and response events. Table A-4 shows the filter attributes available to select with an event filter specification. When applied, filters limit the number of records generated in the audit log. For example, when a filter is specified for a particular host, only the auditable events generated for the specified host are saved to the audit log.

The syntax for defining auditable events with a filter is derived from RFC 2254. Table A-3 shows the filter syntax, and Example A-3 provides several examples.

Table A-3 Audit Trail Events Filter Attributes

Audit Event Filter Attributes Description
Host Specifies the hostname of the host for the service request or response. If this attribute is not specified in a filter, the hostname of the client is not used in filtering audit log records.

Fully specify the hostname of the client or use wildcards ("*"). Wildcards embedded within the specified hostname are not supported the examples show valid and invalid uses of wildcards. If a wildcard is used then the wildcard must be the first character in the filter. Case is ignored for hostnames. Care should be used in setting this attribute. Depending on the DNS setup, the hostname returned could be fully qualified or nonqualified; for example, explosives.acme.com or explosives. For some IP addresses, the DNS may not be able to resolve the hostname.

Legal values for a Host filter attribute include the following examples:

explosives.acme.com, *.acme.com, *.com

Illegal values for a Host filter attribute include the following examples:

*, explosives.acme.*, explosives.*, ex*s.acme.com, *ives.acme.com 
ip Specifies the IP address of the client for the service request or response.

The IP address of the client has to be either fully specified, using all four bytes, in the dot separate decimal form, or specified using wildcards ("*"). Embedded wildcards are not supported. If a wildcard is used then the wildcard must be the last character in the filter.

If this attribute is not used in a filter then the IP address of the client is not used in filtering.

Legal values for an ip filter attribute include the following examples:

 138.2.142.154, 138.2.142.*, 138.2.*, 138.* 

Illegal values for an ip filter attribute include the following examples:

*, 138.2.*.154, *.2, 138.*.152, 138.2.142, 138.2, 138 
urn Specifies the service URN. Wildcards are not supported for this attribute.
username Specifies the transport level username associated with the client.

Wildcards are not supported in a username filter attribute.


Table A-4 Audit Log Filter Syntax

Filter Value Description
attr 1*(any US-ASCII char except "*", "(", ")", "&", "|", "!", "*", "=")
equal "="
filter "("filtercomp")"

Whitespaces between "("filtercomp and ")" are not allowed.

filtercomp and | or | not | item

and = "&" filterlist

or = "|" filterlist

not = "!" filter

filterlist 2*2 filter
filtertype equal
item attr filtertype value

Whitespaces between attr, filtertype and value are not allowed.

value 1*(any octet except ASCII representation of ")" - 0x29).

The character "*" has a special meaning.

The "*" character is referred to as a wildcard and matches anything.


Example A-3 Sample Audit Log Filters

(ip=138.2.142.154) 
(!(host=localhost))
(!(host=*.acme.com))
(&(host=*.acme.com)(username=daffy))
(&(ip=138.2.142.*)(|(urn=urn:www-oracle-com:AddressBook)(username=daffy))) 

A.7.3 Configuring the Audit Logger

Configure the default SOAP audit logger supplied with Oracle Application Server by setting parameters in the SOAP configuration file, soap.xml. To enable the default audit logger and turn on audit logging, do the following in the configuration file.

  • Define the name and options for the audit log handler. The default SOAP audit logger is defined in the class oracle.soap.handlers.audit.AuditLogger. The default audit logger supports several options that you specify in the configuration file. Table A-5 shows the available audit logger options.

  • Add the name for the audit logger handler to the requestHandler, responseHandler, or errorHandler chain (or to all of the handler chains).

Example A-4 shows a sample segment from a SOAP configuration file including the audit logging configuration options. Example A-4 shows configuration options set to use all options. However, this configuration would produce an extremely large audit log, and is not recommended.


Note:

When you audit errors using the audit logger, depending on when the error occurs in the request-chain or the response-chain, it is possible that the request or response message may not be included in the audit log record, even with includeRequest or includeResponse enabled.

Example A-4 Audit Logging Configuration

<osc:handlers>
   <osc:handler name="auditor"
      class="oracle.soap.handlers.audit.AuditLogger">
      <osc:option name="auditLogDirectory"
           value="/private1/oracle/app/product/tv02/soap/webapps/soap/WEB-INF"/>
      <osc:option name="filter" value="(!(host=localhost))"/>
      <osc:option name="includeRequest" value="true"/>
      <osc:option name="includeResponse" value="true"/>
   </osc:handler>
</osc:handlers>
<osc:requestHandlers names="auditor"/>
<osc:responseHandlers names="auditor"/>
<osc:errorHandlers names="auditor"/>

Table A-5 Audit Logger Configuration Options

Option Description
auditLogDirectory Specifies the directory where the audit log file is saved. The auditLogDirectory option is required. The name of the generated audit log file is OracleSoapAuditLog.timestamp, where timestamp is the date and time the file is first generated.

Valid values: any string that is a valid directory

filter Specifies the audit event filter. This option is optional. If a filter is not specified SOAP server logs every event.

Valid values: any valid filter.

includeRequest Specifies that the audit record include the request message for the event that generated the audit log record.

Valid values: true, false

Any value other than true or false is treated as an error.

Default Value: false

includeResponse Specifies that the audit record include the response message for the event that generated the audit log record.

Valid values: true, false

Any value other than true or false is treated as an error.

Default Value: false



A.8 Using OracleAS SOAP Pluggable Configuration Managers

OracleAS SOAP supports pluggable configuration managers similar to those supported in Apache SOAP 2.3.1. Since OracleAS SOAP supports provider deployment descriptors separate from service deployment descriptors, the interface details using OracleAS SOAP are slightly different from Apache SOAP 2.3.1. In OracleAS SOAP, configuration managers are configured separately for the provider manager and the service manager. All configuration managers must implement the oracle.soap.server.ConfigManager interface.

To simplify development, when you write a configuration manager implementation, you may the abstract class that is provided with OracleAS SOAP (oracle.soap.server.impl.BaseConfigManager). This abstract class provides a standard implementation for most of the ConfigManager interface with two abstract methods that read and write the persistent store.

Example A-5 shows a sample implementation of a provider configuration manager.

Example A-5 Sample Provider Configuration Manager Implementation.

public class MyProviderConfigManager extends BaseConfigManager
{ 
    public void setOptions(Properties options) 
        throws SOAPException 
    { 
        // handle implementation specific options 
    } 

    public void readRegistry() 
        throws SOAPException 
    { 
        // read the deployed providers from persistent store 
    } 

    public void writeRegistry() 
        throws SOAPException 
    { 
        // write the deployed providers to persistent store 
    } 
} 

The setOptions method is passed the options specified in any <option> elements specified in the <configManager> element. Synchronization of reading/writing the registry is the responsibility of the specific configuration manager implementation.

A.9 Working With OracleAS SOAP Transport Security

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

OracleAS SOAP Client transport uses the modified, to support Oracle Wallet Manager, HTTPClient package. OracleAS SOAP transport defines several properties to support these features. Table A-6 lists the client-side security properties that Oracle Application Server supports.

In an OracleAS SOAP Client application, you can set the security properties shown in Table A-6 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 A-6 shows how Oracle Application Server supports overriding the values specified for system properties using Oracle Application Server 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 A-6 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 A-6 SOAP HTTP Transport Security Properties

Property Description
http.authRealm Specifies the realm for which the HTTP authentication username/password is specified.

This property is mandatory when using basic authentication.

http.authType Specifies the HTTP authentication type. The case of the value specified is ignored.

Valid values: basic, digest

The value basic specifies HTTP basic authentication.

Specifying any value other than basic or digest is the same as not setting the property.

http.password Specifies the HTTP authentication password.
http.proxyAuthRealm Specifies the realm for which the proxy authentication username/password is specified.
http.proxyAuthType Specifies the proxy authentication type. The case of the value specified is ignored.

Valid values: basic, digest

Specifying any value other than basic or digest 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 for java.net.URLStreamHandlerFactory The prefixes should be separated by "|" vertical bar characters.

This value should contain: HTTPClient This value is required by the Java protocol handler framework; it is not defined by Oracle Application Server. 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=HTTPClient

  • java.protocol.handler.pkgs=sun.net.www.protocol|HTTPClient

oracle.soap. transport. 1022ContentType Specifies the value for the Content-Type HTTP header in Oracle9iAS, and in Oracle Application Server 10g. The value for this property supports Oracle SOAP servers running either Oracle 9iAS Release 1.0.2.2 or Release 9.0.x or 10g (9.0.4). This property provides interoperablity between Oracle9iAS Release 9.0.x Oracle SOAP clients or Oracle Application Server 10g (9.0.4) and older server versions (as distributed with Oracle9iAS Release 1.0.2.2).

Valid values: true, false (case is ignored)

Setting the value to true specifies to use the Oracle9 iAS Release 1.0.2.2 content-type HTTP header values when the SOAP message is sent. In this case, the value is set to: content-type: text/xml

Setting the value to false specifies to use the Oracle Application Server version 9.0.x content-type header value when the SOAP message is sent. In this case, the value is set to: content-type: text/xml; charset=utf-8

The value false is the default value.

Note: for SOAP messages with attachments, the content-type HTTP header is always set to the value: multipart/related.

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:
  1. 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.

  2. 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.ssl.ciphers Specifies a list of: separated cipher suites that are enabled.

Default value: The list of all cipher suites supported by Oracle SSL are supported.

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)

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.

A.9.1 Apache Listener and Servlet Engine Configuration for SSL

When using Apache listener and mod_ssl (or mod_ossl), the following directives must be set for the soap servletlocation/directory:

SSLOption +StdEnvVars +ExportCertData

This directive can be set conditionally, refer to mod_ssl/mod_ossl documentation for details. By default this directive is disabled for performance reasons. If this directive is not set then the servlet engine does not have a way to access the SSL related data (such as the cipher suite, client cert etc).

A.9.2 Using JSSE with Oracle Application Server SOAP Client

This section describes how to use SSL with the OracleAS SOAP Client side when the Oracle security infrastructure is not available. Availability of Oracle security infrastructure means the availability of Oracle client side libraries (including $ORACLE_HOME/lib/*, $ORACLE_HOME/jlib/javax-ssl-1_2.jar, and $ORACLE_HOME/jlib/jssl-1_2.jar).

OracleAS SOAP uses the following class as the default transport class:

oracle.soap.transport.http.OracleSOAPHTTPConnection

This class uses a modified version of HTTPClient package. For information on HTTPClient, see the following site:

http://www.innovation.ch/java/HTTPClient/

This version of HTTPClient package is integrated with Oracle Java SSL and supports Oracle Wallet for HTTPS transport. If a SOAP client side does not have OracleAS SOAP Client side available, it is still possible to use HTTPS as a transport with OracleAS SOAP Client side libraries.

To do this, follow these steps:

  1. Use the following transport class:

    class org.apache.soap.transport.http.SOAPHTTPConnection
    
    

    If using RPC then call the following method by passing an instance of org.apache.soap.transport.http.SOAPHTTPConnection as an argument:

    method org.apache.soap.rpc.Call#setSOAPTransport  (org.apache.soap.transport.SOAPTransport)
    
    

    For example:

    org.apache.soap.rpc.Call myCallObj = new
    org.apache.soap.rpc.Call();
    myCallObj.setSOAPTransport(new    org.apache.soap.transport.http.SOAPHTTPConnection());
    
    

    If using messaging, then call the following method by passing an instance of org.apache.soap.transport.http.SOAPHTTPConnection as an argument:

    org.apache.soap.messaging.Message#setSOAPTransport
    (org.apache.soap.transport.SOAPTransport)
    
    

    For example:

    org.apache.soap.messaging.Message myMsgObj = new
    org.apache.soap.messaging.Message();
    myMsgObj.setSOAPTransport(new
      org.apache.soap.transport.http.SOAPHTTPConnection());
    
    
  2. Download Java Secure Socket Extension (JSSE) and configure JSSE according to the supplied instructions. JSSE is available at the following site:

    http://java.sun.com/products/jsse/
    
    
    • Make sure the files jnet.jar, jcert.jar and jsse.jar are in the classpath or in the installed extensions directory ($JRE_HOME/lib/ext).

    • Make sure that SunJSSE provider is correctly configured. This can be done either statically by editing the $JRE_HOME/lib/security/java.security file and adding the line:

              security.provider.num=com.sun.net.ssl.internal.ssl.Provider
    
    

    Where num is 1-based preference order or by dynamically by adding the provider at run time by adding the following line of code:

    Security.addProvider(new com.sun.net.ssl.internal.ssl.Provider());
    
    
    

    Dynamic addition of security providers requires that appropriate permissions are set.

    • Make sure the system property java.protocol.handler.pkgs is set to com.sun.net.ssl.internal.www.protocol

    • If using proxy server, make sure that the following system properties are set is set to the correct proxy hostname and proxy port, respectively:

      https.proxyHost
      https.proxyPort
      
      
    • If using SSL with server side authentication and the default TrustManager, ensure that the certificate signer of the server is one of the following files:

      $JRE_HOME/lib/security/jssecacerts
      
      

      or if jssecacerts does not exist:

      $JRE_HOME/lib/security/cacerts
      
    
    
    • To override the KeyManager/TrustManager keystore default locations, use the system properties:

      javax.net.ssl.keystore
      javax.net.ssl.keyStoreType
      javax.net.ssl.keyStorePassword
      javax.net.ssl.trustStore
      javax.net.ssl.trustStoreType
      javax.net.ssl.trustStorePassword
      

      Please consult JSSE documentation for details. If using a specific third party JSSE implementation, please consult the appropriate documentation.


      See Also:

      HTTPClient information at the site:

      http://www.innovation.ch/java/HTTPClient/


A.10 Using OracleAS SOAP Sample Services

The section lists the samples included with OracleAS SOAP. The class files for all of the samples are in $SOAP_HOME/lib/samples.jar on UNIX or in %SOAP_HOME%\lib\samples.jar on Windows.

To run any sample, you need to ensure that samples.jar is available on your servlet's CLASSPATH. Please refer to the README included with each sample for more information.

A.10.1 The Xmethods Sample

The clients in the xmethods sample represent the easiest way to get started with SOAP because they are clients that access existing services that are hosted on systems on the internet. Information on these services can be found at the site:

http://www.xmethods.org

This sample is in $SOAP_HOME/samples/xmethods.

A.10.2 The AddressBook Sample

This sample has a service implemented in Java and several clients. This sample illustrates literal XML encoding. See $SOAP_HOME/samples/addressbook for the sample source code. This directory also contains a script that illustrates how to run the sample addressbook clients using HTTPS as transport.

A.10.3 The StockQuote Sample

This sample has a service implemented in Java and one client. It is located in $SOAP_HOME/samples/stockquote

A.10.4 The Company Sample

This sample has a service that is comprised of PL/SQL stored procedures and several clients. It is located in $SOAP_HOME/samples/sp/company. Check the README file in this directory for details on how to setup, compile, and test this sample service.

A.10.5 The Provider Sample

This includes a template provider that can be used as a starting point for creating your own provider.

A.10.6 The AddressBook2 Sample

This sample demonstrates use of the Addressbook service with session scope. It shows how to maintain the same HTTP session across SOAP Calls. It contains an example of a SOAP client proxy generated from a WSDL service description file. It is located in $SOAP_HOME/samples/addressbook2

A.10.7 The Messaging Sample

This sample is an example of a message-based SOAP service. It is located in $SOAP_HOME/samples/messaging

A.10.8 The Mime Sample

This sample does SOAP with attachments using both RPC and message based services. It is located in $SOAP_HOME/samples/mime.

A.11 Using the OracleAS SOAP EJB Provider

This section compares the OracleAS SOAP EJB providers with the Apache-SOAP 2.2 EJB providers.

A.11.1 Stateless Session EJB Provider

In Apache SOAP, the Stateless EJB provider, on receiving the SOAP request, performs a JNDI lookup on the home interface of the EJB. The Stateless EJB provider then invokes a create on the EJB's Home Interface in order to get a reference to a stateless EJB. Then it uses this EJB reference to invoke the requested method.

OracleAS SOAP uses the same mechanism to support Stateless Session EJBs as Apache SOAP.

A.11.2 Stateful Session EJB Provider in Apache SOAP

On receiving a first time SOAP request, the Apache SOAP Stateful Session EJB provider first locates the Home Interface through a JNDI lookup and using a subsequent create obtains an object reference to a Stateful Session EJB. The provider then invokes the requested method on the object reference.

In the next step the provider serializes the EJBHandle of the specified EJB reference and appends it to the targetURI with an "@" delimiter. The Stateful Session EJB provider then sends this modified target URI back to the requesting SOAP client. If the client wants to reuse the same EJB instance, it must retrieve this "modified" target URI for the service from the Response and set it in the next SOAP Call.

Upon receiving this request, the Stateful EJB provider extracts the stringified EJB reference and deserializes it into an EJBHandle from which it can obtain the EJB reference. It can then invoke the method on the specified EJB.

The drawback of the Apache SOAP implementation is that the client must be EJB aware and that it could not operate with other SOAP servers.

OracleAS SOAP offers an alternative solution for Stateful Session EJBs that allows for client interoperablity.

A.11.3 Stateful Session EJB Provider in OracleAS SOAP

The OracleAS SOAP Stateful Session EJB provider binds the EJB reference to the current session, if none is bound, otherwise, it merely retrieves the EJB reference from the session. In order for the client to access the same Stateful Session EJB, the client has to simply maintain it's current session between successive Calls.

If at any point in a session, the SOAP client invokes a create on the EJB's Home Interface, the provider binds the EJB reference from the create to the session, to be used for other call requests within the session.

A.11.4 Entity EJB Provider in OracleAS SOAP

In order for a SOAP client to run a business method on an entity EJB, it first needs to either "create" a new EJB upon which to run the method or find an already existing EJB which suit some criteria. Access to an entity EJB occurs within a session. At the start of the session the SOAP client must invoke a "create" or "find" (in order to specify the bean object interest). While maintaining the same session, all other business methods are directed to that EJB. A subsequent "find" or "create" within the same or different session directs business method execution requests to the newly "created" (or "found") EJB.

Another issue is that EJB specification provides that some "find" methods can return either a Collection of EJB refs or single EJB ref.

The Oracle solution for Entity EJBs embraces the following solution for this problem:

It disallows find methods that return "Collections". This allows for the provider to uniquely specify an Entity EJB to target subsequent business method requests.

A.11.5 Deployment and Use of the OracleAS SOAP EJB Provider

To install an EJB provider and deploy Web Services to the provider under OC4J, where the application server hosts both the SOAP servlet and the deployed EJB's, follow these steps:

  1. Deploy an EJB provider to SOAP using a provider descriptor.

    The provider descriptor specifies the following:

    • EJB access credentials by the middle tier

    • JNDI context factory class

    • JNDI context factory URL

    • Provider class name

    • Provider id

  2. Create the EJB Web Service:

    • Define the associated EJB classes and package the EJB into an EAR file as defined by J2EE spec.

    • Define the service descriptor which specifies following details of the EJB Web Service:

      • JNDI Location

      • Home interface class name

      • Application Deployment Name of this EJB Web Service in OC4J

      • The provider id to which this service is to be associated

  3. Deploy ear file in OC4J. Modify the OC4J specific EJB descriptor to correct the JNDI location for the EJB (as described in sample README).

A.11.6 Current Known EJB Provider Limitations

All service methods can only take primitive Java types as arguments to the methods. User-defined Java types are currently not supported.

A.12 Using PL/SQL Stored Procedures With the SP Provider

The OracleAS SOAP Stored Procedure (SP) Provider supports exposing PL/SQL stored procedures or functions as SOAP services. The Oracle9i Database Server allows procedures implemented in other languages, including Java and C/C++, to be exposed using PL/SQL; these stored procedures are exposed as SOAP services through PL/SQL interfaces.

The SP Provider framework works by translating PL/SQL procedures into Java wrapper classes, and then exporting the generating Java classes as SOAP Java services.

A.12.1 SP Provider Supported Functionality

The SP Provider supports the following:

  • PL/SQL stored procedures. both procedures and functions (this document uses procedure to refer to both)

  • IN parameter modes

  • Packaged procedures only (top-level procedures must be wrapped in a package before they can be exported)

  • Overloaded procedures (however, if two different PL/SQL types map to the same Java type during translating, there may be errors during the export of the PL/SQL package; these errors may be fixed by avoiding the overloading, or else by writing a new dummy package which does not contain the offending overloaded procedures)

  • Simple types

  • (user-defined) object types

A.12.2 SP Provider Unsupported Functionality

The SP provider does not support the following:

  • The SP Provider framework uses Oracle JPublisher to translate from PL/SQL to Java; hence, it inherits all of the restrictions of Oracle JPublisher.

A.12.3 SP Provider Supported Simple PL/SQL Types

The SOAP SP provider supports the following simple types. NULL values are supported for all of the simple types listed, except NATURALN and POSITIVEN.

The Oracle JPublisher documentation provides full details on the mappings of these types.

  • VARCHAR2 (STRING, VARCHAR)

  • LONG

  • CHAR (CHARACTER)

  • NUMBER (DEC, DECIMAL, DOUBLE PRECISION, FLOAT, INTEGER, INT, NUMERIC, REAL, SMALLINT)

  • PLS_INTEGER

  • BINARY_INTEGER (NATURAL, NATURALN, POSITIVE, POSITIVEN)

A.12.4 Using Object Types

Oracle JPublisher supports the use of user-defined object types. The SP Provider framework generates oracle.sql.CustomDatum style classes since these allow automatic serialization using the default BeanSerializer in SOAP.

Refer to the company sample for an example of using object types.

A.12.5 Deploying a Stored Procedure Provider

Example A-7 shows a sample provider deployment descriptor for a stored procedure. You may use any unique id for the provider name (the example uses "company-provider").

The attributes user, password, and url are used to create the URL to connect to the database, and they are all required. The number of connections for a service, handled by this provider, is set using connections_per_service; this is optional and defaults to 10.

Deploy the sample provider descriptor shown in Example A-7, appropriately edited for the local configuration, using the provider manager.

Example A-7 Sample SP Provider Deployment Descriptor

<isd:provider xmlns:isd="http://xmlns.oracle.com/soap/2001/04/deploy/provider"
    id="company-provider"
    class="oracle.soap.providers.sp.SpProvider">
  <!-- edit the following option "values" as appropriate -->
  <isd:option key="user" value="YOUR-USER-NAME" />
  <isd:option key="password" value="YOUR-PASSWORD" />
  <isd:option key="url" value="jdbc:oracle:thin:@YOUR-HOST:YOUR-PORT:YOUR-SID" />
  <isd:option key="connections_per_service" value="3" />
</isd:provider>

A.12.6 Translating PL/SQL Stored Procedures into Java

The shell script $SOAP_HOME/bin/sp2jar.sh translates a PL/SQL package and all its contained procedures/functions into a Java class with equivalent methods. If the package uses any user-defined types, these types are also translated into equivalent Java classes.

The README file in the samples directory has an example of the usage of the sp2jar.sh command to translate the company example into a jar file of compiled Java classes. The README also describes how to load the PL/SQL packages into the database.

Let us assume for the rest of the document that a PL/SQL package company has been installed on a database, and it has been exported into a set of compiled Java classes available in the jar file company.jar.

The generated company.jar should be made available in the CLASSPATH of the SOAP servlet, just as for other Java services.

A.12.7 Deploying a Stored Procedure Service

Example A-8 shows a sample service deployment descriptor for a stored procedure. Notice that the id attribute in the provider element identifies the provider under which this service is deployed.

The service descriptor looks exactly like that for a Java service, since the SP Provider framework translated PL/SQL procedures into Java class methods. All of the information specific to PL/SQL are part of the provider descriptor---the service itself looks like a Java service.

If the procedures use object types, it is necessary to define a type mapping for each object type. The XML type name must be identical to the SQL type name and must be in UPPER CASE (see EMPLOYEE and ADDRESS below). The javaType attribute identifies the oracle.sql.CustomDatum type that was generated by Oracle JPublisher.

The default BeanSerializer can be used to serialize/deserialize the types.

The generated method names are in lower-case since this is the default setting of Oracle JPublisher.

Deploy the sample service descriptor shown in Example A-8 using the service manager.

Example A-8 Sample Stored Procedure Service Deployment Descriptor

<isd:service xmlns:isd="http://xmlns.oracle.com/soap/2001/04/deploy/service"
    id="urn:www-oracle-com:company"
    type="rpc" >

   <isd:provider
    id="company-provider"
    methods="addemp getemp getaddress getempinfo changesalary removeemp"
    scope="Application" >
    <isd:java class="samples.sp.company.Company"/>
   </isd:provider>

  <isd:mappings>
    <isd:map encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
     xmlns:x="urn:company-sample" qname="x:EMPLOYEE"
     javaType="samples.sp.company.Employee"
         java2XMLClassName="org.apache.soap.encoding.soapenc.BeanSerializer"
             xml2JavaClassName="org.apache.soap.encoding.soapenc.BeanSerializer"/>
    <isd:map encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
             xmlns:x="urn:company-sample" qname="x:ADDRESS"
             javaType="samples.sp.company.Address"
             java2XMLClassName="org.apache.soap.encoding.soapenc.BeanSerializer"
           xml2JavaClassName="org.apache.soap.encoding.soapenc.BeanSerializer"/>
  </isd:mappings>

  <isd:faultListener class="org.apache.soap.server.DOMFaultListener"/>

</isd:service>

A.12.8 Invoking a SOAP Service that is a Stored Procedure

SOAP services that are PL/SQL stored procedures are invoked in exactly the same manner as any other SOAP service. The company.jar file created during the translating/deployment of a PL/SQL package is also needed on the client-side to compile application programs that invoke the SOAP service (this jar file is needed only if the stored procedures have input/output types that are user-defined types; if the procedures use only builtin-types, the generated jar file is not needed on the client).

The README file in the company samples directory has instructions on how to compile and test the sample client.

A.13 SOAP Troubleshooting and Limitations

This section lists several techniques for troubleshooting Oracle Application Server Web Services, including:

A.13.1 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 A-7 lists the command line options for TcpTunnelGui.

Table A-7 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

A.13.2 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 in the file soap.xml. This file is placed in soap.ear file in the directory $SOAP_HOME/lib on UNIX or in %SOAP_HOME%\lib on Windows.

To modify the debugging option, expand the soap.ear file and modify the file soap.xml in the directory webapps/soap/WEB-INF on UNIX or in webapps\soap\WEB-INF on Windows, then redeploy the updated soap.ear file.

For example, the following soap.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 stopping and restarting the SOAP Request Handler Servlet, you can view debug information in the file x.log. The file is in the directory $ORACLE_HOME/Apache/logs on UNIX or in %ORACLE_HOME%\Apache\x\logs on Windows.

A.13.3 Using DMS to Display Runtime Information

Oracle Application Server Web Services 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

A.13.4 SOAP Limitations for Java Type Precedence with Overloaded Methods

OracleAS SOAP supports Java inbuilt (primitive) types, wrapper types, one dimensional arrays of inbuilt types, and one dimensional arrays of wrapper types as parameters for SOAP RPC.

An inbuilt type parameter always takes precedence to a wrapper type parameter when the Java provider searches for an overloaded method. When there isn't a clear winner, for an overloaded method, a fault with appropriate message is returned.

For example:

A java class containing aMethod(int) hides aMethod(Integer) in the same class.

A java class containing aMethod(int[]) hides aMethod(Integer[]) in the same class.

A java class, when deployed as a SOAP RPC service returns a fault when a client invokes aMethod() containing the signatures, aMethod(int, Float) and aMethod(Integer, float). In this case, there is no clear winner for resolving the precedence of the overloaded aMethod().

A.14 OracleAS SOAP Differences From Apache SOAP

This section covers differences between Apache Soap and OracleAS SOAP.

A.14.1 Service Installation Differences

Additional instructions are provided for installing services when OracleAS SOAP is used in conjunction with OC4J.

A.14.2 Optional Provider Enhancements

OracleAS SOAP supports both the Apache Provider interface, defined in org.apache.soap.util.Provider, and an enhanced provider interface, defined in oracle.soap.server.Provider.

The native Apache provider includes only two methods, locate() and invoke(). The Oracle Provider interface combines the locate and invoke methods, so that the provider does not have to store input parameters between the locate() and invoke() calls. Additionally, the Oracle Provider interface has init() and destroy() methods, which the SOAP servlet calls only once when the provider is instantiated. This allows providers to perform one time initialization such as opening a database or network connection, and to perform one time clean up activities.

When using the Apache provider interface, a single deployment descriptor supplies both service and provider properties. When using the Oracle Provider interface, these properties are separated between a service descriptor file and a provider descriptor file. This allows common provider properties to be shared among services. When a provider property changes, only a single descriptor file must be changed. Please see the Deployment section of this document for more information.

A.14.3 Oracle Transport libraries

Oracle transport libraries are included for use with SOAP clients. Use of these libraries enables use of the Oracle Wallet Manager for keeping certificates securely, and use of the HttpClient libraries for HTTP connection management. The HttpClient libraries fix a security problem in the native Apache code which incorrectly returns cookies to servers other than the originating server.

A.14.4 Modifications to Apache EJB Provider

The Apache EJB provider has been modified to work with the OC4J EJB container. In addition, the client interface to services provided by stateful and entity EJB's has been improved. The EJB handle is contained in the HttpSession association with the connection rather than being concatenated to the returned URL. Since the HTTPSession cookie is handled transparently by the SOAP client, no special coding is required in the client.

A.14.5 Stored Procedure Provider

A special provider has been added which allows services to be written using PL/SQL Stored Procedures or Functions.

A.14.6 Utility Enhancements

The wsdl2java and java2wsdl scripts simplify building client side code from WSDL descriptions and for generating WSDL descriptions of Java services.

A.14.7 Modifications to Sample Code

The Apache samples have been modified to work with OracleAS SOAP and OC4J. The com, calculator, weblogic_ejb samples have been omitted. New samples illustrating use of Oracle Stored Procedures and OC4J EJB's as Web Services have been added.

A.14.8 Handling the mustUnderstand Attribute in the SOAP Header

This section describes the check that is performed for the mustUnderstand attribute within the header blocks of the SOAP envelope, and describes the difference between the Apache SOAP and the OracleAS SOAP processing of this attribute.

A.14.8.1 Setting the mustUnderstand Check

The check for the mustUnderstand attribute is enabled in the deployment descriptor of the service by setting the checkMustUnderstands flag. If this flag set to true, the check for the mustUnderstand attribute within each header block is performed. If the checkMustUnderstands flag is set to false, the check for the mustUnderstand attribute is not performed. The default value of checkMustUnderstands flag is true.

A.14.8.2 How the mustUnderstand Check Works

If the checkMustUnderstands flag is set to true, then a check is made on all header entries of the envelope after the global request handlers have finished processing and before handing the envelope to the appropriate service. At this point, if any header entries contain a mustUnderstand attribute that is set to true or to "1", then an exception is thrown. Note, the global handler(s) can be used to process one or more header blocks that have the mustUnderstand attribute set to true.

If the checkMustUnderstands flag is set to false, then header entries of the envelope are not checked to see if any entries contain a mustUnderstand attribute that is set to true or to "1". It is then understood that it is up to the service implementation to make sure that this check is done before processing the body of the envelope.

A.14.8.3 Differences Between Apache SOAP and Oracle SOAP for mustUnderstand

The differences between Apache SOAP and OracleAS SOAP with respect to the handling of the mustUnderstand attribute are the following:

  1. In the Apache service deployment descriptor and the Oracle Service deployment descriptor, you may include the checkMustUnderstands attribute. In Apache, the default value of the checkMustUnderstands attribute is false, in OracleAS SOAP the default value of this attribute is true.

  2. In Apache SOAP, if the service deployment descriptor contains checkMustUnderstands='true' and a message with mustUnderstand='1' or mustUnderstand="true" arrives at the server then a fault is sent back with the fault code value of:

    mustUnderstand

    This fault code is not namespace qualified and is incorrect.

    In OracleAS SOAP the fault code that is sent back is namespace qualified and is defined by SOAP 1.1:

    SOAP-ENV:MustUnderstand

  3. In Apache SOAP, the mustUnderstand attribute has to be handled by the service implementation. In OracleAS SOAP, the mustUnderstand attribute can be either handled in the SOAP handlers or in the service implementation. This is very useful for processing headers (with mustUnderstand set to '1') which have a 'global' use. Examples of such headers/functionality are encryption, digsig, authentication, logging etc.

A.15 Apache Software License, Version 1.1

This program contains third-party code from the Apache Software Foundation (Apache). Under the terms of the Apache license, Oracle is required to provide the following notices. Note, however, that the Oracle program license that accompanied this product determines your right to use the Oracle program, including the Apache software, and the terms contained in the following notices do not change those rights. Notwithstanding anything to the contrary in the Oracle program license, the Apache software is provided by Oracle AS IS and without warranty or support of any kind from Oracle or Apache.

======================================

The Apache Software License, Version 1.1Copyright (c) 2000 The Apache Software Foundation. All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

3. The end-user documentation included with the redistribution, if any, must include the following acknowledgment:

"This product includes software developed by the Apache Software Foundation (http://www.apache.org/)."

Alternately, this acknowledgment may appear in the software itself, if and wherever such third-party acknowledgments normally appear.

4. The names "Apache" and "Apache Software Foundation" must not be used to endorse or promote products derived from this software without prior written permission. For written permission, please contact apache@apache.org.

5. Products derived from this software may not be called "Apache", nor may "Apache" appear in their name, without prior written permission of the Apache Software Foundation.

THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

This software consists of voluntary contributions made by many individuals on behalf of the Apache Software Foundation. For more information on the Apache Software Foundation, please see http://www.apache.org/.

Portions of this software are based upon public domain software originally written at the National Center for Supercomputing Applications, University of Illinois, Urbana-Champaign.