Sun GlassFish Enterprise Server v2.1.1 Administration Guide

Chapter 7 Connector Resources

This chapter explains how to configure connectors, which are used to access enterprise information systems (EISs). This chapter contains the following sections:

An Overview of Connectors

Also called a resource adapter, a connector module is a Java EE component that enables applications to interact with enterprise information systems (EISs). EIS software includes various types of systems: enterprise resource planning (ERP), mainframe transaction processing, and non-relational databases, among others. Like other Java EE modules, to install a connector module you deploy it.

A connector connection pool is a group of reusable connections for a particular EIS. To create a connector connection pool, specify the connector module (resource adapter) that is associated with the pool.

A connector resource is a program object that provides an application with a connection to an EIS. To create a connector resource, specify its JNDI name and its associated connection pool. Multiple connector resources can specify a single connection pool. The application locates the resource by looking up its JNDI name. (For more information on JNDI, see the section JNDI Names and Resources.) The JNDI name of a connector resource for an EIS is usually in the java:comp/env/eis-specific subcontext.

The Enterprise Server implements JMS by using a connector module (resource adapter). See the section, The Relationship Between JMS Resources and Connector Resources.

Managing Connector Connection Pools

ProcedureTo Create a Connector Connection Pool

Before You Begin

Before creating the pool, deploy the connector module (resource adapter) associated with the pool. The values that are specified for the new pool depend on the connector module that is deployed.

  1. In the tree component, expand the Resource node and then the Connectors node. Select the Connector Connection Pools node. On the Connector Connection Pools page, click New.

  2. On the first Create Connector Connection Pool page, specify the following settings:

    1. In the Name field, enter a logical name for the pool.

      Specify this name when creating a connector resource.

    2. Select an entry from the Resource Adapter combo box.

      The combo box displays a list of deployed resource adapters (connector modules).

  3. Select a value from the Connection Definition combo box.

    The choices in the combo box depend on the resource adapter you selected. The Connection Definition attribute identifies a resource adapter's connection-definition element in thera.xml file.

  4. Click Next.

  5. On the next Create Connector Connection Pool page, perform these tasks:

    1. In the General Settings section verify that the values are correct.

    2. For the fields in the Pool Settings section, the default values can be retained.

      These settings can be changed at a later time. See To Edit a Connector Connection Pool.

    3. In the Additional Properties table, add any required properties.

      In the previous Create Connector Connection Pool page, you selected a class in the Connection Definition combo box. If this class is in the server’s classpath, then the Additional Properties table displays default properties.

  6. Click Finish.

Equivalent asadmin command

create-connector-connection-pool

ProcedureTo Edit a Connector Connection Pool

  1. In the tree component, expand the Resources node and then the Connectors node. Expand the Connector Connection Pools node and select the connector connection pool you want to edit.

  2. On the Edit Connector Connection Pool page, you can change the settings of this connection pool. (Optional) Under General Settings, modify the description for the connection pool.

  3. Under Pool Settings, you can specify the parameter values as explained in the following table.

    Parameter 

    Description 

    Initial and Minimum Pool Size 

    The minimum number of connections in the pool. This value also determines the number of connections placed in the pool when the pool is first created or when application server starts. 

    Maximum Pool Size 

    The maximum number of connections in the pool. 

    Pool Resize Quantity 

    When the pool scales up and scales down towards the maximum and minimum pool size respectively, it is resized in batches. This value determines the number of connections in the batch. Making this value too large will delay connection creation and recycling; making it too small will make it less efficient. 

    Idle Timeout 

    The maximum time in seconds that a connection can remain idle in the pool. After this time expires, the connection is removed from the pool. 

    Max Wait Time 

    The amount of time the application requesting a connection will wait before getting a connection timeout.  

    On Any Failure 

    If you select the checkbox labelled Close All Connections, if a single connection fails, then the application server will close all connections in the pool and then reestablish them. If you do not select the checkbox, then individual connections will be reestablished only when they are used. 

    Transaction Support 

    Use the Transaction Support list to select the type of transaction support for the connection pool. The chosen transaction support overrides the transaction support attribute in the resource adapter associated with this connection pool in a downward compatible way. In other words, it can support a lower transaction level than that specified in the resource adapter or the same transaction level as that specified in resource adapter, but it cannot specify a higher level. The transaction support options include the following. The None selection from the Transaction Support menu indicates that the resource adapter does not support resource manager local or JTA transactions and does not implement XAResource or LocalTransaction interfaces. For JAXR resource adapters, you need to choose None from the Transaction Support menu. JAXR resource adapters do not support local or JTA transactions. Local transaction support means that the resource adapter supports local transactions by implementing the LocalTransaction interface. Local transactions are managed internal to a resource manager and involve no external transaction managers. XA transaction support means that the resource adapter supports resource manager local and JTA transactions by implementing the LocalTransaction and XAResourceinterfaces. XA transactions are controlled and coordinated by a transaction manager external to a resource manager. Local transactions are managed internal to a resource manager and involve no external transaction managers. 

    Connection Validation 

    Select the Required checkbox to enable connection validation. 

  4. Click Save.

  5. Click Load Defaults if you want to restore the default values of all the settings.

