Skip to content

Latest commit

 

History

History
187 lines (133 loc) · 7.93 KB

QuickScriptFilter.md

File metadata and controls

187 lines (133 loc) · 7.93 KB

Quick Script Filters

The Quick Script Filter feature allow to package scripts as first order filters (i.e appears in pallette etc).

Required directory structure

A Quick script filter must be packaged in a single directory which must contain the following files:

  • script.js, script.py or script.groovy : only once of those file must be present
  • resources.properties : filter configuration and labels for user interface
  • typedoc.xml : entity store schema for this filter
  • ui.xml : user interface description file. See API Gateway Developer Guide for Declarative UI Reference

other files are ignored. An additional icon file may be supported in a future release.

Quick Filter Builder tool

A special tool with no API Gateway specific dependencies is used to produce files suitable for import in policy studio (typeset.xml and updated typedoc.xml). The tool must be invoked with the quick filter package directory. It will create a subdirectory named 'build' with typeset.xml and typedoc.xml. The typeset.xml file must be imported in the Policy Studio to make the filter available. Since the runtime of the policy studio does not change, no restart is required.

The QuickFilterBuilder tool will execute the following tasks. If any of the task fails, it exists in error and no build directory is produced.

  • Select script engine according to script suffix (js, py or groovy)
  • Check for presence of resources.properties and ui.xml files
  • Parse resources.properties and extract relevant filter configuration
  • Parse typedoc.xml file and check for reserved field or constant names
  • Produce an upgraded typedoc.xml with the previous extracted information and class constant
  • Produce the typeset for Policy Studio import

The tool is implemented using the Java class 'com.vordel.circuit.ext.filter.quick.QuickScriptFilterBuilder' which is available in the base runtime jar of the filter dev kit.

# Sample invocation of QuickFilterBuilder tool
java -cp ext/lib/filter-devkit-runtime.jar com.vordel.circuit.ext.filter.quick.QuickScriptFilterBuilder quickfilters/jython

Script file

Only one script file is allowed in the package. file extension is used to select Script Engine. Nashorn is used for .js files (Javascript), Jython is used for .py files (Python) and Groovy for .groovy files.

If multiple scripts are available the filter builder tool will exit in error.

resources.properties File

The resources.properties contains constants for filter configuration as well as labels used by the UI file.

The following constants are reserved and defines for filter configuration:

  • FILTER_DISPLAYNAME : Name displayed in the Filter palette and in the filter header, this property is mandatory
  • FILTER_DESCRIPTION : Description of the filter displayed in the filter header, this property is mandatory
  • FILTER_CATEGORY : Comma separated list of Palette categories in which the filter appears (defaults to 'Utility' if absent),
  • FILTER_ICON : Identifier of filter icon displayed in the Filter Palette (defaults to 'filter_small' if absent)
  • QUICKFILTER_REQUIRED : Comma separated list of attributes required by the filter
  • QUICKFILTER_CONSUMED : Comma separated list of attributes consumed by the filter
  • QUICKFILTER_GENERATED : Comma separated list of attributes generated by the filter

When choosing avoid properties names which starts by FILTER or QUICKFILTER ass additional configuration properties may be added in future releases (next step should be support of external icon file).

typedoc.xml file

The typedoc.xml file represent the filter schema in the API Gateway Entity Store. Any constant or field can be specified as long as constant and field names does not collapse with a reserved name.

The following fields are reserved and not available for customization. The filter builder tool will report an error if any of these are used:

  • successNode
  • failureNode
  • name
  • logMask
  • logMaskType
  • logFatal
  • logFailure
  • logSuccess
  • category
  • abortProcessingOnLogError
  • classloader
  • class
  • displayName
  • description
  • icon
  • palette
  • resources
  • ui
  • required
  • consumed
  • generated
  • engineName
  • script

ui.xml file

The UI file structure must be present. Its structure is defined in the API Gateway Developer Guide.

Scripting for Filters

All script languages of the API Gateway are supported. However, the Filter Builder tool only package javascripts with the nashorn engine.

Each language has now 3 functions to implement:

  • attach(ctx, entity) : This function is called by API Gateway during deployment with the current configuration context and the entity declaration.
  • invoke(circuit, message) : This function receive the current policy and message objects. It must return a boolean to indicate success or failure of the filter, and it can throw CircuitAbortException objects.
  • detach() : This function is called when the API Gateway configuration is undeployed.

Typical use of the attach() call is to lookup for API Gateway reference objects (Policies, Caches), but it can also allocate resources. All allocated resources must be released by the detach() call. The attach call may throw EntityStoreException object.

To keep a high level of performance, all tasks wich can be prepared must be implemented in the attach() call.

The invoke() call is call each time a message is handled by the API Gateway. Be aware that the filter can be called in any policy from any listener. This means that the message attributes may differ from one listener to another.

Javascript prototype (nashorn)

The script below contains function declarations for Javascript using the Nashorn engine. It implements simple trace and is equivalent to a 'True' filter.

var Trace = Java.type('com.vordel.trace.Trace');

function attach(ctx, entity) {
	Trace.info("Javascript True Filter attached");
}

function invoke(circuit, msg) {
	Trace.info("Javascript True Filter called");

	return true;
}

function detach() {
	Trace.info("Javascript True Filter detached");
}

Python prototype (Jython)

The script below contains function declarations for Python using the Jython engine. It implements simple trace and is equivalent to a 'True' filter.

from com.vordel.trace import Trace

def attach(ctx, entity):
    Trace.info("Jython True Filter attached")

def invoke(circuit, msg):
    Trace.info("Jython True Filter called")
    return True

def detach():
    Trace.info("Jython True Filter detached")

Groovy prototype

The script below contains function declarations for Groovy. It implements simple trace and is equivalent to a 'True' filter.

import com.vordel.circuit.CircuitAbortException
import com.vordel.circuit.Message
import com.vordel.config.Circuit
import com.vordel.config.ConfigContext
import com.vordel.es.Entity
import com.vordel.es.EntityStoreException
import com.vordel.trace.Trace

void attach(ConfigContext ctx, Entity entity) throws EntityStoreException {
	Trace.info("Groovy True Filter attached");
}

boolean invoke(Circuit c, Message m) throws CircuitAbortException {
	Trace.info("Groovy True Filter called");
	return true;
}

void detach() {
	Trace.info("Groovy True Filter detached");
}

Limitations

Attributes handling in Policy Studio

Quick Script Filters are not able to dynamically change required/consumed and generated attributes. Only fixed attribute names declaration is allowed. Reporting required, consumed or generated attributes from underlying policy references is not supported

User interface

The following Tags are not useable when defining ui.xml files because they need additional class support in the Policy Studio:

  • ComboAttribute
  • TablePage
  • validator

The following Tags may be useable when defining ui.xml files if they do not need additional class support in the Policy Studio:

  • binding : supported if the class attribute references a class which already exists in Policy Studio
  • comboBinding : supported if the class attribute references a class which already exists in Policy Studio