RESTful interceptor user exit

You can intercept the inbound requests and responses for FTM web services that are acting as a service provider. For FTM web services that are acting as a client, you can intercept outbound requests and responses.

FTM web services as a service provider

For FTM web services that are acting as a service provider, you can intercept an inbound request or a response.

Figure 1. Inbound request and response sequence diagram

Service provider request interceptor

You can intercept the inbound requests for any FTM web services that are acting as a service provider. Access to the request information happens before the FTM web services start to process the HTTP request.

The following code snippet is an example of the interface. For more information about the current function signature, see the RESTful web services SDK.
/**
 * You can ‘intercept’ the inbound requests for any FTM web service that is acting as a service provider.
 * Access to the request information happens before the FTM web service starts to process the HTTP request.
 *
 * @param  requestContext
 * @param  body
 * @param  uriInfo
 * @throws RestfulInterceptorException
 */
public void filter(ContainerRequestContext requestContext, String body, UriInfo uriInfo) throws RestfulInterceptorException;

Service provider response interceptor

You can intercept the response for any FTM web services that are acting as a service provider. Access to the response information happens after the FTM web services processed the request.

The following code snippet is an example of the interface. For more information about the current function signature, see the RESTful web services SDK.
/**
 * You can ‘intercept’ the response for any FTM web service that is acting as a service provider.
 * Access to the response information happens after the FTM web service processed the request.
 *
 * @param  requestContext
 * @param  responseContext
 * @param  status
 * @param  body
 * @throws RestfulInterceptorException
 */
public void filter(ContainerRequestContext requestContext, ContainerResponseContext responseContext, int status, String body) throws RestfulInterceptorException;

FTM web services as a client

For FTM web services that are acting as a client, you can intercept an outbound request or a response.

Figure 2. Outbound request and response sequence diagram

Client request interceptor

You can intercept the outbound client request for any FTM web services that are acting as a client. Access to the request information happens before the request is placed on the network.

The following code snippet is an example of the interface. For more information about the current function signature, see the RESTful web services SDK.
/**
 * You can ‘intercept’ the outbound client request for any FTM web service that is acting as a client
 * which means making an outbound web service call to another HTTP endpoint. Access to the request
 * information happens before the request is placed on the network.
 *
 * @param  requestContext
 * @param  body
 * @param  uri
 * @throws RestfulInterceptorException
 */
public void filter(ClientRequestContext requestContext, String body, URI uri) throws RestfulInterceptorException;

Client response interceptor

You can intercept the corresponding client response for any FTM web services that are acting as a client (HTTP response from the client invocation). Access to the response information happens after FTM processes the response and before the response is sent back to the caller.

The following code snippet is an example of the interface. For more information about the current function signature, see the RESTful web services SDK.
/**
 * You can ‘intercept’ the corresponding client response for any FTM web service that is acting as a client
 * (HTTP response from the client invocation). Access to the response information happens after 
 * FTM processes the response and before the response is sent back to the caller.
 * 
 * @param  requestContext
 * @param  responseContext
 * @param  status
 * @param  body
 * @throws RestfulInterceptorException
 */
public void filter(ClientRequestContext requestContext, ClientResponseContext responseContext, int status, String body) throws RestfulInterceptorException;

Web Services exceptions

You can intercept FTM exception handling for runtime exceptions that occur during any web service processing, either as a service provider or a client. You have access to the originating request that is associated with the exception and also the FTM error model structure that is created during the FTM exception handling process.

Figure 3. Exception sequence diagram
The following code snippet is an example of the interface. For more information about the current function signature, see the RESTful web services SDK.
/**
 * You can ‘intercept’ FTM exception handling for any runtime exception that occurs during any 
 * web service processing, either as a service or a client. You have access to the originating request
 * that is associated with the exception and also the FTM error model structure that is created
 * during the FTM exception handling process.
 *
 * @param  request
 * @param  exception
 * @param  errorModel
 * @throws RestfulInterceptorException
 */
public void filter(HttpServletRequest request, Exception exception, WebServicesError errorModel) throws RestfulInterceptorException;

Sample RESTful interceptor

FTM provides a sample RESTful interceptor that you can use as a template or guide. This sample adds extra logging to the Liberty log files when a certain custom HTTP header exists in either the request or response. The example simulates when a user requires more logging under certain circumstances.

To use the SampleRestfulInterceptor.java sample, you need to compile and package it for FTM to call the interceptor user exit. Details about how to compile and package the sample are in the readme.txt file that is provided with samples. These files are included in the RESTful web services SDK.

The files for the software development kit (SDK) are provided in the FTM artifacts pod and must be downloaded from the pod. For more information about getting files from the artifacts container for your offering, see Getting the files from the artifacts container for your FTM offering.

Configuration

Each Liberty server configuration should have a jvm.options file for setting server-specific options at run time. FTM uses this jvm.options file to enable and configure a supplied RESTful interceptor implementation.

To configure your custom RESTful interceptor, you must supply the following entry in the jvm.options file with a value that represents your custom RESTful interceptor implementation.
#
# Optional entry for configuring the sample FTM RESTful interceptor
#
-Dftm.restful.interceptor.ux=com.ibm.fxh.jaxrs.sdk.userexits.SampleRestfulInterceptor