|
Oracle® Application Server Web Services Developer's Guide
10g Release 2 (10.1.2) Part No. B14027-01 |
|
 Previous |
 Next |
|
Oracle® Application Server Web Services Developer's Guide
10g Release 2 (10.1.2) Part No. B14027-01 |
|
|
Previous |
Next |
This appendix covers the following topics:
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:
SOAP Protocol Handling - It provides an implementation of the interoperable SOAP specification. This includes support for Cookies and Sessions which is particularly useful to pass state information for stateful Web Services request/response.
Support for SOAP requests with Attachments (XML Payloads).
Parsing - OracleAS SOAP Processor integrates the Oracle XML Parser. For RPC-style requests, the OracleAS SOAP Processor can efficiently parse the incoming XML document, ensure the request is well-formed, and possibly validate the request. Similarly, it can also encode/serialize a Java response into a SOAP message.
Invoking Web Service Using Customized Web Services Servlet - The SOAP Processor un-marshals the message contents and depending on the Servlet, calls the Web Services implementation. Web Services can be implemented as Java Classes, EJBs, or PL/SQL Stored Procedures.
Engaging a security manager to possibly authenticate the sender - Before invoking the Web Services implementation, the OracleAS SOAP Processor (Servlet) authenticates the user using a standard JAAS-based User Manager plug-in. OracleAS SOAP Processor also supports Oracle's Single Sign-On Server and third-party authentication services to provide single-sign on for Web Services.
Exception Handling - When exceptions occur during processing, the Java Exception is transformed to a SOAP fault and delivered to the service client.
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:
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
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.
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
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.
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.
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
This section covers the following topics related to deploying and undeploying OracleAS SOAP Services:
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. |
Install an OracleAS SOAP Web Service in Oracle Application Server Containers for J2EE (OC4J) by performing the following steps:
Create service and provider deployment descriptors.
Expand the soap.ear file found in $SOAP_HOME/lib on UNIX or %SOAP_HOME\lib on Windows.
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.
Redeploy the updated soap.ear file.
Deploy the provider descriptor by executing the command:
providerMgr.sh deploy FileName
where FileName is the name of the provider descriptor xml file.
Deploy the service by executing the command:
serviceMgr.sh deploy FileName
Where FileName is the name of the service descriptor xml file.
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.
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 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.
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.
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.
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.
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"/>
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:
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
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.
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, Legal values for a Illegal values for a *, 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 138.2.142.154, 138.2.142.*, 138.2.*, 138.* Illegal values for an *, 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. |
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 withincludeRequest 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
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.
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:
HTTP proxies
HTTP authentication (basic RFC 2617)
Proxy authentication (basic RFC 2617)
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 propertyjava.protocol.handler.pkgs must be set as a system property.
|
Table A-6 SOAP HTTP Transport Security Properties
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).
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:
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());
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.
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.
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:
This sample is in $SOAP_HOME/samples/xmethods.
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.
This sample has a service implemented in Java and one client. It is located in $SOAP_HOME/samples/stockquote
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.
This includes a template provider that can be used as a starting point for creating your own provider.
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
This section compares the OracleAS SOAP EJB providers with the Apache-SOAP 2.2 EJB providers.
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.
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.
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.
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.
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:
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
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
Deploy ear file in OC4J. Modify the OC4J specific EJB descriptor to correct the JNDI location for the EJB (as described in sample README).
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.
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
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.
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)
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.
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>
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.
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>
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.
This section lists several techniques for troubleshooting Oracle Application Server Web Services, including:
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
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.
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
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().
This section covers differences between Apache Soap and OracleAS SOAP.
Additional instructions are provided for installing services when OracleAS SOAP is used in conjunction with OC4J.
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.
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.
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 special provider has been added which allows services to be written using PL/SQL Stored Procedures or Functions.
The wsdl2java and java2wsdl scripts simplify building client side code from WSDL descriptions and for generating WSDL descriptions of Java services.
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.
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.
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.
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.
The differences between Apache SOAP and OracleAS SOAP with respect to the handling of the mustUnderstand attribute are the following:
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.
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
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.
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.
