21 Managing Web Service Persistence

This chapter describes how to manage persistence for WebLogic web services using Java API for XML Web Services (JAX-WS).

This chapter includes the following sections:

• Overview of Web Service Persistence

• Roadmap for Configuring Web Service Persistence

• Configuring Web Service Persistence

• Using Web Service Persistence in a Cluster

• Cleaning Up Web Service Persistence

Overview of Web Service Persistence

WebLogic Server provides a default web service persistence configuration that provides a built-in, high-performance storage solution for web services. Web service persistence is used by the following advanced features to support long running requests and to survive server restarts:

• Asynchronous web service invocation using asynchronous client transport or Make Connection

• Web services reliable messaging

• Message buffering

• Security using WS-SecureConversation

Specifically, web service persistence is used to save the following types of information:

• Client identity and properties

• SOAP message, including its headers and body

• Context properties required for processing the message at the web service or client (for both asynchronous and synchronous messages)

The following figure illustrates an example web service persistence configuration.

Figure 21-1 Example Web Service Persistence Configuration

Description of "Figure 21-1 Example Web Service Persistence Configuration"

The following table describes the components of web service persistence, shown in the previous figure.

Table 21-1 Components of the Web Service Persistence

Component	Description
Logical Store	Provides the configuration requirements and connects the web service to the physical store and buffering queue.
Physical store	Handles the I/O operations to save and retrieve data from the physical storage (such as file, DBMS, and so on). The physical store can be a WebLogic Server persistent store, as configured using the WebLogic Server Administration Console or WLST, or in-memory store. Note: When using a WebLogic Server persistent store as the physical store for a logical store, the names of the request and response buffering queues are taken from the logical store configuration and not the buffering configuration.
Buffering queue	Stores buffered requests and responses for the web service.

When configuring web service persistence, you associate:

• A logical store with a buffering queue.

• A buffering queue that is associated with a physical store via JMS configuration.

The association between the logical store and buffering queue is used to infer the association between the logical store and physical store. The default logical store is named WseeStore and is created automatically when a domain is created using the WebLogic Advanced Web Services for JAX-WS Extension template (wls_webservice_jaxws.jar). By default, the physical store that is configured for the server is associated with the buffering queue. This strategy ensures that the same physical store is used for all web service persistence and buffering. Using a single physical store ensures a more efficient, single-phase XA transaction and facilitates migration.

You can configure one or more logical stores for use within your application environment. In Table 21-1, the servers Server1 and Server2 use the same logical store. This configuration allows applications that are running in a cluster to be configured globally to access a single store name. As described later in Configuring Web Service Persistence, you can configure web service persistence at various levels for fine-grained management. Best practices are provided in Roadmap for Configuring Web Service Persistence.

Roadmap for Configuring Web Service Persistence

Table 21-2 provides best practices for configuring web service persistence to support web service reliable messaging.

Table 21-2 Roadmap for Configuring Web Service Persistence

Best Practice	Description
Define a logical store for each administrative unit (for example, business unit, department, and so on).	By defining separate logical stores, you can better manage the service-level agreements for each administrative unit. For more information, see Configuring the Logical Store.
Use the correct logical store for each client or service related to the administrative unit.	You can configure the logical store at the WebLogic Server, web service, or web service client level. For more information, see Configuring Web Service Persistence.
Define separate physical stores and buffering queues for each logical store.	For more information, see Figure 21-1.

The best practices defined in Table 21-2 facilitates maintenance, and failure recovery and resource migration.

For example, assume Company X is developing web services for several departments, including manufacturing, accounts payable, accounts receivable. Following best practices, Company X defines a minimum of three logical stores, one for each department.

Furthermore, assume that the manufacturing department has a service-level agreement with the IT department that specifies that it can tolerate system outages that are no longer than a few minutes in duration. The accounts payable and receivable departments, on the other hand, have a more relaxed service-level agreement, tolerating system outages up to one hour in duration. If the systems that host web services and clients for the manufacturing department become unavailable, the IT department is responsible for ensuring that any resources required by those web services and clients are migrated to new active servers within minutes of the failure. Because separate logical stores were defined, the IT department can migrate the file store, JMS servers, and so on, associated with the manufacturing department logical store independently of the resources required for accounts payables and receivables.

