C OracleAS Web Services Reliability Schema

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".

Hierarchy of a Reliability Configuration

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:

The oracle-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>

Element and Attribute Descriptions for the Reliability Schema

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.

<ack-interval>

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.

<ack-limit>

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.

<async-poll-reply-to-url>

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.

<cleanup-interval>

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).

<duplicate-elimination>

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.

<duplication-elimination-required>

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.

<expiry>

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).

<group-expiry-time>

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).

<group-max-idle-time>

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.

<guaranteed-delivery>

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.

<guaranteed-delivery-required>

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.

<max-age>

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).

<order-interval>

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.

<poll-interval>

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.

<reliability>

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.

<reply-pattern>

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>".

<reply-to-url>

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>".

<repository>

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

Name	Description
jndiLocation	Values: string Default: n/a (Required if `type=jdbc`) 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 `String` that specifies the name of the repository.
type	Values: `memory\|jdbc` Default: `memory` Determines the type of store being configured. The allowed values for `type` are `memory` for a memory store and `jdbc` for a database store. The default is `memory`.

jndiLocation

Values: string

Default: n/a (Required if type=jdbc)

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 String that specifies the name of the repository.

type

Values: memory|jdbc

Default: memory

Determines the type of store being configured. The allowed values for type are memory for a memory store and jdbc for a database store. The default is memory.

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 `java.sql.Connection`. For most data sources, the driver is `oracle.jdbc.driver.OracleDriver`. This attribute applies only to emulated data sources for which the class attribute is `com.evermind.sql.DriverManagerDataSource`.
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 `String` that specifies the name of the repository.
password	Values: string Default: n/a Specifies the user's password to the repository.
type	Values: `memory\|jdbc` Default: `memory` Determines the type of store being configured. The allowed values for `type` are `memory` for a memory store and `jdbc` for a database store. The default type of store is a `memory` store. If `memory` is specified, then `name` is a required attribute. If a store with the same name has been configured for another server application, then that store will be used. If it has not, then a new store will be configured. If `jdbc` is specified, then you must provide database support on the client side. For a J2EE client, a data source must be configured and its location specified with `jndiLocation`.
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.

<retry-interval>

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.

<retry-limit>

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 the value 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.

<standalone-listener-port>

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.

Reliability Configuration Listing

You can find sample reliability configurations for a Web service and client in Chapter 5, "Ensuring Web Service Reliability".