URL patterns

The urlPatterns element in the @Interceptor annotation defines which REST-based services should be intercepted by a service interceptor. This property is essential for scoping the interceptor's behavior and ensuring it only applies to specific service requests. The urlPatterns element defines the potential target services using simple or advanced patterns, providing fine-grained control over the scope of the interception.

The filtering is performed against the REST path of the service, excluding the context path (/arcgis) and any query or path parameters. You can define one or more patterns to target individual services, partial paths, or apply globally.

The following sections describe some of the pattern types.

Exact Match

Use an exact match when you want to intercept a specific service by name. This is effective for targeting a single known service.

Use dark colors for code blocksCopy
@Interceptor(urlPatterns = {"SampleWorldCities"})

It matches the following:

/arcgis/rest/services/SampleWorldCities/MapServer

It does not match the following:

/arcgis/rest/services/Sample/MapServer
/arcgis/rest/services/SampleWorldCitiesHistoric/MapServer

Partial Match

Prefix-based or partial match allows you to intercept all services whose names start with the provided string. This is effective when your services adhere to a specific naming convention.

Use dark colors for code blocksCopy
@Interceptor(urlPatterns = {"/Sample"})

It matches the following:

/arcgis/rest/services/Sample/MapServer
/arcgis/rest/services/SampleWorldCities/MapServer
/arcgis/rest/services/SampleReports/FeatureServer

It does not match the following:

/arcgis/rest/services/WorldSample/MapServer

Path-based match

You can define full or partial REST paths (excluding context) to match nested folders or specific service groupings. This is effective at intercepting entire service folders or grouped services, such as tools or staging environments.

Use dark colors for code blocksCopy
@Interceptor(urlPatterns = {"/rest/services/Utilities"})

It matches the following:

/arcgis/rest/services/Utilities/Geometry/GeometryServer
/arcgis/rest/services/Utilities/PrintingTools/GPServer

It does not match the following:

/arcgis/rest/services/Public/Countries/MapServer

Global match

Using /services applies the interceptor to all REST-based services. This is effective for interceptors that implement cross-cutting concerns, such as logging, security enforcement, header manipulation, and usage metrics.

Use dark colors for code blocksCopy
@Interceptor(urlPatterns = {"/services"})

It matches all REST services published to an ArcGIS Server site.

Multiple Patterns

You can specify multiple patterns in a list to selectively intercept several services or groups. This is effective when you want one interceptor to apply to a fixed set of services, each possibly serving a different purpose.

Use dark colors for code blocksCopy
@Interceptor(urlPatterns = {"SampleWorldCities", "USA", "/rest/services/Utilities"})

It matches the following:

/arcgis/rest/services/SampleWorldCities/MapServer
/arcgis/rest/services/USA/MapServer
/arcgis/rest/services/Utilities/Geometry/GeometryServer
/arcgis/rest/services/Utilities/PrintingTools/GPServer

It is recommended that you use explicit service names or path-based patterns for predictable behavior, prefix-based patterns if you plan to reuse interceptors across services, and global patterns for cross-service implementations, such as security, auditing, and validations. However, restrict the behavior inside the interceptors to avoid unintended side effects. Ensure that URL patterns do not unintentionally intercept internal services unless necessary. Avoid using overly broad patterns unless you have validated performance and behavior.