Rule set reference

Last update: November 9, 2022

CREATED FOR:

  • Developer
  • User

Image Serving supports a simple request preprocessing mechanism which is based on regular-expression match and substitution rules.

Collections of pre-processing rules (rule sets) can be attached to image catalogs or the default catalog. Rules in the default catalog apply only if the request does not identify a specific main image catalog.

Request pre-processing rules can modify the path and query portions of requests before they are processed by the Platform Server’s parser, including manipulating the path, adding commands, changing command values, and applying templates or macros. Rules can also be used to configure and override certain security features which are normally controlled only with catalog attributes, such as request obfuscation, water-marking, as well as limiting service to specific client IP addresses.

Rule sets are stored as XML document files. The relative or absolute path of the rule set file must be specified in attribute::RuleSetFile.

General structure 

 <?xml version="1.0" encoding="UTF-8"?>
<ruleset>
   <rule>
      <expression>
<varname>
  expression
</varname></expression>
      <substitution>
<varname>
  substitution
</varname></substitution>
      <addressfilter>
<varname>
  addressFilter
</varname></addressfilter>
      <header>
<varname>
  headerValue
</varname></header>
   </rule>
</ruleset>

The <?xml> and <ruleset> elements are always required in a valid rule set XML file, even if no actual rules are defined.

One <ruleset> element containing any number of <rule> elements are permitted.

The contents of preprocessing rule files are case-sensitive.

Ruleset validation

A copy of RuleSet.xsd is provided in the catalog folder and should be used to validate a ruleset file before registering it in the catalog.ini file. Note that Image Serving uses an internal copy of RuleSet.xsd for validation.

URL pre-processing

Before any other processing, an incoming HTTP request is partially parsed to determine which image catalog should be applied. Once the catalog is identified, the rule set for the selected catalog (or the default catalog, if no specific catalog was identified) is applied.

The <rule> elements are searched in the order specified for a match with the contents of the <expression> element ( expression).

If a <rule> is matched, the optional substitution is applied and the modified request string is passed to the server’s request parser for normal processing.

If no successful match is made when the end of the <ruleset> is reached, the request is passed to the parser without modification.

The OnMatch attribute

The default behavior can be modified with the OnMatch attribute of the <rule> element. OnMatch may be set to break (default), continue, or error.

Element and Attribute
Behavior when a match occurs
<rule OnMatch="break">
Rule processing is terminated immediately after the substitution for this rule has been applied. Default.
<rule OnMatch="continue">
The substitution is applied and processing continues with the next rule.
<rule OnMatch="error">
Rule processing is terminated immediately and a "request refused" response status is returned to the client.

Overriding catalog attributes

The rule element can optionally define attributes that override the corresponding catalog attributes when the rule is successfully matched. If multiple matched rules set the same attribute, the last one prevails. See rule element for a list of attributes that can be controlled with rules.

Regular expressions

Simple string matching works for very basic applications, but regular expressions are required in most instances. While regular expressions are industry-standard, the specific implementation varies from instance to instance.

package java.util.regexdescribes the specific regular expression implementation used by Image Serving.

Captured substrings

To facilitate complex URL modifications, substrings may be captured in the expression by enclosing the substring with parentheses (…). Captured substrings are numbered sequentially starting with 1 according to the position of the leading parenthesis. The captured substrings may be inserted in the substitution using $ *n*, where n is the sequence number of the captured substring.

Managing rule set files

One rule set file can be attached to each image catalog with the catalog attribute attribute::RuleSetFile. While you can edit the rule set file any time, the image server recognizes the changes only when the associated image catalog is reloaded. This reloading happens when the platform server is started or restarted and whenever the primary catalog file, which has an .ini file suffix, is modified or “touched” to change the file date.