Chapter 3 EAServer and Application Issues

Connections and connection caching

This section discusses how Application Integrator components use connections to target servers, including the following topics.

Component properties: connections and security

When the Component Builder deploys a component into EAServer, it sets the following properties for the component. These properties affect connection handling and security.

com.sybase.ai.connection.name This property is referred to as connection_name. It specifies the name of the connection associated with the component.

com.sybase.ai.use_client_security This property is referred to as use_client_security. It affects the user ID and password that are used to obtain connections. Valid values are:

• false
  
  A value of false tells the Application Integrator component to use the user ID and password that were supplied in the connection object from the Component Builder. The default value is false.
• true
  
  A value of true tells the component to use the user ID and password from the client that invoked the component method. When the value is true, the caller's user ID and password are obtained from EAServer and are subsequently used to override the user ID and password from the connection definition.

com.sybase.ai.use_connection_cache This property is referred to as use_connection_cache. It specifies how the Application Integrator component acquires and disposes of connections. Valid values are:

• false
  
  A value of false tells the Application Integrator component to open and close connections to a server directly. The default value is false.
• true
  
  A value of true tells the component to get and release connections from an EAServer connection cache.

com.sybase.ai.connection_cache_unavail_action This property controls the action that EAServer takes if there are no connections available in the cache. The valid values correspond to the values for the flag parameter on the JCMCache.getConnection() method. See the section on using connection management in the EAServer Programmer's Guide for a more detailed discussion. Valid values are:

• nowait
  
  If no connections are available, the request results in an exception (error condition) that is then propagated back to the caller. The default is nowait.
• force
  
  EAServer should attempt to open a new connection (that will not be placed back in the cache after use).
• wait
  
  The component waits indefinitely until a connection becomes available. Sybase does not recommend that you use this option because this indefinite wait can cause component instances to tie up resources and can cause the client application to wait indefinitely.

Acquiring and disposing of connections

The process of acquiring and disposing of connections differs depending on whether the Application Integrator component is configured to use connection caching.

When Not Using Connection Caching

• Acquiring connections refers to opening a new connection directly to the target server. The values supplied to the JDBC driver for connecting to the server are retrieved from the connection definition with the name matching the connection_name property. These values include such information as the JDBC driver class name, connection URL, user ID, password, and JDBC driver-specific properties. When opening a new connection to a server, the Application Integrator component passes these values to the JDBC driver.
• Disposing of connections refers to closing connections.

When Using Connection Caching

• Acquiring connections refers to retrieving a connection from the EAServer connection cache. When the Application Integrator component needs to get a connection to the target server, the connection_name property is used to locate an EAServer connection cache by name.
• Disposing of connections refers to releasing a connection back to the EAServer connection cache for other components to use.

Defining connection caches in Jaguar Manager

Defining connection caches for Application Integrator components is similar to defining them for other components that use JDBC connection caches. A connection cache that is defined for an Application Integrator component can be shared with other non-Application Integrator components.

You must set up connection cache definitions in Jaguar Manager using the following procedure. In general, use the same information that was used to create the connection in the Component Builder.

To define a connection cache:

1. On the Driver tab of the Connection Cache Properties dialog box, select JDBC 1.1.
2. Enter the JDBC driver class name in the DLL or Class Name field.
   
   For example, when using jConnect as the JDBC driver, the class name is com.sybase.jdbc.SybDriver.
3. On the Server tab:
   1. Set the Server Name property to match the URL string from the Application Integrator Component Builder connection definition (see "Defining AI connections" for information).
   2. Enter a valid user name and password.
4. Click Enable cache-by-name access to set this property to on (it is off by default). This allows the Application Integrator component to look up connection caches by name.
   
      Setting the EAServer Enable cache-by-name access property requires "Jagadmin" authority.
   
5. Restart the EAServer to effect changes to connection cache definitions.
   
   Make sure the connection cache is installed into a running EAServer before you use it in a component to connect to a target

   Currently, EAServer connection cache definitions for JDBC drivers do not allow you to specify driver connection properties. If you are using jConnect, you can specify the JDBC connection properties by appending the name-value pairs to the URL using this syntax: /optional_db_name&PROP1=VAL1&PROP2=VAL2. See the Sybase jConnect for JDBC Programmer's Reference for information about setting connection properties.

AI Component properties in EAServer components

In addition to the properties that all Java-style EAServer components have, Application Integrator adds some properties to the component in the EAServer component repository. Application Integrator-specific properties begin with the com.sybase.ai prefix and are set to default values by the Component Builder when the component is initially deployed. You must refresh the component in Jaguar Manager for property changes to take effect.

To edit these properties in Jaguar Manager, use the All Properties tab on the Component Properties dialog box. Click on the column heading once to sort the properties alphabetically by name in ascending order; click on the column heading again to sort the properties alphabetically in descending order.

Do not modify any of the following component properties unless instructed to do so by Sybase Technical Support:

• com.sybase.jaguar.component.files
• com.sybase.jaguar.component.ids
• com.sybase.jaguar.component.java.classes
• com.sybase.jaguar.component.interfaces
• com.sybase.jaguar.component.java.class
• com.sybase.jaguar.component.type
• com.sybase.jaguar.component.name
• com.sybase.jaguar.component.bind.object
• com.sybase.jaguar.component.bind.thread

Component execution debugging

The com.sybase.ai.debug component property can be used to cause the component to write detailed trace information to the EAServer log. The property can have a value of true to indicate that the component should write trace information to the EAServer log.
A value of false (the default) indicates that the component should not write information to the log.

In general, the information produced by this logging is intended for Sybase Technical Support to aid in problem determination.

To turn on component debugging:

1. In Jaguar Manager, set the com.sybase.ai.debug property to a value of true. Refresh the component.
2. Run the component using your EAServer client application.
3. Check the EAServer log to view the debug output produced by component execution.

Copyright © 2001 Sybase, Inc. All rights reserved.