| Oracle® Application Server Advanced Web Services Developer's Guide 10g Release 3 (10.1.3) B25603-01 |
|
 Previous |
 Next |
| Oracle® Application Server Advanced Web Services Developer's Guide 10g Release 3 (10.1.3) B25603-01 |
|
Previous |
Next |
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, more 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. The facility provided is that of the OASIS standard. You can find the specification at the following Web site:
http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=wsrm
WS-Reliability 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.
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 running on 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 steps provide a general outline and a "quick start" of how you can enable reliable messaging. For more detailed description, see "WebServicesAssembler Support for Web Service Reliability".
Server side:
On the server-side there are two ways to enable reliable messaging in a Web service. One way is to provide a reliability configuration in a deployment descriptor and assemble it into the Web service. The sections "Assembling Reliability into a Web Service Bottom Up" and "Assembling Reliability into a Web Service Top Down" describes this technique.
The second technique is to use the Application Server Control tool to configure reliable messaging for the Web service after it is deployed. This technique is described in the following steps.
Deploy the Web service.
Web services are deployed in the standard manner into a running instance of OC4J. For more information on deploying Web service EAR files, see the Oracle Containers for J2EE Deployment Guide.
If you have access to the Application Server Control tool, you can use it to configure reliable messaging on the server-side. For more information, see the topic "Configuring Reliability for a Web Service" in the Application Server Control on-line help.
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.
Client Side:
To enable reliable messaging on the client, assemble a reliability configuration into the client proxy. The settings that you choose for the reliability elements in the client side must agree with the reliability settings for the server.
Create a client deployment descriptor file that includes the configuration elements for reliability.
"Client-Side Reliability Configuration Elements" describes the reliability elements that can be included in the client-side configuration file. The configuration file describes some of the built-in behavior of the generated client and is based on 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), then the client must also specify these properties.
The configuration file can be written by hand or created by a tool, such as JDeveloper.
Assemble the client proxy using the WebServicesAssembler command line or ant-tasks.
Use the genProxy command to generate the Web service client. Specify the name of the WSDL with the wsdl argument and the name of the file that contains the reliability configuration with the ddFileName argument. "Assembling Reliability into a J2SE Web Service Client Proxy" provides more information on assembling reliability into Web service clients.
The client stubs will have reliability enabled and are ready to be used by client code.
This section describes the configuration elements for reliability that can be found in the server-side oracle-webservices.xml file. For a description of how you can add management information, including reliability, to oracle-webservices.xml, see "Configuring Server-Side Management Information".
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.
Reliability features 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. 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.
Table 5-1 Port-Level Reliability Elements in the Server-Side Configuration File
| Element Name | Description |
|---|---|
|
<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. |
|
<ack-limit> |
The |
|
<cleanup-interval> |
The |
|
<max-age> |
The |
|
<order-interval> |
The |
|
<repository> |
Describes the kind of store that the server will use to store messages. The value of the
|
Example 5-2 lists the reliability elements as they are used in oracle-webservices.xml to describe reliability for an in-memory store.
Example 5-2 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-4 lists the reliability elements for a configured datasource on the server.
Example 5-3 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-4 lists the reliability elements as they are used in oracle-webservices.xml.
Note that since message ordering can take place across operations, it cannot be set at this level. It also cannot be set at the port level because you might not want all operations to be reliable or sensitive to message ordering.
Example 5-4 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 assertions 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.
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 side, capability assertions can specify the reliable capabilities of the Web service. For reliability, capability assertions restrict the kind of messages sent to the endpoint.
Capability assertions for reliability can be added to the Web service either by JDeveloper wizards or WebServicesAssembler commands. In JDeveloper, the Web service management configuration wizard contains a "Capability Assertions" option.
In WebServicesAssembler, when you are assembling a Web service top down, use the genQosWsdl command to add capability assertions to the WSDL. Use the following arguments to the genQosWsdl command.
use the wsdl argument to specify a WSDL
set the genQos argument to true
set the ddFileName argument to an oracle-webservices.xml deployment descriptor that contains the server-side reliability configuration elements
When you are assembling a Web service bottom up, use the appropriate *Assemble command to add capability assertions to the WSDL. Use the following arguments to the *Assemble command.
set the genQos argument to true to indicate that capability assertions will be added to the WSDL
set the ddFileName argument to an oracle-webservices.xml deployment descriptor that contains the server-side reliability configuration elements
Port-Level Reliability Elements on the Server and "Operation Level Reliability Elements on the Server" describe the elements that can be used in the oracle-webservices.xml deployment descriptor.
"Working with Capability Assertions" provides an overview of working with capability assertions.
Example 5-3 describes the capability assertion elements 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 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. |
|
|
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. |
Example 5-5 provides an excerpt from a generated WSDL with capability assertions tags generated into it. You can edit the generated values in the WSDL to change their affect. If you edit the WSDL, then you will have to regenerate the endpoint and any clients.
Example 5-5 WSDL Fragment, Containing Capability Assertions for Reliability
... <binding name="HttpSoap11Binding" type="tns:Bank"> <soap:binding style="rpc" transport="http://schemas.xmlsoap.org/soap/http"/> <operation name="deposit"> <soap:operation soapAction="http://www.oracle.com/bank/deposit"/> <capability-assertions wsdl:required="true"> <guaranteed-delivery required="true"> <reply-patterns callback="true" poll="true" response="true"/> </guaranteed-delivery> <duplicate-elimination required="true"/> </capability-assertions> <input> <soap:body use="encoded" namespace="http://www.oracle.com/bank" encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" parts="accountName amount"/> </input> </operation> </binding> ...
Clients can manage reliability by using either an API or a configuration file.
Reliability must be configured for both the server side and the client side for reliable message communication to occur. This section describes only the client-side configuration elements. For information on the server-side elements, see "Server-Side Reliability Configuration 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-6 lists the reliability elements as they are used in the client-side configuration file.
Example 5-6 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"/> <cleanup-interval value="3600"/> <poll-interval value="60"/> <retry-limit value="10"/> <max-age value="86400"/> <standalone-listener-port value="8008"/> </reliability> </runtime> ... </port-info>
Table 5-4 describes the reliability elements that can be set at the port level.
Table 5-4 Port-Level Reliability Elements in the Client-Side Configuration File
| Element Name | Description |
|---|---|
|
<async-poll-reply-to-url> |
The |
|
<cleanup-interval> |
The |
|
<max-age> |
The |
|
<poll-interval> |
The |
|
<repository> |
Specifies the kind of store that will be used to store messages. The
|
|
<retry-interval> |
The |
|
<retry-limit> |
The Note: If the |
|
<standalone-listener-port> |
The |
This section describes the reliability elements that can be set at the operation level for the client. Example 5-7 lists the reliability elements as they are used in the client-side configuration file.
Example 5-7 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-expiry-time value="86400"/>
<reply-pattern value="Callback"/>
<reply-to-url value="http://localhost:8008"/>
<expiry value="3600"/>
</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.
Table 5-5 Operation-Level Reliability Elements in the Client-Side Configuration File
| Element Name | Description |
|---|---|
|
<duplicate-elimination> |
If the |
|
<expiry> |
The If a value is set for |
|
<group-expiry-time> |
The |
|
<group-max-idle-time> |
The |
|
<guaranteed-delivery> |
If the |
|
<reply-pattern> |
The 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. Messages stored in memory are not persistent: if the server goes down, the messages are lost.
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 the 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.
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. You 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-8 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-8 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-9 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-10 illustrates the code that must be added to the application's web.xml file.
Example 5-10 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 dynamically 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 describes the classes in the oracle.webservices.reliability package. More detailed information about the classes, such as fields and method-level descriptions, can be found in the output of the Javadoc tool.
Table 5-6 Client APIs for Reliability
| Class Name | Description |
|---|---|
|
ReliabilityClientFactory |
This is the factory class for creating a |
|
ReliabilityClient |
The |
|
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. "Providing Dynamic Configuration for a DII Web Service Client" provides more information on how to pass management details to a DII Web service client.
Example 5-11 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-11 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-12 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-12 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.WSM_INTERCEPTOR_PIPELINE_CONFIG, new File("wsmClient.xml"));
Example 5-13 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-13 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 JDeveloper.
This section describes how to use WebServicesAssembler commands to add a reliability configuration to a Web service. A configuration can be added in a top down or bottom up Web service assembly. A Web service client can also be assembled in this way. In each case, the configuration is specified in an XML file and passed to the WebServicesAssembler command with the ddFileName argument.
The following general steps describe how to assemble a reliability configuration into a Web service bottom up.
Create the XML file that provides settings for the reliability features.
"Server-Side Reliability Configuration Elements" describe 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.
"Web Service Assembly Commands" in the Oracle Application Server Web Services Developer's Guide provides more information on the commands that can assemble a Web service bottom up. See "ddFileName" in the "Deployment Descriptor Arguments" section of the Oracle Application Server Web Services Developer's Guide for more information on this argument.
Example 5-14 illustrates an assemble Ant task that uses the ddFileName argument to add the reliability configuration in wsmBankServiceConfig.xml to the Web service.
Example 5-14 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"
ear="build/bank.ear"
style="rpc"
use="encoded"
createOneWayOperations="true"
ddFileName="wsmBankServiceConfig.xml"
>
</oracle:assemble>
Example 5-15 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> tag. The reliability configuration is highlighted in bold.
Example 5-15 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="false"/>
<guaranteed-delivery-required value="false"/>
</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.
Provide settings for the reliability features that you want to enable in an XML file.
"Server-Side Reliability Configuration Elements" describe the port-level and operation-level reliability features that are available on the server.
Use the topDownAssemble 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.
"Assembling a Web Service from a WSDL" in the Oracle Application Server Web Services Developer's Guide provides more information about the topDownAssemble command and assembling a Web service top down. See "ddFileName" in the "Deployment Descriptor Arguments" section of the Oracle Application Server Web Services Developer's Guide for more information on the ddFileName argument.
Example 5-16 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-16 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>
The following general steps describe how to assemble a reliability configuration into a J2SE Web service client proxy.
Provide settings for the reliability features that you want to enable in an XML file.
"Client-Side Reliability Configuration Elements" describe 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.
"Configuring Management Information for a J2SE Client" provides 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-17 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-17 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-18 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-18 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.
Provide settings for the reliability features that you want to enable in an XML file.
"Client-Side Reliability Configuration Elements" describe the port-level and operation-level reliability features that can be set for the client.
Use the genInterface command to assemble 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 the J2EE Web service client.
"Configuring Management Information for a J2EE Client" provides more detailed information on adding a management configuration to a J2EE client.
Application Server Control can read and modify 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.
On the server-side, Application Server Control only lets you view, enable, and disable reliability arguments. You cannot view or change any values for clients.
JDeveloper can be used to develop OracleAS Web Services and client Web service management configuration files. 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. Options in the wizard allow you to configure all of the reliability elements described in "Port-Level Reliability Elements on the Server" and "Operation Level Reliability Elements on the Server".
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 Logging 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.
