Agents › DevTest Java Agent › Java Agent Usage › rules.xml File › Instrumentation Rules for VSE

Instrumentation Rules for VSE

You can customize the VSE functionality by adding the virtualize directive to the rules.xml file of the agent.

The virtualize directive can be placed within the group element or the agent element of the rules.xml file.

Adding a Class for Virtualization (Both Recording and Playback Modes)

<virtualize class="class_name"/>

Example:

<virtualize class="javax.ejb.SessionBean"/>

Telling the Agent how to Determine What Constitutes a Session for a Given Protocol

You perform this task by providing a code snippet that returns a session identifier.

<virtualize>
   <track class="class_name" method="method_name" signature="signature" push="true|false">
      <code><![CDATA[" and ends with "]]></code>
   </track>
</virtualize>

The format of the signature is described in Signature Specification.

Examples:

<virtualize>
   <track class="javax.servlet.http.HttpServlet" method="service" signature="(Ljavax/servlet/http/HttpServletRequest;Ljavax/servlet/http/HttpServletResponse;)V" push="false">
      <code><![CDATA["return $1.getSession().getId();"]]></code>
   </track>
</virtualize>

<virtualize>
   <track class="javax.ejb.SessionBean" method="setSessionContext" signature="(Ljavax/ejb/SessionContext)V" push="true">
      <code><![CDATA["return $1.getEJBObject().getHandle().toString();"]]></code>
   </track>
</virtualize>

<virtualize>
   <track class="javax.ejb.EntityBean" method="setEntityContext" signature="(Ljavax/ejb/EntityContext)V" push="true">
      <code><![CDATA["return $1.getPrimaryKey().toString();"]]></code>
   </track>
</virtualize>

These examples are hard-coded in the agent and thus unnecessary in your rules.xml file. However, these lines show how the process works so it can be implemented for any number of protocols, other than HTTP and EJB without recompiling the agent.

The value of the class attribute is the class from which we gain access to a session.

The value of the method and signature attributes determine the method that, when invoked, computes the session identifier. This computation uses the value of the code attribute. $0 represents the source object. $1, $2, and so on, are the method arguments.

The push attribute determines how we store that session for later use by VSE frames.

• push="true" specifies that the container sets the session, and we keep a mapping of object to session.
• push="false" specifies that session is thread-scoped and we store in a thread-local variable.

The innermost session (identifier) is served back through VSE in the com.itko.lisa.remote.vse.VSEFrame getSessionId() method. For more information, see the JavaDocs in the LISA_HOME\doc directory.