Using the asadmin commands to change connection pool properties.

You can use the asadmin get and set commands to view and change the values of the connection pool properties.

To list all the connector connection pools in the server:

asadmin list domain.resources.connector-connection-pool.*

To view the properties of the connector connection pool, you can use the following command:

asadmin get domain.resources.connector-connection-pool.conectionpoolname.*

To set a property of the connector connection pool, you can use the following command:

asadmin set domain.resources.connector-connection-pool.conectionpoolname.pool-resize-quantity=3

ProcedureTo Edit Connector Connection Pool Advanced Attributes

  1. Use the Advanced tab to edit the advanced attributes for a connector connection pool.

    Parameter 

    Description 

    Validate Atmost Once 

    Amount of time, in seconds, after which a connection is validated at most once. This will help reduce the number of validation requests by a connection. The default value 0 implies that connection validation is not enabled. 

    Leak Timeout 

    Amount of time, in seconds, to trace connection leaks in a connection pool. The default value 0 means that connection leak tracing is disabled. If connection leak tracing is enabled, you can get statistics on the number of connection leaks in the Monitoring Resources tab. To view this tab, go to Application Server > Monitoring > Resources. 

    Leak Reclaim 

    If this option is enabled, leaked connections will be restored to the pool after leak connection tracing is complete. 

    Creation Retry Attempts 

    Number of attempts that will be made if there is a failure in creating a new connection. The default value of 0 implies that no attempts will be made to create the connection again. 

    Retry Interval 

    Specify the interval, in seconds, between two attempts to create a connection. The default value is 10 seconds. This attribute is used only if the value of Creation Retry Attempts is greater than 0. 

    Lazy Association 

    Connections are lazily associated when an operation is performed on them. Also, they are disassociated when the transaction is completed and a component method ends, which helps reuse of the physical connections. Default value is false. 

    Lazy Connection Enlistment 

    Enable this option to enlist a resource to the transaction only when it is actually used in a method. 

    Associate with Thread 

    Enable this option to associate a connection with the thread such that when the same thread is in need of a connection, it can reuse the connection already associated with it, thereby not incurring the overhead of getting a connection from the pool. Default value is false. 

    Match Connections 

    Use this option to switch on/off connection matching for the pool. It can be set to false if the administrator knows that the connections in the pool will always be homogeneous and hence a connection picked from the pool need not be matched by the resource adapter. Default value is false. 

    Max Connection Usage 

    Specify the number of times a connection should be reused by the pool. Once a connection is reused for the specified number of times, it will be closed. This is useful, for instance, to avoid statement-leaks. The default value of 0 implies that this attribute is not enabled. 

  2. Click Save for the changes to take effect.

  3. Click Load Defaults if you want to restore the default values of all the settings.

