| Oracle® Application Server Advanced Web Services Developer's Guide 10g (10.1.3.1.0) Part Number B28975-02 |
|
|
View PDF |
| Oracle® Application Server Advanced Web Services Developer's Guide 10g (10.1.3.1.0) Part Number B28975-02 |
|
|
View PDF |
Message exchange in Web services can be inherently unreliable. It is not well-suited for long-running conversations in a reliable fashion without additional infrastructure. To use Web services for mission-critical, complex business processes, you must be able to exchange messages reliably. To this end, Oracle Application Server Web Services provides the ability to add quality of service (QOS) guarantees around reliable messaging according to the OASIS WS-Reliability 1.1 specification.
See Also:
http://docs.oasis-open.org/wsrm/ws-reliability/v1.1/wsrm-ws_reliability-1.1-spec-os.pdf for the WS-Reliability 1.1 specification.
WS-Reliability 1.1 is a specification for open, reliable Web service messaging including guaranteed delivery, duplicate message elimination and message ordering, enabling reliable communication between Web services. The reliability features are based on extensions to the Simple Object Access Protocol (SOAP), rather than being tied to the underlying transport protocol. The specification allows a variety of systems to interoperate reliably in a platform- and vendor-neutral manner.
Note:
The Reliability 1.1 specification is different from the WS-Reliable Messaging specification proposed by Microsoft, BEA, IBM, and others. It is also different from the WS-Reliability Exchange (WS-Rx) specification. In the current release, OracleAS Web Services does not support these two specifications.Reliability allows users of the Web services stack to exchange SOAP messages without duplicates and with guaranteed delivery and message ordering. The information that allows messages to be delivered in a reliable fashion is contained in extensions to the SOAP message headers. The SOAP header extensions, the details of the messaging model, and the semantics associated with it are defined by the WS-Reliability specification.
Reliability encompasses the following features.
guaranteed delivery—ensures that a sent message will be received.
duplication elimination—ensures that the receiver will not see any duplicate messages (messages with the same message ID are treated as duplicates).
guaranteed message delivery and duplicate message elimination—ensures that all messages sent will be received, and any duplicate messages will be removed.
message ordering—ensures that a sequence of messages that are sent will be received in the same order.
Enabling reliability on the server enables all of these features. The exercising of the features is driven by the client either through a configuration file or an API.
This chapter contains the following sections.
The following sections describe the requirements you must satisfy before you can use reliable messaging between the server and client.
You can configure reliable messaging such that messages will be stored in the server-side memory store or in a database store. If you choose to use a database store, then a database must be accessible through JNDI from the server before the reliable service is deployed.
To enable reliable messaging, you must install certain SQL tables on both the client and the server. The SQL scripts that install these tables are stored in the j2ee/home/database/webservices/reliability/oracle directory.
clear-tables.sql—can be used to delete all records from the server-side reliability tables. This script is provided as a convenience and should be used only by the database administrator if the tables are in an irreversibly inconsistent state.
drop-tables.sql—can be used to drop all of the client and server reliability tables.
reliability-tables.sql—creates reliability tables on both the client and server. The tables required on the server are RM_SERVER_MESSAGE_INFO and RM_SERVER_GROUP_INFO. The tables required on the client are RM_CLIENT_MESSAGE_INFO and RM_CLIENT_GROUP_INFO. If you are developing only a client or a server, then only its respective table has to be installed.
The scripts can be executed on the command line with the following SQL*Plus command.
sqlplus username/password @sql_script
In this command, username and password are your user name and password for executing SQL scripts; sql_script is the name of the SQL script.
By default, database column widths for fields such as GROUP_ID, REPLY_TO_URL, URL_PATTERN, and ENDPOINT_ADDRESS are set to 150. However, some applications might generate longer names. This is likely to happen if you are working with unusually long URLs or host names. If a generated name is longer than the specified column width, then a database error can be returned.
To avoid this problem, you can modify the reliability-tables.sql script to increase the column widths of the server-side and client-side tables. Example 5-1 illustrates a modified reliability-tables.sql script where the column width of the GROUP_ID, REPLY_TO_URL, URL_PATTERN and ENDPOINT_ADDRESS fields have been increased from 150 to 250.
Example 5-1 reliability-tables.sql with Modified Column Widths
CREATE TABLE RM_SERVER_MESSAGE_INFO ( GROUP_ID varchar(250), SEQUENCE_NUM number, TIMESTAMP number, EXPIRY_TIME number, RETRY_COUNT number, ACK_STATUS varchar(50), PROCESS_STATUS varchar(50), REPLY_TO_URL varchar(250), ENDPOINT_ADDRESS varchar(250), URL_PATTERN varchar(250), REPLY_PATTERN varchar(150), FAULT_CODE varchar(50), LAST_UPDATE number, CONTENT_TYPE varchar(150), SOAP_ACTION varchar(150), MESSAGE BLOB, PIPELINE_CONFIG BLOB, CONSTRAINT RM_SERVER_MESSAGE_INFO_PK PRIMARY KEY (GROUP_ID, SEQUENCE_NUM)); CREATE TABLE RM_SERVER_GROUP_INFO ( GROUP_ID varchar(250) PRIMARY KEY, SEQUENCE_NUM number, LAST_UPDATE number, TIMESTAMP number, GROUP_EXPIRY_TIME number, GROUP_MAX_IDLE number, REPLY_TO_URL varchar(250), ENDPOINT_ADDRESS varchar(250));
To enable reliable messaging, you have to configure it into the Web service on the server side and into the client. The following sections describe how to use the WebServicesAssembler tool to add a reliability configuration to a Web service. A configuration can be added in a top down or bottom up Web service assembly. The tool can also assemble a Web service client. In each case, the configuration is specified in an XML file and passed to the WebServicesAssembler command with the ddFileName argument.
For information on assembling static stub and DII clients that can support reliable messaging, see "How to Configure Reliability on the Client".
Steps to Assemble Reliability into a J2SE Web Service Client Proxy
Steps to Assemble Reliability into a J2EE Web Service Client
The following general steps describe how to assemble a reliability configuration into a Web service bottom up. The Oracle Application Server Web Services Developer's Guide provides complete information on how you can assemble Web services bottom up from Java classes, EJBs, JMS queues, or database resources.
Create the XML file that provides settings for the reliability features.
The file should be based on the oracle-webservices-10_0.xsd schema. Example 5-3 illustrates an XML file that contains a reliability configuration. "Server-Side Reliability Configuration Elements" describes the port-level and operation-level reliability features that are available on the server.
Use the appropriate *Assemble command to assemble the Web service. Use the ddFileName argument to pass the name of the XML file that contains the reliability configuration to the command.
See "Web Service Assembly Commands" in the Oracle Application Server Web Services Developer's Guide for descriptions of the *Assemble commands.
See "ddFileName" in the "Deployment Descriptor Arguments" section of the Oracle Application Server Web Services Developer's Guide for a description of this argument.
If you are also assembling capability assertions into the Web service, use the genQos argument set to true. For more information on capability assertions, see "Working with Capability Assertions".
Example 5-2 illustrates an assemble Ant task that uses the ddFileName argument to add the reliability configuration in wsmBankServiceConfig.xml to the Web service.
Example 5-2 Passing a Reliability Configuration in a Bottom Up Web Service Assembly
<oracle:assemble appName="bank"
targetNamespace="http://www.oracle.com/bank"
typeNamespace="http://www.oracle.com/bank"
serviceName="Banking"
interfaceName="oracle.ws.server.bank.Bank"
className="oracle.ws.server.bank.BankImpl"
input="./build/classes/service"
output="build"
genQos="true"
ear="build/bank.ear"
style="rpc"
use="encoded"
createOneWayOperations="true"
ddFileName="wsmBankServiceConfig.xml"
>
</oracle:assemble>
Example 5-3 illustrates the contents of the wsmBankServiceConfig.xml for a server-side reliability configuration. Note that the contents of the file are enclosed in the <oracle-webservices> element. The reliability configuration is highlighted in bold.
Example 5-3 Sample Server-Side Reliability Configuration
<oracle-webservices xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="oracle-webservices-management-10_0.xsd"
schema-major-version="10" schema-minor-version="0">
<webservice-description name="Banking">
<port-component name="HttpSoap11">
<runtime enabled="reliability">
<reliability>
<repository name="bank-server-store" type="memory"/>
<ack-interval value="60"/>
<order-interval value="60"/>
<cleanup-interval value="10000"/>
<ack-limit value="10"/>
<max-age value="86000"/>
</reliability>
</runtime>
<operations>
<operation name="deposit">
<runtime>
<reliability>
<duplication-elimination-required value="true"/>
<guaranteed-delivery-required value="true"/>
</reliability>
</runtime>
</operation>
</operations>
</port-component>
</webservice-description>
</oracle-webservices>
The following general steps describe how to assemble a reliability configuration into a Web service top down. For a detailed description of top down Web service assembly, see "Assembling a Web Service from a WSDL" in the Oracle Application Server Web Services Developer's Guide.
Provide settings for the reliability features that you want to enable in an XML file.
"Server-Side Reliability Configuration Elements" describes the port-level and operation-level reliability features that are available on the server.
(Optional) Assemble capability assertions into the WSDL for the Web service.
If you are assembling capability assertions into the Web service, you must assemble the assertions into the WSDL before assembling the service. This is described in "How to Assemble Capability Assertions into a Web Service Top Down".
Assemble the Web Service top down by calling the topDownAssemble command.
Use the ddFileName argument to pass the name of the XML file that contains the reliability configuration to the command.
If the WSDL contains capability assertions, use the genQos argument set to true. For more information on capability assertions, see "Working with Capability Assertions".
See "ddFileName" and "genQos" in the "WebServicesAssembler Arguments" section of the Oracle Application Server Web Services Developer's Guide for more information on these arguments.
Example 5-4 illustrates a topDownAssemble Ant task that uses the ddFileName argument to add the reliability configuration in wsmLoggingServiceConfig.xml to the Web service. The ddFileName argument is highlighted in bold.
Example 5-4 Passing a Reliability Configuration in a Top Down Web Service Assembly
<oracle:topDownAssemble
wsdl=" ./wsdl/LoggingFacility.wsdl"
unwrapParameters="false"
className="oracle.demo.topdowndoclit.service.DocLitLoggerImpl"
input="build/classes/service"
output="build"
ear="dist/doclit_topdown.ear"
mappingFileName="type-mapping.xml"
packageName="oracle.demo.topdowndoclit.service"
fetchWsdlImports="true"
classpath="./build/classes/client"
ddFileName="wsmLoggingServiceConfig.xml"
</oracle:topDownAssemble>
If you are assembling a Web service top down and want it to include capability assertions, then you must add the assertions to the WSDL before assembling the service.
The WebServicesAssembler command genQosWsdl allows you to add capability assertions for security and reliability to a specified WSDL. Typically, capability assertions are defined in the deployment descriptor file.
In the genQosWsdl command, use the following arguments:
ddFileName—to specify a deployment descriptor file that contains the server-side reliability configuration elements.
wsdl—to specify the name of the WSDL file into which they will be inserted.
output—to specify where the modified WSDL will be stored. If you do not use this argument, the original WSDL fill be overwritten.
You can then use the modified WSDL as input to the topDownAssemble command. The genQos argument to topDownAssemble must be set to true.
See Also:
See "genQosWsdl" in the Oracle Application Server Web Services Developer's Guide for more information on this command.
The following general steps describe how to assemble a reliability configuration into a J2SE Web service client proxy. The reliability configuration values must be consistent for both the server side and the client side for reliable message communication to occur.
Provide settings for the reliability features that you want to enable in an XML file.
This file can be written by hand or created by a tool, such as Oracle JDeveloper. The configuration file describes some of the built-in behavior of the generated client and is defined by the oracle-webservices-client-10_0.xsd schema. If there are certain quality of service properties marked as "required" (such as duplicate elimination or guaranteed delivery) on the server-side, then the client must also specify these properties.
"Client-Side Reliability Configuration Elements" describes of the port-level and operation-level reliability features that can be set for the client.
Use the genProxy command to assemble the Web service client. Use the ddFileName argument to pass the name of the XML file that contains the reliability configuration to the command.
See "How to Pass Management Information to a J2SE Client" for more detailed information on adding a management configuration to a J2SE client.
"Assembling a J2SE Web Service Client" in the Oracle Application Server Web Services Developer's Guide provides more information on creating J2SE Web service clients.
Example 5-5 illustrates a genProxy Ant task that uses the ddFileName argument to add the reliability configuration in wsmClientDD.xml to the Web service. The ddFileName argument is highlighted in bold.
Example 5-5 Passing a Reliability Configuration in a Web Service Client Assembly
<oracle:genProxy
wsdl="http://localhost:8888/bankdemo/bank?WSDL"
output="test/src"
debug="true"
packageName="oracle.generated"
ddFileName="wsmClientDD.xml"/>
</oracle:genProxy>
Example 5-6 illustrates the contents of the wsmClientDD.xml for a client-side reliability configuration. Note that the contents of the file are enclosed in the <port-info> tag.
Example 5-6 Sample Client-Side Reliability Configuration
... <port-info> <runtime enabled="reliability"> <reliability> <repository name="standalone-client-store" type="memory"/> <retry-interval value="60"/> <cleanup-interval value="10000"/> <poll-interval value="60"/> <retry-limit value="10"/> <max-age value="86000"/> <standalone-listener-port value="9876"/> </reliability> </runtime> <operations> <operation name="deposit"> <runtime> <reliability> <guaranteed-delivery enabled="true"/> <duplicate-elimination enabled="true"/> <group-expiry-time value="860000"/> <reply-pattern value="Callback"/> <reply-to-url value="http://localhost:9876"/> <expiry value="860000"/> </reliability> </runtime> </operation> </operations> </port-info> ...
The following general steps describe how to assemble a reliability configuration into a J2EE Web service client. The reliability configuration values must be consistent for both the server side and the client side for reliable message communication to occur.
Provide settings for the reliability features that you want to enable in an XML file.
This file can be written by hand or created by a tool, such as Oracle JDeveloper. The configuration file describes some of the built-in behavior of the generated client and is defined by the oracle-webservices-client-10_0.xsd schema. If there are certain quality of service properties marked as "required" (such as duplicate elimination or guaranteed delivery) on the server-side, then the client must also specify these properties.
"Client-Side Reliability Configuration Elements" describes the port-level and operation-level reliability features that can be set for the client.
Use the genInterface command to create the Web service client. Pass the reliability configuration to the command with the ddFileName argument.
"How to Assemble a J2EE Web Service Client" in the Oracle Application Server Web Services Developer's Guide provides detailed instructions for creating and packaging the J2EE Web service client.
"How to Pass Management Information to a J2EE Client" for more detailed information on adding a management configuration to a J2EE client.
This section describes the configuration elements for reliability that can be found in the server-side oracle-webservices.xml file.
As with other files that are to be deployed, oracle-webservices.xml is typically stored in an EAR file. Once the EAR is deployed to OracleAS Web Services, the Web services management information in oracle-webservices.xml is extracted and stored in wsmgmt.xml. You can modify the management configuration post-deployment by using the Application Server Control tool.
This section contains the following subsections:
See Also:
"How to Pass Management Information to the Server" for a description of how to add management information, including reliability, to oracle-webservices.xml.
Reliability features can be assigned at the port level and at the operation level.
Note:
Message ordering cannot be configured at the operation level or the port level. It cannot be configured at the operation level because message ordering can take place across operations. It cannot be configured at the port level because you might not want all operations to be reliable or sensitive to message ordering.This section describes the reliability elements that can be set at the port level. The port level configuration determines where messages are stored.
The value of the type attribute in the <repository> element determines whether the server will store messages in-memory or in a database store. If type="memory" then messages are stored in an in-memory store. If type="jdbc" then messages are stored in a database store.
Table 5-1 provides more information on <repository> and other port-level reliability elements that can appear in the oracle-webservices.xml file.
Note:
Theoracle-webservices-reliability-10_0.xsd schema file defines the reliability elements as a sequence. In any reliability configuration, they must appear in order.Table 5-1 Port-Level Reliability Elements in the Server-Side Configuration File
| Element Name | Description |
|---|---|
|
<repository> |
Describes the kind of store that the server will use to store messages. This element has the following attributes:
For a memory store ( For a database store ( |
|
<ack-interval> |
Specifies the interval, in seconds, after which an attempt is made to send acknowledgments or faults for messages that were processing asynchronously. The default value is 60 seconds. |
|
<order-interval> |
The |
|
<cleanup-interval> |
The |
|
<ack-limit> |
The |
|
<max-age> |
The |
Example 5-7 lists the reliability elements as they are used in oracle-webservices.xml to describe reliability for an in-memory store.
Example 5-7 Port-Level Reliability Set for an In-Memory Store
... <port-component name="..."> <runtime enabled="reliability"> <reliability> <repository name="bank-server-store" type="memory"/> <ack-interval value="60"/> <order-interval value="60"/> <cleanup-interval value="3600"/> <ack-limit value="10"/> <max-age value="86400"/> </reliability> </runtime> <operations> ... </port-component>
Example 5-8 lists the reliability elements for a configured datasource on the server.
Example 5-8 Port Level Reliability Set for a Configured Datasource on the Server
... <port-component name="..."> <runtime enabled="reliability"> <reliability> <repository type="jdbc" jndiLocation="jdbc/OracleManagedDS"/> <ack-interval value="60"/> <order-interval value="60"/> <cleanup-interval value="3600"/> <ack-limit value="10"/> <max-age value="86400"/> </reliability> </runtime> <operations> ... </port-component>
This section describes the reliability elements that can be set at the operation level. Example 5-9 lists the reliability elements as they are used in oracle-webservices.xml.
Example 5-9 Operation-Level Reliability Elements in the Server-Side Configuration File
...
<port-component name="...">
...
<operations>
<operation name="deposit">
<runtime>
<reliability>
<duplication-elimination-required value="true"/>
<guaranteed-delivery-required value="true"/>
</reliability>
</runtime>
</operation>
</operations>
</port-component>
...
Table 5-2 describes the reliability elements that you can set at the operation level in the oracle-webservices.xml file. If the values of these assertions are true, but the client does not send the message according to the requirement, then a SOAP fault is returned, describing the assertion that was violated.
Note:
Theoracle-webservices-reliability-10_0.xsd schema file defines the reliability elements as a sequence. In any reliability configuration, they must appear in order.Table 5-2 Operation-Level Reliability Elements in the Server-Side Configuration File
| Element Name | Description |
|---|---|
|
<duplication-elimination-required> |
If set to |
|
<guaranteed-delivery-required> |
If set to |
On the server, capability assertions for reliability are used to restrict the kinds of messages sent to the endpoint. Capability assertions for reliability can be added to the Web service either by Oracle JDeveloper wizards or WebServicesAssembler commands. Table 5-3 describes the capability assertions defined for WS-Reliability.
Table 5-3 Capability Assertions Defined for WS-Reliability
| Reliability Assertion | Description |
|---|---|
|
|
This assertion indicates that only messages that have a duplicate elimination SOAP header element will be processed. Any messages that arrive at the reliable endpoint without the correct SOAP header in the message indicating duplicate elimination will be rejected with a SOAP fault. |
|
|
This assertion indicates that only messages that have a guaranteed delivery SOAP header element will be processed. Any messages that arrive at the reliable endpoint without a SOAP header indicating guaranteed delivery will be rejected with a SOAP fault. |
|
|
This assertion indicates support for various reply patterns. These assertions are explicit advertisements of the capabilities of the endpoint. Clients can use these capabilities to determine how they want to interact with the endpoint. |
You can use the Oracle JDeveloper or WebServicesAssembler tools to add capability assertions to a Web service, or to simply insert the assertions into an existing WSDL. For more information, see "How to Assemble Capability Assertions into a Web Service".
You can configure reliability for a client by using either an API or a configuration file.
The reliability configuration values must be consistent for both the server side and the client side for reliable message communication to occur. This section describes only the client-side configuration elements.
See Also:
"Server-Side Reliability Configuration Elements" for information on server-side reliability elements
On the client, reliability elements are stored in a configuration file. The name of the file and where it resides depends on whether the client is J2EE or J2SE.
For J2EE servlet, EJB, and Web application clients, the configuration file is:
META-INF/orion-ejb-jar.xml for an EJB client
WEB-INF/orion-web.xml for a JSP or servlet client
META-INF/orion-application-client.xml for a Web application client
For J2SE clients, the configuration file is: <generated_name>_Stub.xml, where generated_name is derived from the targetNamespace and port name in the WSDL.
Reliability can be assigned at the port level and at the operation level.
This section describes the reliability elements that can be set at the port level for the client. Example 5-10 lists the reliability elements as they are used in the client-side configuration file.
Example 5-10 Port-Level Reliability Elements in the Client-Side Configuration File
... <port-info> <runtime enabled="reliability"> <reliability> <repository name="standalone-client-store" type="memory"/> <retry-interval value="60"/> <retry-limit value="10"/> <poll-interval value="60"/> <cleanup-interval value="3600"/> <max-age value="86400"/> <standalone-listener-port value="8008"/> <async-poll-reply-to-url value="http://host:port"/> </reliability> </runtime> ... </port-info>
Table 5-4 describes the reliability elements that can be set at the port level.
Note:
Theoracle-webservices-reliability-10_0.xsd schema file defines the reliability elements as a sequence. In any reliability configuration, they must appear in order.Table 5-4 Port-Level Reliability Elements in the Client-Side Configuration File
| Element Name | Description |
|---|---|
|
<repository> |
Specifies the kind of store that will be used to store messages. This element has the following attributes:
|
|
<retry-interval> |
The |
|
<retry-limit> |
The Note: If the |
|
<poll-interval> |
The |
|
<cleanup-interval> |
The |
|
<max-age> |
The |
|
<standalone-listener-port> |
The |
|
<async-poll-reply-to-url> |
The |
This section describes the reliability elements that can be set at the operation level for the client. Example 5-11 lists the reliability elements as they are used in the client-side configuration file.
Example 5-11 Operation-Level Reliability Elements in the Client-Side Configuration File
<port-info>
...
<operations>
<operation name="...">
<runtime>
<reliability>
<guaranteed-delivery enabled="true"/>
<duplicate-elimination enabled="true"/>
<group-max-idle-time value="5"/>
<group-expiry-time value="86400"/>
<expiry value="3600"/>
<reply-pattern value="Callback"/>
<reply-to-url value="http://localhost:8008"/>
</reliability>
</runtime>
</operation>
</operations>
</port-info>
Table 5-5 describes the reliability elements that can be set on the operation level.
You should provide a value for either <group-max-idle-time> or <group-expiry-time>. If both elements are specified, then the value for <group-expiry-time> will take precedence.
Note:
Theoracle-webservices-reliability-10_0.xsd schema file defines the reliability elements as a sequence. In any reliability configuration, they must appear in order.Table 5-5 Operation-Level Reliability Elements in the Client-Side Configuration File
| Element Name | Description |
|---|---|
|
<guaranteed-delivery> |
If the |
|
<duplicate-elimination> |
If the |
|
<group-max-idle-time> |
The |
|
<group-expiry-time> |
The |
|
<expiry> |
The If a value is set for |
|
<reply-pattern> |
The To use The |
|
<reply-to-url> |
The The |
OracleAS Web Services lets you choose whether to store messages sent to the client in memory or in a database. Storing your messages in a database has advantages over storing messages in memory. Messages stored in memory are not persistent: messages are lost once client processes exit (JVM termination) or if the server goes down.
If you choose to store client messages in a database, you must provide the database and connection details to the client. This information cannot be passed to the client by using client-side APIs. Instead, you must provide settings for the port-level <repository> element in the client-side management configuration file. This element is described in Table 5-4.
The following sections describe the tasks involved in configuring the database to store client messages.
How to Configure the Database to Store Messages from a J2SE Client
How to Configure the Database to Store Messages from a J2EE Client
For a J2SE client, you must provide all of the parameters that are required to establish a database connection. This information, such as the name of the database, its URI, connection type, the connection driver, and the user name and password, are all attributes of the repository element. Enter this information into the <generated_name>_Stub.xml file, where generated_name is derived from the target namespace and port name in the WSDL.
Example 5-12 illustrates the configuration of a database connection for a J2SE client. Note that the J2SE client requires all of the repository attributes to connect to the database.
Example 5-12 Database Connection for a J2SE Client
<reliability>
<repository
name="bank-client-store"
type="jdbc"
connection-driver="org.hsqldb.jdbcDriver"
username="SCOTT"
password="TIGER"
url="jdbc:hsqldb:testdb" />
<retry-interval value="60" />
<retry-limit value="10" />
<poll-interval value="60" />
<cleanup-interval value="3600" />
<max-age value="86400" />
<standalone-listener-port value="9999" />
</reliability>
A J2EE client typically interacts with a datasource in an application server. The client connects to the data source by performing a JNDI lookup on its location.
You enter the information into one of the following files, based on your client.
META-INF/orion-ejb-jar.xml for an EJB client
WEB-INF/orion-web.xml for a JSP or servlet client
META-INF/orion-application-client.xml for a Web application client
Datasources used for reliable clients should be configured to use local transactioning. To declare local transactioning, add the attribute tx-level="local" to the <managed-data-source> element. For example:
...
<managed-data-source name="OracleDS" tx-level="local"
jndi-name="jdbc/OracleManagedDS" ...
/>
...
In Example 5-13 the values for the repository attributes type and jndiLocation provide the datasource type and location details to the J2EE client. The repository elements are highlighted in bold.
For a J2EE client where the reliability client runs inside of an application, a Servlet class, oracle.j2ee.ws.reliability.AckFaultServlet, is provided for use in the application.
Example 5-14 illustrates the code that must be added to the application's web.xml file.
Example 5-14 Listener Configuration for a J2EE Client
<servlet>
<servlet-name>wsrm</servlet-name>
<servlet-class>oracle.j2ee.ws.reliability.AckFaultServlet</servlet-class>
<load-on-startup>1</load-on-startup>
</servlet>
<servlet-mapping>
<servlet-name>wsrm</servlet-name>
<url-pattern>/wsrm/*</url-pattern>
</servlet-mapping>
The replyTo URL must be set to the URL to which the AckFaultServlet is mapped. This is in contrast to the J2SE case, where the replyTo URL must correspond to the standalone listener's host:port value.
OracleAS Web Services provides the ability to programmatically configure reliability features and receive notifications for acknowledgments and faults at the application level. This functionality is provided by the oracle.webservices.reliability package, a client-level API for managing reliability features.
The functionality contained in this package lets you override any default configuration, or the configuration that was initially provided to the client.
You must use the API if you want to implement message ordering for your Web service. Currently, using the API is the only way to start and end groups of ordered messages.
You can also use this API if you want to enforce reliability policies on a per-message basis.
Table 5-6 summarizes the classes in the oracle.webservices.reliability package.
See Also:
More detailed information about the classes, such as fields and method-level descriptions, can be found in the Oracle Application Server Web Services Java API Reference.
Table 5-6 Client APIs for Reliability
| Class Name | Description |
|---|---|
|
ReliabilityClient |
The |
|
ReliabilityClientFactory |
This is the factory class for creating a |
|
ReliabilityContext |
The class represents the context for reliable messaging that the client is in. The context can be used to override any default configuration for the client and to add listeners for reliability events. Ordered groups of messages can be started and ended only by using the context (and not by static configuration) as groups have to be determined dynamically. |
|
ReliabilityEvent |
This is an event that is sent to a |
|
ReliabilityListener |
Listener for reliability events (acks/faults). The client can implement a reliability listener and add it to its |
The APIs in the reliability package can be used to create the reliability context for both static stub and DII clients.
The createContext() method in the ReliabilityClient class creates a reliability context. The context is where you can set, among other features, the reliability listeners, message acknowledgment type, duplicate message elimination, guaranteed delivery, message expiration time, and the reply URL.
For a static stub, the reliability context is set on the current thread. All operations invoked on the stub within the scope of a reliability context inherit their reliability characteristics from that context.
For a DII client, the details about the service are passed to the client by URIs.
See Also:
"How to Pass a Management Configuration to a DII Web Service Client Programmatically" for more information on how to pass management details to a DII Web service client.
Example 5-15 illustrates the code to make a stub that is generated by genProxy reliable. In the code sample, a reliability context is created that is used over the lifetime of the client (client.createContext()). The context is set on ThreadContext when it is created. This allows operations on the banking stub to inherit their reliability characteristics from the context.
Reliability is set to return asynchronous acknowledgments of messages received (setAcknowledgmentType). The code guarantees that messages will be delivered (setGuaranteedDeliveryEnabled), and that duplicate messages will be eliminated (setDuplicateEliminationEnabled).
Example 5-15 Reliability Code for a Static Stub Client
ReliabilityClient client= ReliabilityClientFactory.getClientFactory().getClient(); ReliabilityContext reliabilityContext = client.createContext(); reliabilityContext.setAcknowledgmentType(ReliabilityContext.ACKNOWLEDGMENT_TYPE_CALLBACK); reliabilityContext.setDuplicateEliminationEnabled(true); reliabilityContext.setGuaranteedDeliveryEnabled(true); Banking banking = new Banking_Impl(); Bank bank = banking.getBankPort(); bank.deposit(new Deposit("checking", 100));
Example 5-16 illustrates the same client code, but for a DII client. In this case, the service name and deposit details are obtained dynamically with URIs.
Example 5-16 Reliability Code for a DII Client
ReliabilityClient client = ReliabilityContextFactory.getDefault().getClient(); ReliabilityContext reliabilityContext = client.createContext(); reliabilityContext.setAcknowledgmentType(ReliabilityContext.ACKNOWLEDGMENT_TYPE_CALLBACK); reliabilityContext.setDuplicateEliminationEnabled(true); reliabilityContext.setGuaranteedDeliveryEnabled(true); Service service = ServiceFactory.newInstance().createService(new QName("http://oracle.com/test/wsdl","TestService","test") ); Call call = service.createCall(new QName("http://oracle.com/test/wsdl","TestServicePort"), new QName("http://oracle.com/test/wsdl","deposit")); call.setProperty(ClientConstants.CLIENT_CONFIG, new File("wsmClient.xml"));
Example 5-17 illustrates client code that performs message ordering. Like the previous examples, a reliability context is created that is used over the lifetime of the client (reliabilityClient.createContext()). To ensure that messages are received in the same order in which they are sent, embed the code which is capable of sending messages within the startMessageOrdering and endMessageOrdering methods. These methods are highlighted in bold.
Note that for message ordering to work, the methods setDuplicateEliminationEnabled and setGuaranteedDeliveryEnabled must also be present and set to true. These methods are also highlighted in bold.
Example 5-17 Message Ordering on the Client
reliabilityContext = reliabilityClient.createContext();
reliabilityContext.setAcknowledgmentType(ReliabilityContext.ACKNOWLEDGMENT_TYPE_CALLBACK);
reliabilityContext.setDuplicateEliminationEnabled(true);
reliabilityContext.setGuaranteedDeliveryEnabled(true);
reliabilityContext.startMessageOrdering();
Banking banking = new Banking_Impl();
Bank bank = banking.getBankPort();
bank.deposit("Checking", 10.0);
bank.withdraw("Checking", 5.0);
reliabilityContext.endMessageOrdering();
The following sections describe the support for reliability offered by Application Server Control and Oracle JDeveloper.
Application Server Control lets you view, enable, and disable the reliability configuration of a deployed Web service. Once the configuration has been modified and applied, the Web service will run with the new configuration values. Application Server Control can be used to set Web service reliability options on the port and operation level.
You cannot use Application Server Control to view or change the reliability configuration for clients.
The following steps provide a general description of how to deploy a Web service and use Application Server Control to read and modify its reliability configuration.
Deploy the Web service.
Web services are deployed in the standard manner into a running instance of OC4J. See Oracle Containers for J2EE Deployment Guide for more information on deploying Web service EAR files.
Use Application Server Control to configure reliable messaging for the deployed Web service.
Log in to the Application Server Control tool.
Click the Web services tab.
Select the name of the Web service that was deployed.
Click the Administration tab.
Click Enable/Disable features.
Move "Reliability" to the enabled column and click "OK".
The Web service will have reliable messaging enabled.
See Configuring Reliability for a Web Service in the Application Server Control on-line help for more information on this step.
Oracle JDeveloper can be used to develop OracleAS Web Services and client Web service management configuration files. Oracle JDeveloper can aid you in the initial creation of these files or it can be used to add management configuration to existing files.
The "Configure Management and Reliability" wizard helps you configure port and operation level reliability for inbound and outbound SOAP messages.
See Also:
"Port-Level Reliability Elements on the Server" and "Operation Level Reliability Elements on the Server" describes the reliability elements that the wizard enables you to configure.
For more information on:
adding Web service management information, including security, to a Web service, see Chapter 3, "Managing Web Services".
adding security information to a Web service, see Chapter 4, "Ensuring Web Services Security" and the Oracle Application Server Web Services Security Guide.
adding auditing and logging information to a Web Service, see Chapter 6, "Auditing and Tracing Messages".
the contents of the wsmgmt.xml file which contains the security configuration, see Appendix A, "Understanding the Web Services Management Schema".
assembling a Web service top down, see "Assembling a Web Service from a WSDL" in the Oracle Application Server Web Services Developer's Guide.
using Java classes to assemble a Web service, see "Assembling a Web Service with Java Classes" in the Oracle Application Server Web Services Developer's Guide.
using EJBs to assemble a Web service, see "Assembling a Web Service with EJBs" in the Oracle Application Server Web Services Developer's Guide.
using JMS topics and destinations to assemble a Web service, see "Assembling Web Services with JMS Destinations" in the Oracle Application Server Web Services Developer's Guide.
using database resources, such as PL/SQL packages, SQL queries, DML statements, Oracle Streams AQ, or server-side Java classes, to assemble a Web service, see "Assembling Database Web Services" in the Oracle Application Server Web Services Developer's Guide.
assembling a J2EE Web Service client, see "Assembling a J2EE Web Service Client" in the Oracle Application Server Web Services Developer's Guide.
assembling a J2SE Web service client, see "Assembling a J2SE Web Service Client" in the Oracle Application Server Web Services Developer's Guide.
the contents of the oracle-webservices.xml deployment descriptor which contains the Web services management configuration, see "Packaging and Deploying Web Services" in the Oracle Application Server Web Services Developer's Guide.
using WebServicesAssembler commands to assemble Web service artifacts, see "Using WebServicesAssembler" in the Oracle Application Server Web Services Developer's Guide.
