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

      Fields 
      Modifier and Type Field and Description
      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

      Methods 
      Modifier and Type Method and Description
      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:
        • 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

        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 9.0