Introduction to Service Interceptor Project Template

This topic provides an overview of the recommended Java project template for developing a service interceptor. It is important to understand the structure of the service interceptor project template before you start writing code. The template includes the necessary project structure, pre-implemented interfaces, and essential boilerplate code to help you get started quickly. Instead of writing the entire implementation from scratch, you can focus on adding your custom interception logic to designated placeholders within the template.

A service interceptor is defined by implementing the com.esri.arcgis.enterprise.interceptor.server.IServerServicesInterceptor interface. This interface is required and contains three key methods: init(), intercept() and cleanup(). 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
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
@Interceptor(
		name = "SimpleAuditLogging",
		displayName = "Service Interceptor",
		description = "Service Interceptor Description",
		urlPatterns = {"/MapServer/","/FeatureServer/"},
		properties = {"prop1=value1"},
		chainingOrder = 1
)
public class SimpleAuditLogging implements IServerServicesInterceptor {
	private IInterceptorConfig interceptorConfig;
	private IServerServicesInterceptorHelper interceptorHelper;
	private IServerInterceptorLogger logger;

	@Override
	public void init(IInterceptorConfig interceptorConfig,
					 IServerServicesInterceptorHelper interceptorHelper,
					 IServerInterceptorLogger logger){
		this.interceptorConfig = interceptorConfig;
		this.interceptorHelper = interceptorHelper;
		this.logger = logger;
	}

	@Override
	public void intercept(
			IInterceptorRequest request,
			IInterceptorResponse response,
			IServerServicesInterceptorChain filterChain) throws IOException, ServletException {

		if (!filterChain.isRestRequestChain()) {
			filterChain.intercept(request, response);
			return;
		}

		//To intercept the request, write your code here
		logger.info("Inside SimpleAuditLogging.intercept");

		filterChain.intercept(request, response);

		//To intercept the response, write your code here

	}

  /*
   * Perform any cleanup required by the interceptor at the end of its lifecycle
  */
  @Override
  public void cleanup(){

  }

}

@Interceptor annotation

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 Admin Directory. It can include spaces but not special characters.
• description—Provides a detailed explanation of the service interceptor. It appears in the ArcGIS Server Admin Directory to help administrators understand the purpose of the service interceptor.
• urlPatterns—Defines one or more URL patterns that determine which services the interceptor will be intercepted. For more information, see URL patterns.
• properties—Key-value pairs used for dynamic configuration. For more information, see Interceptor properties.
• chainingOrder—Defines the chaining order for service interceptor if this interceptor participates in chain. For more information, see chaining interceptors.

1
2
3
4
5
6
7
8
@Interceptor(
		name = "SimpleAuditLogging",
		displayName = "Service Interceptor",
		description = "Service Interceptor Description",
		urlPatterns = {"/MapServer/","/FeatureServer/"},
		properties = {"prop1=value1"},
		chainingOrder = 1
)

init() method

The init() method is invoked once, when the service interceptor is instantiated—typically at the time of registration with ArcGIS Server. This is the appropriate place to perform one-time initialization tasks such as:

• Establishing database connections
• Initializing connections to third-party systems
• Loading configuration files or metadata
• Creating temporary workspaces or caches
• Preparing reusable resources required during request interception

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 every request made to a service that matches the urlPatterns defined in the interceptor annotation. This is where the core request and response interception logic are 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 to read or modify the response before it is returned to the client. You can manipulate headers, status codes, and payload content as needed.
• IServerServicesInterceptorChain: Provides utility methods to control 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 the target service.

Within this 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
9
10
11
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);
}

cleanup() method

The cleanup() method is invoked once, when the service interceptor is unregistered from ArcGIS Server. Its purpose is to safely release all resources allocated during initialization or runtime, including:

• Closing database connections
• Releasing file handles or network streams
• Clearing temporary caches or workspaces
• Disposing of in-memory objects
• Preventing resource leaks such as DB locks or memory retention

Proper use of cleanup() ensures clean shutdown, efficient resource utilization, and prevents issues during subsequent registrations or server restarts.

Method signature

1
void cleanup()