Show Menu
TOPICS×

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

 <?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

<rule> elements 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. Refer to the description of the [<rule>](../../../../../is-api/image-catalog/image-serving-api-ref/c-image-catalog-reference/c-rule-set-reference/r-rule-rule.md#reference-af76c0e2b8be48dabb52b71fe7e51ee9) 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.regex] describes 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.

Examples

Example A. Define a rule that increases the image quality settings if the image name has the suffix " _hg":
<rule> 
   <expression>(?i)_hg$</expression> 
   <substitution>\?&amp;qlt=95,1&amp;resmode=bicub</substitution> 
</rule>

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:
<substitution><![CDATA[&qlt=95,1&resmode=bicub]]></substitution>
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:
<rule> 
   <expression>([^/]+)/(small|medium|large)$</expression> 
   <substitution>$2Template?src=sample/$1</substitution> 
</rule>