com.ibm.websphere.j2c

Interface InteractionMetrics

All known subinterfaces:
ConnectionEventListener

  1. 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

Modifier and Type Field and Description
  1. static
  2. int
RM_ARM_ABORT
RM_ARM_ABORT - Aborted is intended for cases where the transaction is interrupted/cancelled before completion.
  1. static
  2. 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.
  1. static
  2. int
RM_ARM_GOOD
RM_ARM_GOOD - Good, the request is completed successfully
  1. static
  2. int
RM_ARM_UNKNOWN
RM_ARM_UNKNOWN - Unknown is used when the transaction status is not known.
  1. static
  2. int
TRAN_DETAIL_LEVEL_BASIC
At this level, component will call preInteraction/postInteraction and pass context data matching basic context names.
  1. static
  2. int
TRAN_DETAIL_LEVEL_EXTENDED
At this level, component will call preInteraction/postInteraction and pass context data matching extended context names.
  1. static
  2. int
TRAN_DETAIL_LEVEL_PERF
At this level, component will call preInteraction/postInteraction without passing any context data.

Method Summary

Modifier and Type Method and Description
  1. byte[]
getCorrelator()
  1. int
getTranDetailLevel()
Returns one of the following: TRAN_DETAIL_LEVEL_PERF At this level, component will call preInteraction/postInteraction without passing any context data.
  1. boolean
isInteractionMetricsEnabled()
Indicates whether or not the InteractionMetrics is enabled for instrumentation.
  1. 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.
  1. 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.
  1. 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

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

TRAN_DETAIL_LEVEL_BASIC

  1. 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:

TRAN_DETAIL_LEVEL_EXTENDED

  1. 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:

RM_ARM_GOOD

  1. static final int RM_ARM_GOOD
RM_ARM_GOOD - Good, the request is completed successfully
See Also:

RM_ARM_ABORT

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

RM_ARM_FAILED

  1. 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:

RM_ARM_UNKNOWN

  1. static final int RM_ARM_UNKNOWN
RM_ARM_UNKNOWN - Unknown is used when the transaction status is not known.
See Also:

Method Detail

getCorrelator

  1. 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

  1. 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

  1. 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.
  • Connection.close method.
  • Interaction.executes methods.

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

  1. void postInteraction(java.lang.Object ctx,
  2. 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

  1. void postInteraction(java.lang.Object ctx,
  2. int status,
  3. 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

  1. 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.