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 about
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.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 runtime 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.
The
information implicitly collected and set on the database connection
consists of the thread ID, user name, user location, and application
name.
Important: User name and user location can be
implicitly collected and set only on the database connection if you enable Java 2 security.
- thread ID
- An eight-character hexadecimal value that identifies the Java thread that controls the processing of
the application request within WebSphere Application
Server. This ID is displayed in the trace header.
- 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 EE
Name 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 JavaBeans (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, and, 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).