The url element in the @ 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.
A url element defines the target services using simple or advanced matching rules, giving you fine-grained control over which REST endpoints are intercepted.
How URL Pattern Matching Works
Filtering is performed against the REST path of the service, excluding:
- The context path (e.g.,
/arcgisor/).<web Adaptor Name > - Any query string or path parameters.
Each URL pattern must contain a valid service type, such as Map, Feature, Image, etc. You may define multiple URL patterns pointing to the same service type but targeting different resources.
General Rules
- You can define one or more patterns to target specific services or entire groups of services.
- Every pattern must include exactly one type of service.
- Pattern matching is case sensitive.
- If a pattern does not include a valid service type, the service interceptor project fails to build.
Valid service types
Valid service types for use in url include:
Map, Globe, GP, Geocode, Geo, Geometry,
Image, Feature, Search, Index, Indexing, Scene, Stream, WM, Big, Relational,
Vector, Knowledge, Workspace
If a URL pattern is missing a valid service type, you will see an error while building service interceptor project:
[ERROR] ... Error - urlPattern 'XXXXX' does not contain a valid service type. Valid service types are : MapServer, GlobeServer, GPServer, ...URL pattern examples
Match a specific service by name
@Interceptor(urlPatterns = {"/SampleWorldCities/MapServer"})Matches:
/arcgis/rest/services/Sample World Cities/ Map Server
Match a specific layer in a service
@Interceptor(urlPatterns = {"/SampleWorldCities/MapServer/0"})Matches:
/arcgis/rest/services/Sample World Cities/ Map Server/0
Does not match:
/arcgis/rest/services/Sample World Cities/ Map Server/1 /arcgis/rest/services/Sample World Cities/ Map Server
Match a specific operation for any service
@Interceptor(urlPatterns = {"/FeatureServer/0/query"})Matches:
/arcgis/rest/services/Incidents/ Feature Server/0/query /arcgis/rest/services/States/ Feature Server/0/query
Does not match:
/arcgis/rest/services/Sample World Cities/ Map Server/0/query /arcgis/rest/services/US A/ Map Server/0
Match by service type
@Interceptor(urlPatterns = {"/GPServer"})Matches:
/arcgis/rest/services/Utilities/ Geocoding Tools/ GP Server /arcgis/rest/services/Utilities/ Printing Tools/ GP Server /arcgis/rest/services/Utilities/ Raster Utilities/ GP Server
Multiple URL Patterns
@Interceptor(urlPatterns = {"/SampleWorldCities/MapServer", "/USA/MapServer",
"/PublishingTools/GPServer","/incidents/FeatureServer"})Matches:
/arcgis/rest/services/Sample World Cities/ Map Server /arcgis/rest/services/US A/ Map Server /arcgis/rest/services/Publishing Tools/ GP Server /arcgis/rest/services/incidents/Feature Server
Testing URL patten
ArcGIS Server provides an admin API called testURLPattern to test and verify which published services match a particular pattern. This is especially useful when validating advanced or broad patterns before deploying a Service Interceptor.
Best practices
- Prefer explicit service names when possible (e.g., /SampleWorldCities/MapServer).
- Avoid overly broad patterns (e.g., just /MapServer or /FeatureServer) unless you have validated performance and system impact.
- Keep URL patterns simple and predictable to avoid accidental interception of unintended services.
- Use multiple precise patterns instead of one broad pattern when targeting different service groups.