com.ibm.wsspi.zos.connect

Interface Interceptor



  • public interface Interceptor
    Defines an OSGI service that performs an action before and after the execution of a HTTP work request.

    When more than one interceptors are configured, the order of execution is determined by a sequence number. See getSequence().

    Interceptors' postInvoke methods are processed in the opposite order the interceptors' preInvoke methods are processed. If interceptors specify invalid sequence numbers or the same sequence numbers, there is no predictable processing order. Interceptors are allowed to return a HTTP servlet response code if set in a InterceptorException. The response code is processed only when the InterceptorException is thrown during preInvoke. Exceptions thrown during preInvoke immediately fail the request and the exception is reported. When an exception is detected, prior to exiting the request, postInvoke is driven on those interceptors that successfully processed preInvoke and the one that reported the error.

    • Method Summary

      Methods 
      Modifier and Type Method and Description
      java.lang.String getName()
      Returns the name that identifies the interceptor.
      int getSequence()
      Retrieves the number to be used to establish the sequence in which the interceptor is to be processed with respect to other configured interceptors.
      void postInvoke(java.util.Map<java.lang.Object,java.lang.Object> requestStateMap, HttpZosConnectRequest httpZosConnectRequest, Data data)
      Runs implementor specific logic after a service endpoint has completed executing the request.
      void preInvoke(java.util.Map<java.lang.Object,java.lang.Object> requestStateMap, HttpZosConnectRequest httpZosConnectRequest, Data data)
      Runs implementor specific logic before a service endpoint is executed to drive the request.
    • Field Detail

      • DEFAULT_SEQUENCE_NUMBER

        static final int DEFAULT_SEQUENCE_NUMBER
        The default sequence number. It indicates that the interceptor will run after all other interceptors defining a valid sequence number have run. Furthermore, it indicated that execution ordering is not desired.
        See Also:
        Constant Field Values
      • CFG_AD_SEQUENCE_ALIAS

        static final java.lang.String CFG_AD_SEQUENCE_ALIAS
        Sequence attribute definition name.
        See Also:
        Constant Field Values
    • Method Detail

      • getName

        java.lang.String getName()
        Returns the name that identifies the interceptor.
        Returns:
        The interceptor's name.
      • preInvoke

        void preInvoke(java.util.Map<java.lang.Object,java.lang.Object> requestStateMap,
                     HttpZosConnectRequest httpZosConnectRequest,
                     Data data)
                       throws InterceptorException
        Runs implementor specific logic before a service endpoint is executed to drive the request. If an exception is thrown during the execution of this method, the request is failed and the exception is reported.
        Parameters:
        requestStateMap - A map object that holds implementor data that can be retrieved and/or updated by artifacts that have a reference to it (i.e. Service.invoke()). z/OS Connect creates a new map and makes it available to the consuming artifacts per request. More specifically, z/OS Connect does not preserve this map or its contents across requests. The the life cycle of the map is that of a single request. Users must ensure that map key entries are unique. Key string entries starting with "IBM_ZOS_CONNECT" are reserved for z/OS Connect use.
        httpZosConnectRequest - A zosConnect representation of a HTTP servlet request.
        data - Common request specific data.
        Throws:
        InterceptorException - If an error was encountered during the interceptor's execution.
      • postInvoke

        void postInvoke(java.util.Map<java.lang.Object,java.lang.Object> requestStateMap,
                      HttpZosConnectRequest httpZosConnectRequest,
                      Data data)
                        throws InterceptorException
        Runs implementor specific logic after a service endpoint has completed executing the request.
        Parameters:
        requestStateMap - A map object that holds implementor data that can be retrieved and/or updated by artifacts that have a reference to it (i.e. Service.invoke()). z/OS Connect creates a new map and makes it available to the consuming artifacts per request. More specifically, z/OS Connect does not preserve this map or its contents across requests. The the life cycle of the map is that of a single request. Users must ensure that map key entries are unique. Key string entries starting with "IBM_ZOS_CONNECT" are reserved for z/OS Connect use.
        httpZosConnectRequest - A zosConnect representation of a HTTP servlet request.
        data - Common response specific data.
        Throws:
        InterceptorException - If an error was encountered during the interceptor's execution.
      • getSequence

        int getSequence()
        Retrieves the number to be used to establish the sequence in which the interceptor is to be processed with respect to other configured interceptors.

        Implementors can define an attribute definition "sequence" when defining the metatype for the OSGI service representing the interceptor.

        The sequence attribute definition is not required; therefore, a default value of DEFAULT_SEQUENCE_NUMBER (0) must be returned when this method is invoked. Setting a default sequence value is an indication that order of execution is not desired. Furthermore, these interceptors' preInvoke method will be processed after the preInvoke method for those interceptors with a valid configured sequence value have run.

        A valid sequence number is a positive integer greater than 0 (DEFAULT_SEQUENCE_NUMBER) and less than or equal to Integer.MAX_VALUE.

        Interceptors that do NOT define a valid sequence number are treated in the same manner as those that define a default value.

        Interceptors that define a valid sequence number will run in the order the sequence number specifies. If multiple interceptors are defined with the same sequence number, there are no execution ordering guarantees within that sequence group.

        For example, given the following list with 4 configured interceptors:

        <interceptorA id="myInterceptorA" sequence="1" ... />
        <interceptorB id="myInterceptorB" sequence="2" ... />
        <interceptorC id="myInterceptorC" sequence="2" ... />
        <interceptorD id="myInterceptorD" ... />
        <interceptorE id="myInterceptorE" ... />

        The order in which the interceptors' invoke and post invoke methods will be called are as follows:

        InterceptorA's preInvoke method is called first.
        InterceptorB's preInvoke method is called second or third.
        InterceptorC's preInvoke method is called second or third.
        InterceptorD's preInvoke method is called fourth or fifth.
        InterceptorE's preInvoke method is called fourth or fifth.

        InterceptorE's postInvoke method is called first or second.
        InterceptorD's postInvoke method is called first or second.
        InterceptorC's postInvoke method is called third or fourth.
        InterceptorB's postInvoke method is called third or fourth.
        InterceptorA's postInvoke method is called fifth.

        Returns:
        The default or configured sequence number.