The delegate script mechanism enables the use of custom Ruby methods as "hooks" to provide dynamic information back to the image server. A truly customized image server can be created with minimal code.
Delegate methods are implemented in Ruby, and invoked by a JRuby interpreter bundled into the image server. There is no need to install an external Ruby environment and no need to know Java; just type some code into a file, and go.
The delegate script mechanism is disabled by default. To enable it, copy the sample delegate script, delegates.rb.sample, included in the distribution, to delegates.rb; reference it from the
delegate_script.pathname configuration option; and set
While the arguments and return types of each method will vary, all delegate methods must be contained within a
Cantaloupe module. Inside a method, anything goes, and you can use any (non-platform-native) gems that you have installed with
Because delegate methods will be called frequently, though, they should be written with efficiency in mind.
The delegate script will be reloaded on each request, so it can be edited without restarting. But, code that has been loaded into the JRuby runtime cannot be unloaded. For example, when a method is changed, it will overwrite the old version; but a constant cannot be redefined.
Here is an example of a script used by FilesystemResolver that performs a Solr query to return a pathname based on an identifier. The documentation in that section describes the contract that this method must abide by: its name, arguments, and return value.
Using the example above,
get_pathname() could be tested by adding the following line to the end of the script:
And running it on the command line with a command like:
ruby delegates.rb. The method output will appear in the console.
A catch, however, is that the
ruby command will normally invoke the standard ("MRI") Ruby interpreter, and not the JRuby interpreter. While they mostly work the same, one thing to be aware of is that gems with platform-native extensions will not work in JRuby. For that reason, you might want to install a standalone JRuby interpreter and test with that instead. (Something like RVM can make it easier to switch between different versions of the Ruby interpreter.)