Rule set reference rule-set-reference

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 section-8bcbd91ea8a946f28051bde8ad21827f

 <?xml version="1.0" encoding="UTF-8"?>

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 section-d8d101a0b4d74580835e37d128d05567

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 section-2c09a2d79ada46b994857c6a7fb4c13a

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 section-ed952fa55d99422db0ee68a2b9d395d3

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 section-3f1e33a65c5346d1b4a69958c61432f3

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 section-3f77bb9a265147b38c645f63ab1bad8b

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 section-066e659406d5403599cd26ae35e80d68

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 section-0598a608e4044bb4805fe93ceebe10a9

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.

Examples section-aa769437d967459299b83a4bf34fe924

Example A. Define a rule that increases the image quality settings if the image name has the suffix " _hg":


The rule expression specifies a case-insensitive match of " _hg" at the end of the URL string. The suffix is replaced with the specified query string which changes the image quality settings. Note that the ? character in the substitution string is escaped since this is a special character in regular expressions.

The required encoding for the ampersand character. Alternatively, the substitution string could be enclosed in a CDATA block:


Example B. A particular web application does not permit query strings. Define a rule which translates the trailing path element small, medium, or large to a template, using the remainder of the path as the image name. For example, myCat/myImage/small would translate to myCat/smallTemplate?src=myCat/myImage.

We can use substrings to restructure the request:


See also section-9b748e7c5cff4759a70f96657bd43352

package java.util.regex