Content Pipeline

The response content pipeline is essentially a configurable sequence of transformations.  By default, it is empty.  When the BaseWeb content rule is used, and its onResponse method is called, it is populated with a number of transformations for URL mapping.  Adapter rules can customize the content pipeline by adding their own transforms.

TransformSequence

The transform sequence can be accessed in onResponse through the request context object:

var transforms = ctx.rootSequence;

Adapters can add transforms by calling addTransform:

transform = new PlainTextReplacement('foo', 'bar');
transforms.addTransform(new TransformNode(transform, 'example replacement'));

The supplied transform must be wrapped in a TransformNode object, which essentially gives the transform a name – this will be used later for rule debugging and tracing.

addTransformsToPipeline

The most common types of transforms are PlainTextReplacement, sometimes in combination with PlainTextRange, so a convenience method addTransformsToPipeline is supplied (by tomcat/webapps/ROOT/WEB-INF/classes/webrules/system/lib/ContentReplacementUtils.js).  This method accepts an array of transform definitions:

name

find

replace

caseSensitive

countStart

countStop

range

range.start

range.stop

range.caseSensitive

The equivalent of the example in the section above would be:

addTransformsToPipeline(ctx, [
    {
        name: 'example replacement',
        find: 'foo',
        replace: 'bar'
    }
]);

Injected Scripts

Sometimes it is necessary to inject JavaScript into an application to facilitate it operating correctly within the EdgeCore interface.  A few utility methods – defined in ContentReplacementUtils.js are made available to content rules to facilitate this.

Note: These can only currently be used in the non-SSO content rules because the URL mappings afterward will prepend the endpoint paths.

injectScript

injectScriptAtHead

injectEdgeWebUtils

injectEdgeWebUtilsAtHead

utils.js

Currently edgeWeb ships with one script – utils.js – that is intended to be injected into applications by adapter content rules.  It implements a single module called edgeWeb which exports two methods:

getTop

getFrameName

Transforms

The transforms described here are all Java objects.  Definitions are already imported and available to be used by adapter content rules (via ContentReplacementUtils.js), and can be created similar to this:

var transform = new TransformType( ... );

Replacement Transforms

StandardRegexTransform

Introduced in the 3.8.5 version

This transform searches for text matching the supplied regular expression and replaces it using a ‘normal’ regex replacement string.  Refer to the Matcher documentation for valid syntax.

matchExpr

replacementString

Create and add a StandardRegexTransform to the response content pipeline like this:

var transform1 = new StandardRegexTransform("foo", "bar");
ctx.rootSequence.addTransform(new TransformNode(transform1, "foo bar mapper"));
 
var transform2 = new StandardRegexTransform("(foo) (bar)", "$2 $1");
ctx.rootSequence.addTransform(new TransformNode(transform2, "foo bar reverser"));

JsRegexTransform

Introduced in the 3.8.5 version

This transform searches for text matching the supplied regular expression and replaces it using a supplied function that returns a string.

matchExpr

getReplacementStringFn

Create and add a JsRegexTransform to the response content pipeline like this:

var transform = new JsRegexTransform("(http(s){0,1})://([\w._-]+)(:(\d*)){0,1}",
    function(requestContext, matchResult) {
        return "";
    });
 
ctx.rootSequence.addTransform(new TransformNode(transform, "Naive absolute URL mapper"));

MatchResult

The result of a match operation.

This interface contains query methods used to determine the results of a match against a regular expression. The match boundaries, groups, and group boundaries can be seen but not modified through a MatchResult.

match.group() is whatever the whole regex match was, and match.group(0) is the same.
If there are capturing groups, match.group(1) is the first.

How to use it:

ctx.rootSequence.addTransform(new TransformNode(new JsRegexTransform(
    '(https?)://([^/]*)/', function(req, match) {
    logger.debug(match.group());
    logger.debug(match.group(0));
    logger.debug(match.group(1));
    logger.debug(match.group(2));

If the body of the response contained https://www.edgeti.com/ somewhere, the output would look like this:

match.group(): https://www.edgeti.com/

match.group(0): https://www.edgeti.com/

match.group(1): https

match.group(2): www.edgeti.com

BasicRegexTransform

This transform searches for text matching the supplied regular expression and replaces it using a supplied function that returns a replacement string.  Take care when using this transform, as it can produce unexpected results.  When the response content contains characters that will be interpreted by the Java Matcher#appendReplacement method, you may find that backslash characters (used for escaping) are removed, and dollar signs cause errors (which are quietly ignored, and the input content is passed out unmodified).  If necessary, consider using Matcher#quoteReplacementString.  In most cases, you should probably use JsRegexTransform or StandardRegexTransform, where the transformation logic is clearer.

matchExpr

getReplacementStringFn

The BasicRegexTransform can be added to the response content pipeline in the same way as JsRegexTransform.

PlainTextReplacement

This transform searches for a fixed string value in the input buffer, and delegates replacement to another transform.

matchText

countStart

countStop

caseSensitive

child

Create a PlainTextReplacement transform like this:

// replace every occurrence of 'foo' with 'bar'
var transform1 = new PlainTextReplacement('foo', new FullTextReplacement('bar'));
 
 
// just replace the 5th occurrence of 'foo' in the document with 'bar'
var transform2 = new PlainTextReplacement('foo', 5, 5, new FullTextReplacement('bar'));
 
 
// modify transform2 so that it ignores case
transform2.setCaseSensitive(false);

FullTextReplacement

This transform replaces the input buffer with a fixed string value.

replacementString

VariableSubstituter

Identical to FullTextReplacement, except that a function is used to provide the replacement text, rather than a string literal.

stringSupplier

RangeTransforms

PlainTextRange

startText

stopText

inclusive

inclusiveReplacement

caseSensitive

children

HtmlTagTransform

tagName

children

HtmlAttributeTransform

This is a very specific transform which is most effectively used as a child of an HtmlTagTransform.  It is used to identify the text range representing the value for the named attribute.  Any Transform can be supplied to perform the replacement in the context of that range.

attributeName

children