public interface Interceptor
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.
Modifier and Type | Field and Description |
---|---|
static java.lang.String |
CFG_AD_SEQUENCE_ALIAS
Sequence attribute definition name.
|
static int |
DEFAULT_SEQUENCE_NUMBER
The default sequence number.
|
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.
|
static final int DEFAULT_SEQUENCE_NUMBER
static final java.lang.String CFG_AD_SEQUENCE_ALIAS
java.lang.String getName()
void preInvoke(java.util.Map<java.lang.Object,java.lang.Object> requestStateMap, HttpZosConnectRequest httpZosConnectRequest, Data data) throws InterceptorException
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.InterceptorException
- If an error was encountered during the interceptor's execution.void postInvoke(java.util.Map<java.lang.Object,java.lang.Object> requestStateMap, HttpZosConnectRequest httpZosConnectRequest, Data data) throws InterceptorException
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.InterceptorException
- If an error was encountered during the interceptor's execution.int getSequence()
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.