Scripting language filter

Overview

The Scripting Language filter uses the Java Specification Request (JSR) 223 to embed a scripting environment in the API Gateway core engine. This enables you to write custom JavaScript, Groovy, or Jython code to interact with the message as it is processed by the API Gateway. You can get, set, and evaluate specific message attributes with this filter.

Some typical uses of the Scripting Language filter include the following:

  • Check the value of a specific message attribute
  • Set the value of a message attribute
  • Remove a message attribute
  • DOM processing on the XML request or response

Write a custom script

To write a custom script, you must implement the invoke() method. This method takes a com.vordel.circuit.Message object as a parameter and returns a boolean result.

The API Gateway provides a Script Library that contains a number of prewritten invoke() methods to manipulate specific message attributes. For example, there are invoke() methods to check the value of the SOAPAction header, remove a specific message attribute, manipulate the message using the DOM, and assign a particular role to a user.

You can access the script examples provided in the Script library by clicking the Show script library button on the filter's main configuration window.

Note   When writing the JavaScript, Groovy, or Jython code, you should note the following:
  • You must implement the invoke() method. This method takes a com.vordel.circuit.Message object as a parameter, and returns a boolean.
  • You can obtain the value of a message attribute using the get() method of the Message object. However, do not perform attribute substitution as follows:
  • This is not thread safe and can cause performance issues.

Use local variables

The API Gateway is a multi-threaded environment, therefore, at any one time multiple threads can be executing code in a script. When writing JavaScript, Groovy, or Jython code, always declare variables locally using var. Otherwise, the variables are global, and global variables can be updated by multiple threads.

For example, always use the following approach:

Do not use the following approach:

Using the second example under load, you cannot guarantee which value is output because both variables (myString and i) are global.

Add your script JARs to the classpath

You must add your custom JavaScript, Groovy, or Jython JAR files to your API Gateway classpath and to the list of runtime dependencies in Policy Studio.

Add your script JARs to the API Gateway classpath

Because the scripting environment is embedded in the API Gateway engine, it has access to all Java classes on the API Gateway classpath, including all JRE classes.

If you wish to invoke a Java object, you must place its corresponding class file on the API Gateway classpath. The recommended way to add classes to the API Gateway classpath is to place them (or the JAR files that contain them) in the INSTALL_DIR/ext/lib folder. For more details, see the readme.txt in this folder.

Add your script JARs to Policy Studio

Your custom JavaScript, Groovy, or Jython script JARs must also be compiled and validated in Policy Studio. To add your JARs files to the list of runtime dependencies in Policy Studio, perform the following steps:

  1. In the Policy Studio main menu, select Window > Preferences > Runtime Dependencies.
  2. Click Add to select your script JAR file(s) and any other required third-party JARs.
  3. Click Apply when finished. Copies of these JAR files are added to the plugins directory in your Policy Studio installation.
  4. You must restart Policy Studio and the server for these changes to take effect. You should restart Policy Studio using the policystudio -clean command.

See also Policy Studio preferences.

Configure a script filter

You can write or edit the JavaScript, Groovy, or Jython code in the text area on the Script tab. A JavaScript function skeleton is displayed by default. Use this skeleton code as the basis for your JavaScript code. You can also load an existing JavaScript or Groovy script from the Script library by clicking the Show script library button.

On the Script library dialog, click any of the Configured scripts in the table to display the script in the text area on the right. You can edit a script directly in this text area. Make sure to click the Update button to store the updated script to the Script library.

Add a script to the library

To add a new script to the library, perform the following steps:

  1. Click the Add button, which displays the Script Details dialog.
  2. Enter a Name and a Description for the new script in the fields provided.
  3. By default, the Language field is set to JavaScript, but you can select from the following options:
    • Groovy: Groovy script
    • JavaScript: JavaScript based on Nashorn JavaScript engine (JRE8)
    • JavaScript (Rhino engine JRE7 and earlier): JavaScript based on Rhino JavaScript engine (JRE7 and earlier)
    • Jython: Jython script
  4. Write the script in the Script text area on the right. For example:

Script Library

Note   Regular expressions specified in Scripting Language filters use the regular expression engine of the relevant scripting language. For example, JavaScript-based filters use JavaScript regular expressions. This includes regular expressions inside XSDs defined by the W3C XML Schema standard.

Other API Gateway filters that use regular expressions are based on java.util.regex.Pattern, unless stated otherwise.

Further information

For more details on using scripts to extend API Gateway, see the API Gateway Developer Guide.

Related Links