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 nameFunction parametersDescription
filterRequestParamsFnMap params, HttpServletRequest reqReceives all HTTP request parameters. Can update the existing parameters map, or return a new one, before it's handled by Highlighter.
getDocumentProviderFnString uri, Map paramsFor received request parameters, returns implementation of com.jobjects.highlighter.IDependency interface that provides Highlighter with PDF file content (bytes).
uriFilterFnString uriUsed 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.
xmlUriFilterFnString uriAs above but used to filter "xml" parameter.
cachedDocumentProviderFnString idUsed by the /cached-document endpoint to return original PDF for document ID.
filterResponseObjectFnMapAmend highlighting response object before it's serialized to JSON.
ocrFnString documentUri, byte[] fileInvoked 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: