IBM WebSphere Application ServerTM
Release 7

com.ibm.websphere.j2c
Interface InteractionMetrics

All Known Subinterfaces:
ConnectionEventListener

public interface InteractionMetrics

Interface name : InteractionMetrics

This InteractionMetrics interface introduces the capability for any ResourceAdapter to participate in reporting its use time in a request and have that time reported by the various Request Metrics reporting tools available for WebShpere.

The WebSphere ConnectionEventListener will implement this class. We keep an EventListener associated with each ManagedConnection. By tracking the interaction time on a per ManagedConnection basis we can gather use time statistics for each ManagedConnection which will be useful data for solving performance related problems.

ResourceAdapters wishing to participate in various WebSphere RequestMetric tools, diagnostic tools, etc. will need to use this interface, which will be implemented on the ConnectionEventListner we register with every ResourceAdapter ManagedConnection we create, to report the usage time associated with the subset of calls as defined below in the table below.

The call flow in the resource adapter is the following:

  1. At the beginning of each method to report statics for, call isInteractionMetricsEnabled.
  2. If it returns false, do nothing for the rest of this request.
  3. If it returns true, call preInteraction.
  4. Before sending the request to the downstream EIS process, call getCorrelator and attach the correlator with the request so that the downstream EIS process can get the correlator.
  5. Do the actual work.
  6. At the end of the execute method, call getTranDetailLevel. Based on the level, collect transaction detail information as specified in the table listed in the postInteraction method, and then call postInteraction.

Note that the Websphere runtime will track and report the time for the calls which either come into our code through the spi or come out of our code through the spi as identified in the table.

The following table will detail the minimum expected content for the detailed info for the various levels:

ResourceAdapter Metric Instrumentation
Instrumentation Point
Package
Interface
Methods
Probe Action
Level 1
Probe Action
Level 2
Probe Action
Level 3
These methods must be intrumented by the ResourceAdapter

Package: javax.resource.cci
Interface: Interaction
Methods:
  • execute(InteractionSpec, Record)
  • execute(InteractionSpec, Record, Record)
Performance Readable form of the javax.resource.cci.InteractionSpec Readable form of the javax.resource.cci.InteractionSpec
AdapterName
AdapterShortDescription
AdapterVendorName
AdapterVersion
InteractionSpecsSupported
SpecVersion
These methods must be intrumented by the ResourceAdapter

Package: javax.resource.cci
Interface: LocalTransaction

Methods:
  • begin
  • commit
  • rollback
Performance Performance AdapterName
AdapterShortDescription
AdapterVendorName
AdapterVersion
InteractionSpecsSupported
SpecVersion
See Note 1

Package: javax.resource.spi
Interface: ManagedConnectionFactory
Methods:
  • createManagedConnection(Subject subject, ConnectionRequestInfo cxRequestInfo)
  • matchManagedConnections(Set connectionSet, Subject subject, ConnectionRequestInfo cxRequestInfo)
  • createConnectionFactory()
Performance Performance AdapterName
AdapterShortDescription
AdapterVendorName
AdapterVersion
InteractionSpecsSupported
SpecVersion
See Note 1

Package: javax.resource.spi
Interface: ManagedConnection
Methods:
  • getConnection(Subject subject, ConnectionRequestInfo cxRequestInfo)
Performance EISProductName
EISProductVersion
UserName
ConnectionFactory JNDI Name EISProductName
EISProductVersion
UserName
AdapterName
AdapterShortDescription
AdapterVendorName
AdapterVersion
InteractionSpecsSupported
SpecVersion
See Note 1

Package: javax.resource.spi
Interface: ManagedConnection
Methods:
  • cleanup()
  • destroy()
Performance Performance AdapterName
AdapterShortDescription
AdapterVendorName
AdapterVersion
InteractionSpecsSupported
SpecVersion
See Note 1

Package: javax.resource.spi
Interface: LocalTransaction
Methods:
  • begin
  • commit
  • rollback