Using the asadmin commands to change connection pool properties.

You can use the asadmin get and set commands to view and change the values of the connection pool properties.

To list all the connector connection pools in the server:

asadmin list domain.resources.connector-connection-pool.*

To view the properties of the connector connection pool, you can use the following command:

asadmin get domain.resources.connector-connection-pool.conectionpoolname.*

To set a property of the connector connection pool, you can use the following command:

asadmin set domain.resources.connector-connection-pool.conectionpoolname.validate-atmost-once-period-in-seconds=3

ProcedureTo Edit Connection Pool Properties

  1. Use the Additional Properties tab to modify the properties of an existing pool.

    The properties specified depend on the resource adapter used by this pool. The name-value pairs specified by the deployer using this table can be used to override the default values for the properties defined by the resource-adapter vendor.

  2. Click Save for the changes to take effect.

Managing Security Maps

You can create, edit, and delete security maps associated with connector connection pools.

ProcedureTo create security maps for connector connection pools

  1. In the Edit Connector Connection Pool page, click the Security Maps tabbed pane.

  2. Click New to create a new security map.

  3. In the New Security Map page, provide a name for the security map, a user name, and password.

  4. Click OK.

ProcedureTo Edit Security Maps for Connector Connection Pools

  1. In the Edit Connector Connection Pool page, click the Security Maps tabbed pane.

  2. From the list of security maps, click the name of the security map that you want to edit.

  3. Modify the values as desired, and click Save.

ProcedureTo Delete a Connector Connection Pool

  1. In the tree component, expand the Resources node and then the Connectors node.

  2. Select the Connector Connection Pools node.

  3. On the Connector Connection Pools page, select the checkbox for the pool to be deleted.

  4. Click Delete.

Equivalent asadmin command

delete-connector-connection-pool

ProcedureTo Set Up EIS Access

  1. Deploy (install) a connector.

  2. Create a connection pool for the connector.

  3. Create a connector resource that is associated with the connection pool.

Managing Connector Resources

ProcedureTo Create a Connector Resource

A connector resource (data source) provides applications with a connection to an EIS.

Before You Begin

Before creating a connector resource, first create a connector connection pool.

  1. In the tree component, expand the Resources node and then the Connectors node.

  2. Expand the Connector Resources node.

  3. On the Connector Resources page, click New.

  4. On the Create Connector Resources page, specify the resource’s settings:

    1. In the JNDI Name field, type a unique name, for example: eis/myERP.

    2. From the Pool Name combo box, choose the connection pool to which the new connector resource belongs.

    3. To change the resource to be unavailable, deselect the Status checkbox.

      By default, the resource is available (enabled) when it is created.

    4. Do one of the following:

      • If you are using the cluster profile, you will see the Targets section of the page. in the Targets section of the page, select the domain, cluster, or server instances where the connector resource will reside, from the Available field and click Add. If you do not want to deploy the connector resource to one of the domains, clusters, or server instances listed in the Selected field, select it from the field and click Remove.

      • If you are running a domain with developer profile, skip to step 5.

  5. Click OK.

Equivalent asadmin command

create-connector-resource

ProcedureTo Edit a Connector Resource

  1. In the tree component, expand the Resources node and then the Connectors node.

  2. Expand the Connector Resources node.

  3. Select the node for the connector resource that you want to edit. On the Edit Connector Resources page, you can change the settings of this connection.

  4. Do one of the following:

    • If you are using the cluster profile or enterprise profile, you will see the Targets tabbed pane. On the Targets tabbed pane, you can enable or disable the connector resource on individual targets. You can change the targets on which the connector resource is deployed by clicking Manage Targets.

    • If you are using developer profile, skip to next step.

  5. Click Save to apply the edits.

