Custom JavaScript Stages for Query Pipelines

The JavaScript Query stage allows you to write a custom processing logic using JavaScript to manipulate search requests and responses. The first time that the pipeline is run, Fusion compiles the JavaScript program into Java bytecode using the JDK’s JavaScript engine.

The JavaScript Query stage allows you to run JavaScript functions over search requests and responses by manipulating variables called "request" and "response" which are Request and Response objects, respectively.

JavaScript Query Stage Global Variables

JavaScript is a lightweight scripting language. The JavaScript in a JavaScript stage is standard ECMAScript. What a JavaScript program can do depends on the container in which it runs. For a JavaScript Query stage, the container is a Fusion query pipeline. The following global pipeline variables are available:

Name Type Description

request

The Solr query information.

response

The Solr response information.

params

A reference to the container which holds a map over the pipeline properties. Used to update or modify this information for downstream pipeline stages.

ctx

A reference to the container which holds a map over the pipeline properties. Used to update or modify this information for downstream pipeline stages.

_context

Another reference to the same object as ctx, included because some stages use this name instead.

collection

String

The name of the Fusion collection being indexed or queried.

solrServer

The Solr server instance that manages the pipeline’s default Fusion collection. All indexing and query requests are done by calls to methods on this object. See SolrClient for details.

solrServerFactory

The SolrCluster server used for lookups by collection name which returns a Solr server instance for a that collection, e.g.
var productsSolr = solrServerFactory.getSolrServer("products");

Global variable logger

The global variable named logger writes messages to the logfile of the server running the pipeline. Since Fusion’s api service does the query pipeline processing, these log messages go into the logfile: fusion/3.1.x/var/log/api/api.log. There are 5 methods available, which each take either a single argument (the string message to log) or two arguments (the string message and an exception to log). The five methods are, "debug", "info", "warn", and "error".

JavaScript Query Stage Examples

Add a parameter to the query request

request.addParam("foo", "bar");

Add a parameter to the query response

This example contains a simple JavaScript function which adds information to the query response. Repeated calls to this function build out the response.

function add_to_response(key, list) {
  if (list.length > 0) {
      response.initialEntity.appendStringList(key, Java.to(list, Java.type('java.util.List')));
  }
}
add_to_response('banners', ctx.getProperty('banners'));
add_to_response('landing-pages', ctx.getProperty('redirects'));

Debugging and Troubleshooting

To debug a JavaScript Index stage you can:

  • Check the Fusion api server logs for errors.

  • Use the logger object for print debugging (in the Fusion api logfile).

  • Use the Pipeline Preview tool (only available in Fusion 1.x)

The JavaScript Engine Used by Fusion

The JavaScript engine used by Fusion is the Nashorn engine from Oracle. See The Nashorn Java API for details.

Upgrading to the latest Nashorn engine

The default version of the Nashorn engine used by Fusion versions 2.4.1 and earlier is the nashorn-0.1-jdk7.jar which contains many bugs that have since been fixed in the official JDK 1.8 version. In order to use the latest version of the Nashorn engine, you must:

  • Have an up-to-date version of Java 8 installed.

  • Remove the nashorn-0.1-jdk7.jar from the Fusion classpaths:

    • cd fusion/3.1.x

    • find . -name "nashorn-0.1-jdk7.jar" -print -exec rm -i {} \;

Creating and accessing Java types

The following information is taken from Oracle’s JavaScript programming guide section 3, Using Java From Scripts.

To create script objects that access and reference Java types from Javascript use the Java.type() function:

var ArrayList = Java.type("java.util.ArrayList");
var a = new ArrayList;