Interface: XAResource
Methods:
  • commit(Xid xid, boolean onePhase)
  • end(Xid xid, int flags)
  • forget(Xid xid)
  • prepare(Xid xid
  • rollback(Xid xid)
  • start(Xid xid, int flags)
Performance Performance AdapterName
AdapterShortDescription
AdapterVendorName
AdapterVersion
InteractionSpecsSupported
SpecVersion

NOTE 1: the JCA Runtime has access to these method calls and information and can call the pre/postInteraction methods surrounding the calls it makes to these methods. It will do that for the RA so the RA should NOT make calls to report usage for these methods.

When providing dynamic infomation for a given segment of an interaction, the following properties/capabilities will be considered standard for all JCA Resource adapters as defined in the JCA 1.5 or later specification: (whenever representing this information you must use these names as spelled).

  1. ServerName
  2. PortNumber
  3. UserName
  4. Password
  5. ConnectionURL
  6. EISProductName
  7. EISProductVersion
  8. MaxConnections
  9. UserName
  10. AdapterName
  11. AdapterShortDescription
  12. AdapterVendorName
  13. AdapterVersion
  14. InteractionSpecsSupported
  15. SpecVersion
  16. supportsExecuteWithInputAndOutputRecord
  17. supportsExecuteWithInputRecordOnly
  18. supportsLocalTransactionDemarcation
  19. deletesAreDetected
  20. insertsAreDetected
  21. othersDeletesAreVisible
  22. othersInsertsAreVisible
  23. othersUpdatesAreVisible
  24. ownDeletesAreVisible
  25. ownInsertsAreVisible
  26. ownUpdatesAreVisible
  27. supportsResultSetType
  28. supportsResultTypeConcurrency
  29. updatesAreDetected


Field Summary
static int RM_ARM_ABORT
          RM_ARM_ABORT - Aborted is intended for cases where the transaction is interrupted/cancelled before completion.
static int RM_ARM_FAILED
          RM_ARM_FAILED - Failed is intended for cases where program logic determines that an operation cannot be successfully completed due to some discovered error.
static int RM_ARM_GOOD
          RM_ARM_GOOD - Good, the request is completed successfully
static int RM_ARM_UNKNOWN
          RM_ARM_UNKNOWN - Unknown is used when the transaction status is not known.
static int TRAN_DETAIL_LEVEL_BASIC
          At this level, component will call preInteraction/postInteraction and pass context data matching basic context names.
static int TRAN_DETAIL_LEVEL_EXTENDED
          At this level, component will call preInteraction/postInteraction and pass context data matching extended context names.
static int TRAN_DETAIL_LEVEL_PERF
          At this level, component will call preInteraction/postInteraction without passing any context data.
 
Method Summary
 byte[] getCorrelator()
           
 int getTranDetailLevel()
          Returns one of the following: TRAN_DETAIL_LEVEL_PERF At this level, component will call preInteraction/postInteraction without passing any context data.
 boolean isInteractionMetricsEnabled()
          Indicates whether or not the InteractionMetrics is enabled for instrumentation.
 void postInteraction(java.lang.Object ctx, int status)
          The postInteraction method should be called by the ResourceAdapter at the end of any method for which the preInteraction call was made.
 void postInteraction(java.lang.Object ctx, int status, java.util.Properties detailInfo)
          The postInteraction method should be called by the ResourceAdapter at the end any method for which the preInteraction call was made.
 java.lang.Object preInteraction(java.lang.String[] ctxData)
          The preInteraction method should be called by the ResourceAdapter at the start of any methods for which interaction time is to be measured, including but not limited to the following: ConnectionFactory.getConnection methods.
 

Field Detail

TRAN_DETAIL_LEVEL_PERF

static final int TRAN_DETAIL_LEVEL_PERF
At this level, component will call preInteraction/postInteraction without passing any context data.

See Also:
Constant Field Values

TRAN_DETAIL_LEVEL_BASIC

static final int TRAN_DETAIL_LEVEL_BASIC
At this level, component will call preInteraction/postInteraction and pass context data matching basic context names. This informaction will vary depending on the particular method being executed. See the method identifier constants for more info.

See Also:
Constant Field Values

TRAN_DETAIL_LEVEL_EXTENDED

static final int TRAN_DETAIL_LEVEL_EXTENDED
At this level, component will call preInteraction/postInteraction and pass context data matching extended context names. This informaction will vary depending on the particular method being executed. See the method identifier constants for more info.

See Also:
Constant Field Values

RM_ARM_GOOD

static final int RM_ARM_GOOD
RM_ARM_GOOD - Good, the request is completed successfully

See Also:
Constant Field Values

RM_ARM_ABORT

static final int RM_ARM_ABORT
RM_ARM_ABORT - Aborted is intended for cases where the transaction is interrupted/cancelled before completion.

See Also:
Constant Field Values

RM_ARM_FAILED

static final int RM_ARM_FAILED
RM_ARM_FAILED - Failed is intended for cases where program logic determines that an operation cannot be successfully completed due to some discovered error.

See Also:
Constant Field Values

RM_ARM_UNKNOWN

static final int RM_ARM_UNKNOWN
RM_ARM_UNKNOWN - Unknown is used when the transaction status is not known.

See Also:
Constant Field Values
Method Detail

getCorrelator

byte[] getCorrelator()
Returns:
return the ARM correlator in byte[]. This method should be called before the resource adapter sends out the request to the downstream EIS. The resource adapter should attach the correlator with the JCA protocol so that the downstream EIS process can extract it and correlate the request.

getTranDetailLevel

int getTranDetailLevel()
Returns one of the following:
TRAN_DETAIL_LEVEL_PERF
At this level, component will call preInteraction/postInteraction without passing any context data.
TRAN_DETAIL_LEVEL_BASIC
At this level, component will call preInteraction/postInteraction and pass context data matching basic context names. This informaction will vary depending on the particular method being executed. See the method identifier constants for more info.
TRAN_DETAIL_LEVEL_EXTENDED
At this level, component will call preInteraction/postInteraction and pass context data matching extended context names. This informaction will vary depending on the particular method being executed. See the method identifier constants for more info.

Returns:
one of the following: TRAN_DETAIL_LEVEL_PERF, TRAN_DETAIL_LEVEL_BASIC, TRAN_DETAIL_LEVEL_EXTENDED
The returned integer indicates how much transaction detail information is needed for postInteraction. This method should be called right before postInteraction.

preInteraction

java.lang.Object preInteraction(java.lang.String[] ctxData)
The preInteraction method should be called by the ResourceAdapter at the start of any methods for which interaction time is to be measured, including but not limited to the following:

Note: this method returns an opaque context Object. If during the course of this methods execution the ResourceAdapter switches threads then the context object must be passed along since it will then be required on the postInteraction call.

Parameters:
ctxData - should be the actual class name (array index 0)and method name (array index 1) with the signature that preInteraction is called with.
Returns:
Oject is only needed if the ResourceAdapter will switch threads before the current method ends.

postInteraction

void postInteraction(java.lang.Object ctx,
                     int status)
The postInteraction method should be called by the ResourceAdapter at the end of any method for which the preInteraction call was made.

Parameters:
ctx - - Oject is only needed if the ResourceAdapter switches threads between the start and the end of the current method. If not needed pass null.
status - will return one of the following constants depending on if the transaction is successful or not.
  • RM_ARM_GOOD
  • RM_ARM_ABORT
  • RM_ARM_FAILED

postInteraction

void postInteraction(java.lang.Object ctx,
                     int status,
                     java.util.Properties detailInfo)
The postInteraction method should be called by the ResourceAdapter at the end any method for which the preInteraction call was made.

Parameters:
ctx - Oject is only needed if the ResourceAdapter switches threads between the start and the end of the current method. If not needed pass null.
status - will return one of the following constants depending on if the transaction is successful or not.
  • RM_ARM_GOOD
  • RM_ARM_ABORT
  • RM_ARM_FAILED
detailInfo - If required then the detailInfo which is passed back is a property object which contains additional dynamic content which is appropriate for the given TRAN_DETAIL_LEVEL.

isInteractionMetricsEnabled

boolean isInteractionMetricsEnabled()
Indicates whether or not the InteractionMetrics is enabled for instrumentation. This method should be called for every execute method.

Returns:
boolean When it returns false, the resource adapter should not call preInteraction/postInteraction/getCorrelator.

When it returns true, the resource adapter will call preInteraction/postInteraction/getCorrelator.


IBM WebSphere Application ServerTM
Release 7