ProcedureTo Delete a Connector Resource

  1. In the tree component, expand the Resources node and then the Connectors node.

  2. Select the Connector Resources node.

  3. On the Connector Resources page, select the checkbox for the resource to be deleted.

  4. Click Delete.

Equivalent asadmin command

delete-connector-resource

ProcedureTo Configure the Connector Service

Use the Connector Service screen to configure the connector container for all resource adapters deployed to this cluster or server instance.

  1. Select Configurations from the tree.

  2. If you are using the cluster profile, select the instance to configure:

    • To configure a particular instance, select the instance’s config node. For example, for the default instance, server, select the server-config node.

    • To configure the default settings for future instances that use a copy of default-config, select the default-config node.

  3. Select the Connector Service node.

  4. Specify the shutdown timeout in seconds in the Shutdown Timeout field.

    Enter an integer representing the number of seconds that the application server waits to allow the ResourceAdapter.stop method of the connector module’s instance to complete. Resource adapters that take longer than the specified shutdown timeout are ignored by the application server and the shutdown procedure continues. The default shutdown timeout is 30 seconds. Click Load Defaults to select the default shutdown timeout for the resource adapters deployed to this cluster or server instance.

Managing Administered Object Resources

Packaged within a resource adapter (connector module), an administered object provides specialized functionality for an application. For example, an administered object might provide access to a parser that is specific to the resource adapter and its associated EIS. The object can be administered; that is, it can be configured by an administrator. To configure the object, add name-value property pairs in the Create or Edit Admin Object Resource pages. When creating an administered object resource, associate the administered object to a JNDI name.

To create, edit, and delete Connector Connection Pools, click Resources —> Administered Object Resources in the Admin Console. Consult the Admin Console Online Help for detailed instructions on managing connector connection pools.

ProcedureTo Create an Administered Object Resource

Packaged within a resource adapter (connector module), an administered object provides specialized functionality for an application. For example, an administered object might provide access to a parser that is specific to the resource adapter and its associated EIS. The object can be administered; that is, it can be configured by an administrator. To configure the object, add name-value property pairs in the Create or Edit Admin Object Resource pages. When creating an administered object resource, associate the administered object to a JNDI name.

The Enterprise Server implements JMS by using resource adapter. For each JMS destination created, the Enterprise Server automatically creates an administered object resource.

  1. In the tree component, expand the Resources node and then the Connectors node.

  2. Expand the Admin Object Resources node.

  3. On the Admin Object Resources page, click New.

  4. On the Admin Object Resources page, specify the following settings:

    1. In the JNDI Name field, type a unique name that identifies the resource.

    2. In the Resource Type field, enter the Java type for the resource.

    3. From the Resource Adapter combo box, select the resource adapter that contains the administered object.

    4. Select or deselect the Status checkbox to enable or disable the resource.

    5. To configure the administered object with name-value property pairs, click Add Property.

    6. If you are using cluster profile, in the Targets section of the page, select the domain, cluster, or server instances where the administered object will reside, from the Available field and click Add.

      To undeploy the administered object to one of the domains, clusters, or server instances listed in the Selected field, select it from the field and click Remove.

    7. Click Finish.

Equivalent asadmin command

create-admin-object

ProcedureTo Edit an Administered Object Resource

  1. In the tree component, expand the Resource node and then the Connectors node.

  2. Expand the Administered Object Resources node.

  3. Select the node for the administered object resource to be edited.

  4. On the Edit Administered Object Resources page, modify values specified in Creating an Administered Object Resource.

  5. If you are using cluster profile, on the Targets tabbed pane, edit the targets on which the administered object is deployed by clicking Manage Targets.

  6. Click Save to apply the edits.

ProcedureTo Delete an Administered Object Resource

  1. In the tree component, expand the Resources node and then the Connectors node.

  2. Select the Administered Object Resources node.

  3. On the Administered Object Resources page, select the checkbox for the resource to be deleted.

  4. Click Delete.

Equivalent asadmin command

delete-admin-object