Rule set reference

Image Rendering supports a simple request pre-processing mechanism which is based on regular-expression match and substitution rules.

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

Request pre-processing rules can modify the path and query portions of requests before they are processed by the server’s request parser, including manipulating the path, adding commands, changing command values, and applying templates or macros. Rules can also be used to configure and override some catalog attributes, as well as for 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"?>
<!DOCTYPE ruleset SYSTEM" RuleSet.dtd">
<ruleset>
   <rule>
      <expression>
<varname>
  expression
</varname></expression>
      <substitution>
<varname>
  substitution
</varname></substitution>
      <addressfilter>
<varname>
  addressFilter
</varname></addressfilter>
   </rule>
</ruleset>

The <?xml>, <!DOCTYPE> 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.

Contents of preprocessing rule files are case-sensitive.

URL pre-processing

Before any other processing, an incoming HTTP request is partially parsed to determine which material 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> elements. OnMatch may be set to break (default), continue, or error.

Overriding catalog attributes

<rule> elements may optionally define attributes that override the corresponding catalog attributes when the rule is successfully matched and OnMatch="break" is set. No attributes are applied if OnMatch="continue" is set. Refer to the description of <rule> 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 material catalog with the catalog attribute attribute::RuleSetFile. While you can edit the rule set file at any time, the image server recognizes the changes only when the associated material catalog is reloaded. This happens when the Platform Server is started or restarted and whenever the primary catalog file (which has a .ini file suffix) is modified or ‘touched’ (to change the file date).

Examples

Ruleset examples are provided in the corresponding section of the Image Catalog Reference in the Image Serving documentation.

See also

package java.util.regex

Business.Adobe.com resources

Asset Collections Personalized Communications Document Generation Dynamic Media Customer Experience Management Headless Cms