Service interceptor project template

The Java service interceptor project template includes the necessary project structure, pre-implemented interfaces, and essential boilerplate code to help you develop service interceptors quickly. Instead of writing the entire implementation from scratch, you can focus on adding your custom interception logic to designated placeholders within the template. It is essential that you understand the template's structure before you begin writing code.

A service interceptor is defined by implementing the com.esri.arcgis.enterprise.interceptor.server.IServerServicesInterceptor interface. This interface is required and contains two key methods: init() and intercept(). Here is an example:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
@Interceptor(

    name = "MyInterceptor",
    displayName = "My Service Interceptor",
    description = "Logs basic request info",
    urlPatterns = {"/services"}
)

public class MyInterceptor implements IServerServices Interceptor {
    public void init(IInterceptorConfig config,
                    IServerServicesInterceptorHelper helper,
                    IServerInterceptorLogger logger) {
            logger.info("Interceptor initialized.");
    }

    public void intercept(IInterceptorRequest request,
                    IInterceptorResponse response,
                    IServerServices InterceptorChain chain)
            throws IOException, ServletException {
        if (chain.isRestRequestChain()) {
            // Before request reaches the service
            chain.intercept(request, response);
            // After service generates the response
        } else {
            chain.intercept(request, response);
        }
    }
}

@Interceptor annotation

Every service interceptor must include the @Interceptor annotation to define metadata that ArcGIS Server uses during registration and at runtime.

The following element pairs are supported:

• name—Defines the unique identifier for the service interceptor. It must not include spaces or special characters.
• displayName—Defines a user-friendly name shown in tools such as ArcGIS Server Manager or the Admin API. It can include spaces but not special characters.
• description—Provides a detailed explanation of the service interceptor's functions. It appears in the ArcGIS Server administrative client to help administrators understand the purpose of the service interceptor.
• urlPatterns—Defines one or more URL patterns that determine which services the interceptor will act on. Full match, partial match, path-based, and multiple URL patterns are supported. For more information, see URL patterns.
• properties—Key-value pairs used for dynamic configuration. These can control aspects such as behavior toggles, allowed fields, or thresholds, and are accessible at runtime via IInterceptorConfig. For more information, see Interceptor properties.

1
2
3
4
5
6
7
@Interceptor (
    name = "AuditLogInterceptor",
    displayName = "Enterprise Interceptor",
    description = "Logs service access events for auditing.",
    urlPatterns = {"/services"},
    properties = {"logLevel=INFO", "trackUser=true"}
)

init() method

The init() method is invoked once, when the service interceptor is instantiated, which is typically at the time of registration with ArcGIS Server. This is the initialization block where you write code to set up operations that only need to be executed once (for example, establishing a connection with third-party systems or databases and reading other configuration values).

Method signature

1
2
void init(IInterceptorConfig interceptorConfig,
        IServerServicesInterceptorHelper interceptorHelper, IServerInterceptorLogger logger)

• IInterceptorConfig—Provides access to the configuration and properties defined in the service interceptor annotation.
• IServerServicesInterceptorHelper—Offers utility methods for working with services.
• IServerInterceptorLogger—Enables logging of interceptor activity for debugging and auditing.

intercept() method

The intercept() method is called for each request made to a service that matches the URL patterns defined in the interceptor annotation. This is where the core request and response interception logic is implemented.

Method signature

1
2
3
4
void intercept (IInterceptorRequest request,
            IInterceptorResponse response,
            IServerServicesInterceptorChain filterChain)
    throws IOException, ServletException

• IInterceptorRequest—A wrapped version of the standard HttpServletRequest. It provides access to request metadata, headers, query parameters, body content, and other HTTP request attributes relevant to the service being intercepted.
• IInterceptorResponse—A wrapped version of the standard HttpServletResponse. It provides methods for reading and modifying the response before it is returned to the client. You can manipulate headers, status codes, and payload content as needed.
• IServerServicesInterceptorChain—Provides utility methods for controlling the flow of the interceptor chain. The most common method is isRestRequestChain(), which helps determine whether the current request is part of a REST-based service chain. The method filterChain.intercept(request, response) must be called to forward the request to the next interceptor or target service.

You can do the following things within the intercept() method:

• Add request interception logic before calling filterChain.intercept(request, response);
• Add response interception logic after that call.
• A check like filterChain.isRestRequestChain() can be used to ensure the interceptor only operates on REST-based requests.

1
2
3
4
5
6
7
8
if (filterChain.isRestRequestChain()) {
    logger.info("Processing REST request...");
    // Request interception logic here
    filterChain.intercept(request, response);
    // Response interception Logic here
} else {
    filterChain.intercept(request, response);
}