Oracle® Application Server Advanced Web Services Developer's Guide 10g (10.1.3.1.0) Part Number B28975-02 |
|
|
View PDF |
This appendix describes the Oracle Application Server Web Services reliability configuration elements defined by the reliability schema oracle-webservices-reliability-10_0.xsd
. The schema can be found in the oc4j-schemas.jar
file.
OC4J_HOME
\j2ee\home\lib\oc4j-schemas.jar
OC4J_HOME
represents the directory where you installed Oracle Containers for J2EE (OC4J).
The reliability elements are typically used as part of a larger Web services management configuration. To enable reliable messaging, you have to configure it into the Web service on the server side and into the client. The configuration is part of an XML configuration file that is passed to the Web service or client when it is assembled.
For the server, the configuration is stored in the oracle-webservices.xml
deployment descriptor file. This file is based on the oracle-webservices-10_0.xsd
schema.
For the client, the configuration is stored in the <
generated_name
>_Stub.xml
deployment descriptor file. This file is based on the oracle-webservices-client-10_0.xsd
schema.
If there are certain reliability properties marked as "required" (such as duplicate elimination or guaranteed delivery) on the server-side, then the client must also specify these properties.
Reliability elements can be set at the port level and at the operation level.
For more information about assembling reliability into a Web service and client, see Chapter 5, "Ensuring Web Service Reliability".
Here is an overview of the element hierarchy for reliability elements defined in the oracle-webservices-reliability-10_0.xsd
schema file for reliability. Different elements can appear on the port and the operation 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.Server-Side Port-Level Hierarchy:
<reliability> <repository> <ack-interval> <order-interval> <cleanup-interval> <ack-limit> <max-age>
Server-Side Operation-Level Hierarchy:
<reliability> <duplication-elimination-required> <guaranteed-delivery-required>
Client-Side Port Level Hierarchy:
<reliability> <repository> <retry-interval> <retry-limit> <poll-interval> <cleanup-interval> <max-age> <standalone-listener-port> <async-poll-reply-to-url>
Client-Side Operation-Level Hierarchy:
<reliability> <guaranteed-delivery> <duplicate-elimination> <group-max-idle-time> <group-expiry-time> <expiry> <reply-pattern> <reply-to-url>
This section is an alphabetical dictionary of the reliability elements that can be specified as part of a Web service management configuration. Reliability elements can be configured for the server and the client at the port level and the operation level. See the preceding section, "Hierarchy of a Reliability Configuration" if you are interested in the hierarchy.
Parent element: <reliability>
Child element: None
Required? Optional
Server or Client? Server
Port or Operation? Port
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.
Parent element: <reliability>
Child element: None
Required? Optional
Server or Client? Server
Port or Operation? Port
The value
attribute specifies a limit on the number of attempts that will be made to acknowledge a message. The default value is -1. This indicates no-limit, or an infinite number of acknowledgment attempts. A value of 0 indicates no acknowledgment attempts.
Parent element: <reliability>
Child element: None
Required? Optional
Server or Client? Client
Port or Operation? Port
The value
attribute specifies the URL to which acknowledgments and faults will be sent if asynchronous polling is desired. The URL for this is typically the host name of the client along with the port that the listener is on.
Parent element: <reliability>
Child element: None
Required? Optional
Server or Client? Both
Port or Operation? Port
Server:
The value
attribute specifies the interval, in seconds, after which an attempt is made to purge the store of expired or invalid messages. The default is 3600 seconds (60 minutes).
Client:
The value
attribute specifies the interval, in seconds, after which an attempt is made to purge the store of expired or invalid messages. The default is 3600 seconds (60 minutes).
Parent element: <reliability>
Child element: None
Required? Required
Server or Client? Client
Port or Operation? Operation
If the enabled
attribute is true
, duplicate elimination of the message is enabled. Default value is true
.
Parent element: <reliability>
Child element: None
Required? Required
Server or Client? Server
Port or Operation? Operation
If set to true
, it indicates that non-reliable clients will not be allowed to invoke this operation. Specifically messages that do not have the SOAP header for duplicate elimination will be rejected. The default is false
.
Parent element: <reliability>
Child element: None
Required? Optional
Server or Client? Client
Port or Operation? Operation
The value
attribute specifies the expiry time for a single message in a group. For example, if a message has not been acknowledged for a time duration longer than the expiration duration, then no further attempt will be made to deliver the message. The client will be notified of the failure.
If a value is set for <group-expiry-time>
, it should be greater than the value of <expiry>
. Default value is 3600 seconds (60 minutes).
Parent element: <reliability>
Child element: None
Required? Optional
Server or Client? Client
Port or Operation? Operation
The value
attribute specifies the expiration time, in seconds, for all messages in the group. The value for <group-expiry-time>
should be greater than the value set for <expiry>
. Default value is 84600 seconds (1 day).
Parent element: <reliability>
Child element: None
Required? Optional
Server or Client? Client
Port or Operation? Operation
The value
attribute specifies the maximum idle time, in seconds, for a group of messages. This element is not required to be present.
Parent element: <reliability>
Child element: None
Required? Required
Server or Client? Client
Port or Operation? Operation
If the enabled
attribute is true
, guaranteed delivery of message is enabled. Default value is true
.
Parent element: <reliability>
Child element: None
Required? Required
Server or Client? Server
Port or Operation? Operation
If set to true
, it indicates that non-reliable clients will not be allowed to invoke this operation. Specifically, messages that do not have the SOAP header for guaranteed delivery will be rejected. The default is false
.
Parent element: <reliability>
Child element: None
Required? Optional
Server or Client? Both
Port or Operation? Port
Server:
The value
attribute specifies the maximum time the user would want the message to be stored. The default value is 86400 seconds (1 day).
Client:
The value
attribute specifies the maximum time the user would want the message to be stored. The default value is 86400 seconds (1 day).
Parent element: <reliability>
Child element: None
Required? Optional
Server or Client? Server
Port or Operation? Port
The value
attribute specifies the interval, in seconds, after which the unordered messages are processed. The default is 60 seconds.
Parent element: <reliability>
Child element: None
Required? Optional
Server or Client? Client
Port or Operation? Port
The value
attribute specifies the interval, in seconds, after which a poll message will be sent to the server for reliable messages that have not yet received any acknowledgment. Default value is 60 seconds.
Parent element: root element for reliability configuration
Child elements:
Server, port level: <ack-interval>, <ack-limit>, <cleanup-interval>, <max-age>, <order-interval>, <repository>
Server, operation level: <duplication-elimination-required>, <guaranteed-delivery-required>
Client, port level: <async-poll-reply-to-url>, <cleanup-interval>, <max-age>, <poll-interval>, <repository>, <retry-interval>, <retry-limit>, <standalone-listener-port>
Client, operation level: <duplicate-elimination>, <expiry>, <group-expiry-time>, <group-max-idle-time>, <guaranteed-delivery>, <reply-pattern>, <reply-to-url>
Required? Required to delimit a reliability configuration
Server or Client? Both
This element delimits the start and end of a reliability configuration.
Parent element: <reliability>
Child element: None
Required? Required
Server or Client? Client
The value
attribute can be either Callback
(asynchronous acknowledgment/fault), Response
(synchronous acknowledgment/fault) or Polling
(the acknowledgment or fault will be polled for). Default value is Polling
.
To use Callback
, you must configure a listener. This is not possible on a J2SE client.
The <reply-pattern>
element must be set only if <guaranteed-delivery>
is true
. See "<guaranteed-delivery>".
Parent element: <reliability>
Child element: None
Required? Optional
Server or Client? Client
The value
attribute specifies the URL to which acknowledgments and faults will be sent for messages that want asynchronous acknowledgments. The URL for this is typically the host name of the client along with the port that the listener is on.
The <reply-to-url>
element must be set only if <guaranteed-delivery>
is true
. See "<guaranteed-delivery>".
Parent element: <reliability>
Child element: None
Required? Required
Server or Client? Both
Server:
Describes the kind of store that the server will use to store messages.
For a memory store (memory
), name
is a required attribute. If the store with that name has been configured for another application in the server, then that store will be used. Otherwise a new store will be configured.
For a database store (jdbc
), a datasource must be configured on the server and its location specified by jndiLocation
.
Table C-1 <repository> Attributes, Server-Side
Name | Description |
---|---|
jndiLocation |
Values: string Default: n/a (Required if Specifies the JNDI name of the datasource on the server. Required only if messages will be stored in the database. |
name |
Values: string Default: n/a A |
type |
Values: Default: Determines the type of store being configured. The allowed values for |
Client:
Describes the kind of store that will be used to store messages.
Table C-2 <repository> Attributes, Client-Side
Name | Description |
---|---|
connection-driver |
Values: string Default: n/a the JDBC driver class name for this data source, used by some data sources that deal with |
jndiLocation |
Values: string Default: n/a Specifies the JNDI name of the datasource on the server. Required only if messages will be stored in the database. |
name |
Values: string Default: n/a A |
password |
Values: string Default: n/a Specifies the user's password to the repository. |
type |
Values: Default: Determines the type of store being configured. The allowed values for If If |
url |
Values: string Default: n/a Specifies the URL for database connections. |
username |
Values: string Default: n/a Specifies the name of the user that can access the repository. |
Parent element: <reliability>
Child element: None
Required? Optional
Server or Client? Client
The value
attribute specifies the interval after which an attempt will be made to retry sending of messages that have not yet received any acknowledgment or fault. The default value is 60 seconds.
Parent element: <reliability>
Child element: None
Required? Optional
Server or Client? Client
The value
attribute specifies a limit on the number of attempts that will be made to retry a message. The default value is 10. A value of -1 indicates no -limit, or infinite retries.
Note:
If thevalue
attribute is set to 0, then the client will not attempt to re-send messages. This, in effect, negates the guaranteed delivery quality of service. As an optimization, the reliability stack does retain messages in the database if the value
attribute is set to 0. No polling will be performed for these messages since no guarantee can be made that the message will reach the destination and an acknowledgment returned.Parent element: <reliability>
Child element: None
Required? Optional
Server or Client? Client
The value
attribute specifies the port at which a listener will be started for receiving acknowledgments or faults. This is used for J2SE clients where there is no infrastructure to which acknowledgments can be sent. If the client is in a J2EE application, then a supplied servlet can be used.
You can find sample reliability configurations for a Web service and client in Chapter 5, "Ensuring Web Service Reliability".