Configuring Web Service Persistence

The following table summarizes the information that you can configure for each of the web service persistence components.

Table 21-3 Summary of the Web Service Persistence Component Configuration

Component	Summary of Configuration Requirements
Logical Store	You configure the following information for each logical store: Name of the logical store. Maximum lifetime of an object in the store. The cleaner thread that removes stale objects from the store. For more information, see Cleaning Up Web Service Persistence. Accessibility from other servers in a network. Request and response buffering queues. The request buffering queue is used to infer the physical store by association.
Physical store	You configure the following information for the physical store: Name of the physical store. Type and performance parameters. Location of the store. Note: You configure the physical store or buffering queue, but not both. If the buffering queue is configured, then the physical store information is inferred.
Buffering queue	You configure the following information for the buffering queue: Request and response queue details Retry counts and delays

You can configure web service persistence at the levels defined in the following table.

Table 21-4 Configuring Web Service Persistence

Level	Description
WebLogic Server	The web service persistence configured at the server level defines the default configuration for all web services and clients running on that server. To configure web service persistence for WebLogic Server, use one of the following methods: When creating or extending a domain using Configuration Wizard, you can apply the WebLogic Advanced Web Services for JAX-WS Extension template (wls_webservice_jaxws.jar) to configure automatically the resources required to support web services persistence. Although use of this extension template is not required, it makes the configuration of the required resources much easier. Configure the resources required for web service persistence using the Oracle WebLogic Server Administration Console or WLST. For more information, see: - WebLogic Server Administration Console: Configure web service persistence in Oracle WebLogic Server Administration Console Online Help - WLST: Configuring Existing Domains in Understanding the WebLogic Scripting Tool For more information, see Configuring Your Domain For Advanced Web Services Features.
Web service endpoint	Configure the default logical store used by the web service endpoint, as described in Configuring Web Service Persistence for a Web Service Endpoint.
Web service client	Configure the default logical store used by the web service client, as described in Configuring Web Service Persistence for Web Service Clients.

The following sections provide more information about configuring web service persistence:

• Configuring the Logical Store

• Configuring Web Service Persistence for a Web Service Endpoint

• Configuring Web Service Persistence for Web Service Clients

Configuring the Logical Store

You can configure one or more logical stores for use within your application environment, and identify the logical store that is used as the default.

The default logical store, WseeStore, is generated automatically when you create or extend a domain using the WebLogic Advanced Web Services for JAX-WS Extension template (wls_webservice_jaxws.jar), as described in Configuring Your Domain For Advanced Web Services Features.

You can configure the logical store using the WebLogic Server Administration Console, see Configure web service persistence in Oracle WebLogic Server Administration Console Online Help. Alternatively, you can use WLST to configure the resources. For information about using WLST to extend the domain, see Configuring Existing Domains in Understanding the WebLogic Scripting Tool.

The following table summarizes the properties that you define for the logical store.

Table 21-5 Configuration Properties for the Logical Store

