Monitoring interceptor interfaces

You create a monitoring interceptor by implementing the Interceptor interface and optionally, one or more of its subinterfaces.

Before you study this topic, you should first be familiar with the information in Creating an interceptor.

The following IBM z/OS Connect SPI Interceptor sub-interfaces are applicable in both zosConnect-2.0 and zosConnect-3.0 unless specified.

com.ibm.zosconnect.spi.Interceptor: Implement this interface to obtain monitoring data for API requests into the z/OS Connect Server (API provider).
com.ibm.zosconnect.spi.ServiceProviderInterceptor: Implement this interface to obtain SoR specific monitoring data for API requests.
com.ibm.zosconnect.spi.EarlyFailureInterceptor: Implement this interface to monitor API requests that fail authentication or are badly formed.
com.ibm.zosconnect.spi.EarlyFailureInterceptorRequester zosConnect-2.0: Implement this interface to monitor API requests from a z/OS application that fail authentication or are badly formed.
com.ibm.zosconnect.spi.InterceptorRequester: Implement this interface to monitor API requests from a z/OS application that invoke a service in a REST endpoint.
com.ibm.zosconnect.spi.EndpointInterceptor: Implement this interface to obtain API endpoint-specific monitoring data for requests from a z/OS application.
com.ibm.zosconnect.spi.TrackingInterceptor: Implement this interface to selectively track API requests that invoke a service in a SoR. It enables a stakeholder to add their stakeholder token to the tracking token sent to the SoR.

For the Java™ API documentation, see z/OS Connect SPI. This documentation is also available as a separate file at <installation_path>/doc/javadoc.zip and <installation_path>/doc/javadoc.oas3.zip depending on which IBM z/OS Connect feature (zosConnect-2.0 or zosConnect-3.0) you are using.

z/OS Connect monitoring points for the API provider

z/OS Connect provides five points where interceptors can monitor requests for the API provider, as illustrated in Figure 1. The following diagram is an illustration for zosConnect-3.0 with the use of z/OS Assets. The only difference between the zosConnect-2.0 and zosConnect-3.0 implementations is that instead of a z/OS Asset, the zosConnect-2.0 implementation uses service and a service provider instead.

When the request is received from the client, the preInvoke method is called. The preSorInvoke method is called when the request is sent to the system of record (SoR). The postSorInvoke method is called when the response is returned from the SoR and the postInvoke method is called just before the response is returned to the client. — Figure 1. Monitoring interceptor points for the z/OS Connect zosConnect-3.0 API provider

preInvoke: Required interface: Interceptor; The preInvoke method is called when a request is received from the client and initial validation of the request is complete. This method can throw an interceptor exception to reject the request at this point.; zosConnect-3.0 For z/OS Connect zosConnect-3.0, the exception does not cause the request to be rejected.
preSorInvoke: Required interface: ServiceProviderInterceptor; The preSorInvoke method is called when a request is sent to the SoR.
postSorInvoke: Required interface: ServiceProviderInterceptor; The postSorInvoke method is called when a response is received from the SoR.
postInvoke: Required interface: Interceptor; The postInvoke method is called just before a response is returned to the client.
earlyFailure: Required interface: EarlyFailureInterceptor; The earlyFailure method is called when a request fails validation before the preInvoke method is called. No other interceptors are called. Early failures can be caused by errors such as incorrect URLs, or authentication or authorization failures.; zosConnect-2.0 The earlyFailure method is invoked only for interceptors that are configured at the global level.

z/OS Connect monitoring points for the API requester

z/OS Connect zosConnect-2.0 provides five monitoring points for the API requester, as illustrated in Figure 2.

z/OS Connect zosConnect-3.0 provides four monitoring points as illustrated in Figure 3.

When the request is received from the client, the preInvokeRequester method is called. The preEndpointInvoke method is called when the request is sent to the API endpoint. The postEndpointInvoke method is called when the response is returned from the API endpoint and the postInvokeRequester method is called just before the response is returned to the client. — Figure 2. Monitoring interceptor points for the z/OS Connect zosConnect-2.0 API requester

preInvokeRequester: Required interface: Interceptor; The preInvokeRequester method is called when a request is received from the z/OS application and initial validation of the request is complete. This method can throw an interceptor exception to reject the request.
preEndpointInvoke: Required interface: EndpointInterceptor; The preEndpointInvoke method is called when a request is sent to the API endpoint.
postEndpointInvoke: Required interface: EndpointInterceptor; The postEndpointInvoke method is called when a response is received from the API endpoint.
postInvokeRequester: Required interface: Interceptor; The postInvokeRequester method is called just before a response is returned to the z/OS application.
earlyFailureRequester zosConnect-2.0: Required interface: EarlyFailureInterceptor; The earlyFailureRequester method is called when a request fails validation before the preInvokeRequester method is called. No other interceptors are called. Early failures can be caused by errors such as incorrect URLs, or authentication or authorization failures.; The earlyFailureRequester method is invoked only for interceptors that are configured at the global level.