Sun Java System Application Server Enterprise Edition 8.1 2005Q2 Developer's Guide

- Previous: Deploying and Configuring an Embedded Resource Adapter
- Next: Inbound Communication Support

# Advanced Connector Configuration Options

You can use these advanced connector configuration options:

- Thread Pools

- Security Maps

- Overriding Configuration Properties

- Testing a Connection Pool

- Handling Invalid Connections

- Setting the Shutdown Timeout

- Using Last Agent Optimization of Transactions

## Thread Pools

Connectors can submit work instances to the Application Server for execution. By default, the Application Server services work requests for all connectors from its default thread pool. However, you can associate a specific user-created thread pool to service work requests from a connector. A thread pool can service work requests from multiple resource adapters. To create a thread pool:

- In the Administration Console, select Thread Pools under the relevant configuration. For details, see the Sun Java System Application Server Enterprise Edition 8.1 2005Q2 Administration Guide.

- Use the `asadmin create-threadpool` command. For details, see the Sun Java System Application Server Enterprise Edition 8.1 2005Q2 Reference Manual.

To associate a connector with a thread pool:

- In the Administration Console, open the Applications component and select Connector Modules. Deploy the module, or select the previously deployed module. Specify the name of the thread pool in the Thread Pool ID field. For details, see the Sun Java System Application Server Enterprise Edition 8.1 2005Q2 Administration Guide.

- Use the `--threadpoolid` option of the `asadmin create-resource-adapter-config` command. For details, see the Sun Java System Application Server Enterprise Edition 8.1 2005Q2 Reference Manual.

If you create a resource adapter configuration for a connector module that is already deployed, the connector module deployment is restarted with the new configuration properties.

## Security Maps

Create a security map for a connector connection pool to map an application principal or a user group to a back end EIS principal. The security map is usually used in situations where one or more EIS back end principals are used to execute operations (on the EIS) initiated by various principals or user groups in the application.

To create or update security maps for a connector connection pool:

- In the Administration Console, open the Resources component, select Connectors, select Connector Connection Pools, and select the Security Maps tab. For details, see the Sun Java System Application Server Enterprise Edition 8.1 2005Q2 Administration Guide.

- Use the `asadmin create-connector-security-map` command. For details, see the Sun Java System Application Server Enterprise Edition 8.1 2005Q2 Reference Manual.

If a security map already exists for a connector connection pool, the new security map is appended to the previous one. The connector security map configuration supports the use of the wildcard asterisk (`*`) to indicate all users or all user groups.

When an application principal initiates a request to an EIS, the Application Server first checks for an exact match to a mapped back end EIS principal using the security map defined for the connector connection pool. If there is no exact match, the Application Server uses the wild card character specification, if any, to determined the mapped back end EIS principal.

## Overriding Configuration Properties

You can override the properties specified in the `ra.xml` file of a resource adapter. Use the `asadmin create-resource-adapter-config` command to create a configuration for a resource adapter. Use this command’s `--property` option to specify a name-value pair for a resource adapter property.

You can use the `asadmin create-resource-adapter-config` command either before or after resource adapter deployment. If it is executed after deploying the resource adapter, the existing resource adapter is restarted with the new properties. For details, see the Sun Java System Application Server Enterprise Edition 8.1 2005Q2 Reference Manual.

You can also use token replacement for overriding resource adapter configuration properties in individual server instances when the resource adapter is deployed to a cluster. For example, for a property called `inboundPort`, you can assign the value `${inboundPort}`. You can then assign a different value to this property for each server instance. Changes to system properties take effect upon server restart.

## Testing a Connection Pool

After configuring a connector connection pool, use the `asadmin ping-connection-pool` command to test the health of the underlying connections. For details, see the Sun Java System Application Server Enterprise Edition 8.1 2005Q2 Reference Manual.

## Handling Invalid Connections

If a resource adapter generates a `ConnectionErrorOccured` event, the Application Server considers the connection invalid and removes the connection from the connection pool. Typically, a resource adapter generates a `ConnectionErrorOccured` event when it finds a `ManagedConnection` object unusable. Reasons can be network failure with the EIS, EIS failure, fatal problems with resource adapter, and so on. If the `fail-all-connections` property in the connection pool configuration is set to `true`, all connections are destroyed and the pool is recreated.

You can set the `fail-all-connections` configuration property during creation of a connector connection pool. Or, you can use the `asadmin set` command to dynamically reconfigure a previously set property. For details, see the Sun Java System Application Server Enterprise Edition 8.1 2005Q2 Reference Manual.

The interface `ValidatingManagedConnectionFactory` exposes the method `getInvalidConnections` to allow retrieval of the invalid connections. The Application Server checks if the resource adapter implements this interface, and if it does, invalid connections are removed when the connection pool is resized.

## Setting the Shutdown Timeout

According to the Connector 1.5 specification, while an application server shuts down, all resource adapters should be stopped. A resource adapter might hang during shutdown, since shutdown is typically a resource intensive operation. To avoid such a situation, you can set a timeout that aborts resource adapter shutdown if exceeded. The default timeout is 30 seconds per resource adapter module. To configure this timeout:

- In the Administration Console, select JMS/Connector Service under the relevant configuration. For details, see the Sun Java System Application Server Enterprise Edition 8.1 2005Q2 Administration Guide.

- Use the following command:

      asadmin set server-instance.connector-service.shutdown-timeout-in-seconds="num-secs"

  For details, see the Sun Java System Application Server Enterprise Edition 8.1 2005Q2 Reference Manual.

The Application Server deactivates all message-driven bean deployments before stopping a resource adapter.

## Using Last Agent Optimization of Transactions

Transactions that involve multiple resources or multiple participant processes are distributed or global transactions. A global transaction can involve one non-XA resource if last agent optimization is enabled. Otherwise, all resources must be XA. For more information about transactions in the Application Server, see Chapter 12, Using the Transaction Service.

The Connector 1.5 specification requires that if a resource adapter supports `XATransaction`, the `ManagedConnection` created from that resource adapter must support both distributed and local transactions. Therefore, even if a resource adapter supports `XATransaction`, you can configure its connector connection pools as non-XA or without transaction support for better performance. A non-XA resource adapter becomes the last agent in the transactions in which it participates.

The value of the connection pool configuration property `transaction-support` defaults to the value of the `transaction-support` property in the `ra.xml` file. The connection pool configuration property can override the `ra.xml` file property if the transaction level in the connection pool configuration property is lower. If the value in the connection pool configuration property is higher, it is ignored.

- Previous: Deploying and Configuring an Embedded Resource Adapter
- Next: Inbound Communication Support

- © 2010, Oracle Corporation and/or its affiliates