If you track client information in your database, you can choose
one of two ways to pass WebSphere Application Server client data on database
connections.
You can choose to
explicitly pass the information on connections
by calling an IBM proprietary API, setClientInformation(Properties), on the
com.ibm.websphere.rsadapter.WSConnection object within your application code.
In some cases, however, you might want WebSphere Application Server to handle
the passing of client information to database connections. This method of
setting the client information is referred to as
implicit. You might
choose the implicit method because:
- You want to keep your application free of proprietary APIs, or
- Your application uses container-managed persistence (CMP), in which case
you cannot use the proprietary API to set client information on database connections.
The WebSphere Application Server trace facility provides the capability
for setting client information implicitly. You can designate one of two special
trace groups to enable or disable client information passing: WAS.clientinfo trace or WAS.clientinfopluslogging trace.
Possible run-time scenarios
- Connection sharing
In the case of connection sharing, WebSphere Application
Server sets the client information on the first acquired connection handle
only. If connection sharing is enabled and two or more getConnection methods
are called (resulting in two handles on the same connection), only the first
getConnection call causes the client information to pass to the backend database.
This scenario does not apply to the explicit process of passing client information;
in such cases every setClientinformation method is relayed to the database
regardless of connection sharing.
- Implicit/explicit co-existence
When you use both the explicit and implicit
procedures for relaying client information, some combination of the explicitly
set data and implicitly set data is combined, but the explicit setting usually
takes precedence. For example, if the application sets the client accounting
information to "myAccountingInfo", the final accountingInfo string that is
passed to the backend database looks something like the following sample code:
000325_WSRdbManagedConnectionImpl@1234_myAccountingInfo:
where
000325 is the thread id and
WSRdbManagedConnectionImpl@1234 is
the WebSphere connection instance.
- Client information reset
When you configure Application Server to pass
client information, it does reset client information when a connection is
returned to the pool, but only if the WAS.clientinfo and WAS.clientinfopluslogging
trace mechanisms are disabled (that is, WAS.clientinfo=all=disabled:WAS.clientinfopluslogging=all=disabled).
In
the explicit case, however, the reset operation is done only when the application
issues setClientInformation(null) on the WSConnection connection.
WAS.clientinfo trace
By default,
the implicit mechanism is disabled. You can turn on this mechanism dynamically,
without stopping and starting your application server, or statically by setting
the WebSphere Application Server trace group WAS.clientinfo=all=enabled.
The information implicitly collected and set on the
database connection consists of the user name, user location and application
name.
Important: User name and user location
can only be implicitly collected and set on the database connection if you
enable global security.
- user name
- The name of the user that initiates the application request. This option
is collected and passed to the backend database (when supported) only if global security is enabled.
Information here is collected by calling the WSSecurityHelper.getFirstCaller
method.
- user location
- The name of the location of the user, in the form of cell:node:server.
This option is collected and passed to the backend database, when appropriate,
only when global security is enabled.
Information here is collected by calling the WSSecurityHelper.getFirstServer
method.
- application name
- The name of the application running. This value is the output of the
getApplication method from the J2EEName object. This value is collected regardless
of the Global Security setting.
WAS.clientinfopluslogging trace
When
debugging database problems, such as deadlocks, there is a set of information
that is needed to help with the debugging effort. This information is typically
obtained by enabling a WebSphere Relational Resource Adapter (RRA) trace,
and an Enterprise JavaBean (EJB) container trace. However, there are some
cases where timing is an issue when reproducing a given problem. Having too
much tracing information can alter the behavior of the application, such as
change the timing, and the problem might no longer occur.
Because of
this situation, a new trace group is provided where only a minimum set of
information is collected. This trace group is WAS.clientinfopluslogging.
This function sets the client information implicitly on the connection, just
like the WAS.clientinfo trace, as well as logs and traces important application
activities. Those activities are:
- SQL Strings that are run (such as, select userId from tabl1 where id=?
for update).
- Start, commit, and rollback of transactions.
- EJB calls (such as, Create, Remove, findByPrimaryKey, and so on).