Chapter 3 Jaguar 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
• Acquiring and Disposing of Connections
• Defining Connection Caches in Jaguar Manager
• AI Component Properties in Jaguar Components

Component Properties: Connections and Security

When the Component Builder deploys a component into Jaguar, 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 Jaguar 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 a Jaguar connection cache.
  

com.sybase.ai.connection_cache_unavail_action

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

• nowait
  Indicates that 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
  Indicates that Jaguar should attempt to open a new connection (that will not be placed back in the cache after use).
  
• wait
  Indicates that the component waits indefinitely until a connection becomes available. We do 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 the process of 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 the process of retrieving a connection from the Jaguar connection cache. When the Application Integrator component needs to get a connection to the target server, the connection_name property is used to locate a Jaguar connection cache by name.
• Disposing of connections refers to releasing a connection back to the Jaguar 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 the JDBC 1.1 radio button.
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 "Understanding AI Connections" for information).
   2. Enter a valid user name and password.
4. Click the Enable cache-by-name access checkbox 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 Jaguar Enable cache-by-name access property requires Jaguar administrator authority.
   

5. Restart the Jaguar server to effect changes to connection cache definitions.
   Make sure the connection cache is installed into a running Jaguar server before you use it in a component to connect to a target.
   

   Currently, Jaguar connection cache definitions for JDBC drivers do not allow you to specify driver connection properties. If the JDBC driver is Sybase jConnect, the JDBC connection properties can be specified by appending the name-value pairs to the URL using the following 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 Jaguar Components

In addition to the properties that all Java-style Jaguar components have, Application Integrator adds some properties to the component in the Jaguar 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 Jaguar server log. The property can have a value of true to indicate that the component should write trace information to the Jaguar server 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:
   1. Set the com.sybase.ai.debug property to a value of true.
   2. Refresh the component.
2. Run the component using your Jaguar client application.
3. Check the Jaguar server log to view the debug output produced by component execution.

Copyright © 1999 Sybase, Inc. All rights reserved.