Property	Description
Default Logical Store Name	Name of the logical store. The name must begin with an alphabetical character and can contain alphabetical characters, spaces, dashes, underscores, and numbers only. This field defaults to LogicalStore_n. This field is required. If you create or extend a single server domain using the web service extension template, a logical store named WseeStore is created by default.
Default Logical Store	Flag that specifies whether the logical store is used, by default, to persist state of all web services on the server. Only one logical store can be set as the default. If you enable this flag on the current logical store, the flag is disabled on the current default store.
Persistence strategy	Persistence strategy. Select one of the following values from the drop-down menu. Local Access Only—Accessible to the local server only. In Memory—Accessible by the local VM only. In this case, the buffering queue and physical store configuration information is ignored.
Request Buffering Queue JNDI Name	JNDI name for the request buffering queue. The request buffering queue is used to infer the physical store by association. If this property is not set, then the default physical store that is configured for the server is used. Note: You configure the physical store or buffering queue, but not both. If the buffering queue is configured, then the physical store information is inferred. It is recommended that the same physical storage resource be used for both persistent state and message buffering to allow for a more efficient, single-phase XA transaction and facilitate service migration. By setting this value, you ensure that the buffering queue and physical store reference the same physical storage resource. If you create or extend a domain using the web service extension template, a buffering queue named weblogic.wsee.BufferedRequestQueue is created by default. Note: This property is ignored if Persistence strategy is set to In Memory.
Response Buffering Queue JNDI Name	JNDI name for the response buffering queue. If this property is not set, then the request queue is used, as defined by the Request Buffering Queue JNDI Name property. If you create or extend a domain using the web service extension template, a buffering queue named weblogic.wsee.BufferedRequestErrorQueue is created by default. Note: This property is ignored if Persistence strategy is set to In Memory.
Cleaner Interval	Interval at which the logical store will be cleaned. For more information, see Cleaning Up Web Service Persistence. The value specified must be a positive value and conform to the XML schema duration lexical format, PnYnMnDTnHnMnS, where nY specifies the number of years, nM specifies the number of months, nD specifies the number of days, T is the date/time separator, nH specifies the number of hours, nM specifies the number of minutes, and nS specifies the number of seconds. This value defaults to PT10M (10 minutes). Note: This field is available when editing the logical store only. When creating the logical store, the field is set to the default, PT10M (10 minutes).
Default Maximum Object Lifetime	Default value used as the maximum lifetime of an object. This value can be overridden by the individual objects saved to the logical store. The value specified must be a positive value and conform to the XML schema duration lexical format, PnYnMnDTnHnMnS, where nY specifies the number of years, nM specifies the number of months, nD specifies the number of days, T is the date/time separator, nH specifies the number of hours, nM specifies the number of minutes, and nS specifies the number of seconds. This value defaults to P1D (one day). Note: This field is available when editing the logical store only. When creating the logical store, the field is set to the default, P1D (one day).

Configuring Web Service Persistence for a Web Service Endpoint

By default, web service endpoints use the web service persistent store defined for the server. You can override the logical store used by the web service endpoint using the WebLogic Server Administration Console. For more information, see Configure web service persistence in Oracle WebLogic Server Administration Console Online Help.

Configuring Web Service Persistence for Web Service Clients

For information about configuring persistence for web service clients, see Configuring Web Service Clients.

Using Web Service Persistence in a Cluster

The following provides some considerations for using web services persistence in a cluster:

• If you create or extend a clustered domain using the WebLogic Advanced Web Services for JAX-WS Extension template (wls_webservice_jaxws.jar), the resources required to support web services persistence in a cluster are automatically created. For more information, see Configuring Your Domain For Advanced Web Services Features.

• To facilitate service migration, it is recommended that the same physical storage resource be used for both persistent state and message buffering. To ensure that the buffering queue and physical store reference the same physical storage resource, you configure the Request Buffering Queue JNDI Name property of the logical store, as described in Configuring the Logical Store.

• It is recommended that the buffering queues be defined as JMS uniform distributed destinations (UDDs). JMS defines a member queue for the UDD on each JMS Server that you identify. Because a logical store is associated with a physical store through the defined buffering queue, during service migration, this allows a logical store to use the new physical stores seamlessly for the member queues that migrate onto the new server.

• It is recommended that you target the JMS Server, store-and-forward (SAF) service agent, and physical store (file store) resources to migrateable targets. For more information, see Resources Required by Advanced Web Service Features.

For example, consider the two-node cluster configuration shown in Figure 21-2. The domain resources are configured and targeted using the guidelines provided above.

Figure 21-2 Example of a Two-Node Cluster Configuration (Before Migration)

Description of "Figure 21-2 Example of a Two-Node Cluster Configuration (Before Migration)"

The following figure shows how the resources on Server1 can be easily migrated to Server2 in the event Server1 fails.

Figure 21-3 Example of a Two-Node Cluster Configuration (After Migration)

Description of "Figure 21-3 Example of a Two-Node Cluster Configuration (After Migration)"

Cleaning Up Web Service Persistence

The persisted information is cleaned up periodically to remove expired or stale objects. Typically, an object is associated with a specific expiration time or a maximum lifetime. In addition, a stale object may represent a request for which no response was received or a reliable messaging sequence that was not explicitly terminated.

You configure the interval of time at which web service persistence will be cleaned by setting the Cleaner Interval configuration property on the logical store. For more information about setting this property, see Configuring the Logical Store.