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 = [
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.


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



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.


String uri,
Map params

For received request parameters, returns implementation of com.jobjects.highlighter.IDependency interface that provides Highlighter with PDF file content (bytes).


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.


String uri

As above but used to filter "xml" parameter.


String id

Used by the /cached-document endpoint to return original PDF for document ID.



Amend highlighting response object before it's serialized to JSON.


String documentUri, byte[] file

Invoked if it's detected that document needs OCR

To link your function to PDF 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:

comments powered by Disqus