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. The com.ibm.websphere.rsadapter.WSConnection object
is located in the
plugins_root/com.ibm.ws.runtime_6.1.0.jar file.
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 Java™ 2 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). 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). 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 Java EEName
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).