Scripting

Some functionalities of PDF Highlighter can be extended using scripting.

Loading Scripts#

To enable scripting, add the script loading block to your application.conf:

highlighter.service.scripting {
  files = [
    "/path/to/script/file1.groovy"
    "/path/to/script/file2.groovy"
  ]
  engine = "groovy"
}

You can load one or more script files. Default scripting language supported by PDF Highlighter is Groovy, but other scripting languages that support javax.script package should work as well.

Dependencies#

If your script has any Java library dependencies, create lib directory below the script's location and put needed jar files to it.

Script Lifecycle#

Function init(), if defined, will be invoked when the script file is loaded.
Script objects saved in its global scope will be persisted between function calls.
Function destroy(), if defined, will be invoked when the script file is unloaded.

When the script is updated, PDF Highlighter will detect the change, reload, and recompile the script.

Global scope objects:

scriptPath - path used to load the script
log - an instance of org.slf4j.Logger

Log messages from the scripts and Highlighter's scripting module can be found in highlighter.log marked with highlighter.scripting.

Extension Points#

Extension points are listed in order they're invoked during highlight request handling.

Config hook name	Function parameters	Description
`filterRequestParamsFn`	Map params, HttpServletRequest req	Receives all HTTP request parameters. Can update the existing parameters map, or return a new one, before it's handled by Highlighter.
`getDocumentProviderFn`	String uri, Map params	For received request parameters, returns implementation of com.jobjects.highlighter.IDependency interface that provides Highlighter with PDF file content (bytes).
`uriFilterFn`	String uri	Used by highlighting methods to convert received document "uri" parameter to file path. Expected to return either Java File or a String with path to PDF. If a String was returned, any uriMappings rules will be applied as well.
`xmlUriFilterFn`	String uri	As above but used to filter "xml" parameter.
`cachedDocumentProviderFn`	String id	Used by the `/cached-document` endpoint to return original PDF for document ID.
`filterResponseObjectFn`	Map	Amend highlighting response object before it's serialized to JSON.
`ocrFn`	String documentUri, byte[] file	Invoked if it's detected that document needs OCR
`convertDocumentFn`	File outputDir, IDependency dep	Invoked to convert the file if the input file is not PDF or HTML

To link your function to JObjects Highlighter, add the hook name to highlighter.service.scripting config section where the value is the name of your script function.

For example, if the script function is defined as:

def uriToFile(uri) {
  ...
}

Then, to link it in config use:

highlighter.service.scripting {
  uriFilterFn = "uriToFile"
}

Script Examples: