com.ibm.zosconnect.spi

Interface Interceptor

All Known Subinterfaces:

EarlyFailureInterceptor, EarlyFailureInterceptorRequester, EndpointInterceptor, InterceptorRequester, ServiceProviderInterceptor, TrackingInterceptor

public interface Interceptor

Defines an OSGI service that is invoked before and after the z/OS Connect EE processing of an HTTP request.

When more than one interceptor is configured, the order in which they are called is determined when a sequence number is specified, see getSequence().

The postInvoke methods of interceptors are processed in the opposite order to that in which the preInvoke methods are called. All interceptors configured with a sequence number are called before those without. If an interceptor is configured with an invalid sequence number or a duplicate sequence number, the processing order is undefined. If an API or service is invoked while a configuration refresh is in progress, interceptor methods might not be called as expected. For example, if an interceptor definition is added to the configuration, for a particular request, the preInvoke method might not get called but the postInvoke method would be called. Interceptors can return an HTTP servlet response code by setting it in a InterceptorException. The response code is processed only when the InterceptorException is thrown during preInvoke. An exception thrown by the preInvoke method causes immediate failure of the request, and the exception is logged. In this instance, the postInvoke method is called for all those interceptors for which the preInvoke method had been successfully called, and for the one that reported the error.

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	CFG_AD_SEQUENCE_ALIAS Sequence attribute definition name.
static java.lang.String	copyright_notice
static int	DEFAULT_SEQUENCE_NUMBER The default sequence number.

Method Summary

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 z/OS Connect EE processing of an API, service or an administration request.
void	preInvoke(java.util.Map<java.lang.Object,java.lang.Object> requestStateMap, HttpZosConnectRequest httpZosConnectRequest, Data data) Runs implementor specific logic before z/OS Connect EE processing of an API, service or an administration request.

Field Detail

copyright_notice

static final java.lang.String copyright_notice

See Also:

Constant Field Values

DEFAULT_SEQUENCE_NUMBER

static final int DEFAULT_SEQUENCE_NUMBER

The default sequence number. It indicates the interceptor is called after all interceptors defined with a valid sequence number. Furthermore, it indicates that execution ordering for this interceptor is not required.

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. This name is used to identify the interceptor in z/OS Connect EE messages. The default interceptor name is "UNNAMED".

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 z/OS Connect EE processing of an API, service or an administration 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 (e.g. Interceptor.preInvoke(), Inteceptor.postInvoke()). z/OS Connect EE creates a new map and makes it available to the consuming artifacts per request. Prefix key strings with your own unique identifier to avoid clashes with those created by other interceptor providers. Key string entries starting with "IBM_ZOS_CONNECT" are reserved for z/OS Connect EE use.

httpZosConnectRequest - A z/OS Connect representation of a HTTP servlet request.

data - 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 z/OS Connect EE processing of an API, service or an administration 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 (e.g. Interceptor.preInvoke(), Inteceptor.postInvoke()). z/OS Connect EE creates a new map and makes it available to the consuming artifacts per request. Prefix key strings with your own unique identifier to avoid clashes with those created by other interceptor providers. Key string entries starting with "IBM_ZOS_CONNECT" are reserved for z/OS Connect EE use.

httpZosConnectRequest - A z/OS Connect EE representation of a HTTP servlet request.

data - 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; in this case, 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. Interceptors with a default sequence value are processed after those with a valid configured sequence value.

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 are run in the order the sequence number specifies. If multiple interceptors are defined with the same sequence number, the order of execution is indeterminate 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.