Network Deployment (Distributed operating systems), v8.0 > Administer applications and their environment > Administer Data access resources > Administer data access applications > Configure Java EE Connector connection factories in the administrative console
Resource workload routing
Use this topic to learn how to enable resource routing in the environment.
New feature: Resource workload routing includes data source and connection factory fail over and subsequent fail back from a predefined alternate or backup resource. This function enables applications to easily recover from resource outages, such as database failures, without requiring you to embed alternate resource and configuration information. We can tailor the resource fail over and failback flexible configuration options to meet the environment-specific and application needs.New feature:
On distributed systems, you can enable resource routing only by configuring an alternate resource.
Configure an alternate resource
A data source and connection factory can fail over and fail back automatically when a specified or default failure threshold value is reached. When fail over occurs, the application switches from using the primary resource to using the alternate resource. Fail back occurs when the application switches back from the alternate resource to the primary resource.
The alternate resource is created the same way that other connection factories or data sources are created. The alternate resource configuration should mirror the primary resource configuration. For example, the alternate resource security configuration and the primary resource configuration, with respect to the application and resources, should mirror each other so that the application and database can access the required data. After the alternate resource is created, you can change the database values that are necessary for the alternate resource backend configuration. If the alternate resource is not compatible, it is likely that fail over will fail. If the resources are not compatible, the following errors might occur: tables or fields that do not exist, an expected record does not exist and unexpected resource errors exist. As a test option, before the alternate resource is configured to the primary data source, you can test the application by changing the JNDI name in the application from the primary JNDI name to the alternate JNDI name.
When the primary resource is used, the alternate resource is paused. Before the alternate resource is paused, the alternate resource can be available before the primary is used. Using the alternate before it is paused is not recommended unless there is a special reason the alternate needs to be accessed before the primary resource. An example of a special reason is testing the application for compatability.
An alternate resource cannot be used as a primary. When using the fail over feature with non-relational resource adapters that have back-ends that also support fail over, verify that fail over is not configured for these back-ends. Fail over works with non-relational resource adapters that have a ManagedConnection object that implements a testConnection method. The testConnection method is used to ping the alternate and primary resources for success before re-establishing a connection to the currently available resource. If the resource adapter does not implement a testConnection method or testConnection throws a javax.resource.NotSupportedException error, the fail over feature is disabled.
For resource adapters that do not meet the requirement for testConnection, partial fail over can be used. We must manually fail back using Mbeans to the primary resource when the primary resource is available. Partial fail over can be enabled by setting the property, enablePartialResourceAdapterFailoverSupport to true.
You are encouraged to test the suitability of this feature with the system environment and resources before enabling fail over support.
Mbean operations properties
failOverToAlternateResource
Values: none, hold or automated; default is hold without automated fail back.
Description: Manual fail over to alternate resource. This action is issued on the primary resource.
failBackToPrimaryResource
Values: none, hold or automated; default is automated with automated fail over.
Description: Manual fail back to primary resource. This action is issued on the primary resource.
Mbean attribute properties
resourceFailOver
Values: boolean
Description: False - Disables resource fail over. True - Enables resource fail over. This action is issued on the primary resource.
resourceFailBack
Values: boolean
Description: False - Disables resource fail back. True - Enables resource fail back. This action is issued on the primary resource.
populateAlternateResource
Values: boolean
Description: False - Disables populate alternate resource. True - Enables populate alternate resource. This action is issued on the alternate resource.
Custom properties
All properties for this feature must be created as new custom properties on the connection pool for a particular data source or connection factory. In the administrative console, navigate to the data source or connection factory that notification is to be enabled for. Click the Connection pool properties link. On the Pool Properties panel, click Connection pool custom properties link. The Custom properties panel for the resource connection pool displays. Click New to create the custom properties described as follows:
failureThreshold
Values: Must be an integer and > 0.
Description: The failureThreshold property is only read if the failureNotificationActionCode or alternateResourceJNDIName property is set to valid value. If the failureThreshold property is not set or is set to an invalid number the default value of 5 is used. The integer value specified for the failureThreshold is the number of consecutive resource exceptions that must occur for a particular resource before notification is sent or failover occurs.
The following is an example of how this value works: If the failureThreshold property is set to 5 for data source B, then data source B must get five consecutive resource exceptions while attempting to establish connections, with no successful attempts in-between these failures, before notification is sent or the resource can fail over. An attempt to send the notification or fail over is made after five consecutive resource exceptions occur. However, in a multi-threaded environment, after the failure threshold value is reached, the timing of the notification or fail over might occur after additional resource exceptions.
Attention: Resource exception counters are not shared between resources. Resource exceptions must be consecutive to reach failure threshold.
alternateResourceJNDIName
Values: String value containing a direct JNDI name.
Description: An alternate connection factory or data source resource should be like the primary resource. Provide the JNDI name of the alternate resource to enable the fail over feature.
Advanced fail over properties
resourceAvailabilityTestRetryInterval
Values: int value, default is 10.
Description: The test connection interval by default is 10 seconds. Every 10 seconds, the test connection thread attempts to test the primary resource. Depending on system resources, this value can be change from 1 - MAXINIT seconds.
enablePartialResourceAdapterFailoverSupport
Values: boolean value, default is false.
Description: If this value is true, fail over to the alternate resource occurs, but fail back to the primary is manual. This property can be set if the resource adapter being used does not meet the requirements for connection fail over, for example, it does not have testConnection implemented or it throws a not supported exception.
disableResourceFailOver
Values: boolean value, default is false.
Description: If this value is true, automatic fail over does not occur.
disableResourceFailBack
Values: boolean value, default is false.
Description: If this value is true, automatic fail back does not occur.
populateAlternateResource
Values: boolean value, default is false.
Description: If this value is true, the alternate resource is populated with connections to maximum connections. Every attempt is made to keep the alternate resource at maximum connections. If the database goes down for the alternate resource, the stale connections are removed and the populate thread repopulates the alternate resource when the database is available. We can dynamically enable and disable the populate alternate resource using the Mbean operations, disablePopulateAlternateResource and enablePopulateAlternateResource.
Attention: You might see performance gains during a failover with populate alternate resource enabled, but, the cost is high to keep the alternate resource populated. Most of the cost is in keeping twice the number of connections typically required for one data source. Because connections are large objects, keeping the connections uses additional memory resource on the server and extra resource on the database.