req=context.createSubRequest("active:ruby");
req.addArgument("operator", [resource representation, aspect, or URI] );
result=context.issueSubRequest(req);

The ruby accessor executes Ruby language scripts. It is based on JRuby 1.0.1.

The operator specifies a resource to be executed as a program. This may contain zero or more classes plus some script code outside the context of any class which will be executed when the script is invoked. The script may either be a plain/text or an XML document with the script specified as the text of the root element. This later form is useful when embedding ruby snippets inside declarative languages.

When using XML it is strongly advisable to enclose your script inside a CDATA section, for example:

<script><![CDATA[ ...your script .. ]]></script>

Script Context

When executed, each script is provided an instance of the INKFConvenienceHelper class as the local variable context. The context variable has two purposes. It supports introspection of the request which initiated the script and it allows sub-requests to be issued. For more details see the NKF Reference Guide.

Once a response object is created:

response=context.createResponseFrom(...);

it will be returned via the context when the script exits.

Parameters

Parameters can be passed to a script using named arguments. Argument values are available within the script through the context using the this:param URI address space convention.

For example if the ruby accessor is requested with...

active:[email protected][email protected]

The myargument parameter can be obtained inside the script using the context and the argument URI "this:param:myargument".

$context.source("this:param:myargument")

Ruby Libraries

Many useful libraries for ruby are available and it can also be useful to structure your own code up into multiple modules. The ruby accessor allows you to import Ruby modules into your ruby scripts. Traditionally ruby has been oriented around the filesystem and all imports were resolved against the fileystem either absolutely or relatively. Because NetKernel has a modular address space abstraction this accessor resolves imports not from the filesystem but from NetKernel modules. The principles are the same, modules are resolved either absolutely or against the current working URI of the "main" script. Module import specificiations using require or load become URIs which are resolved against the address space of the script execution request.

For example, the import statement:

require 'area'

would import the Ruby script 'area.rb' from the same directory as the currently running script. But also a fully qualified URI can be used such as require 'ffcpl:/scripts/myModule.rb' which is then resolved through the URI address space.

Java Libraries

JRuby has the ability to access native Java classes. Java classes are often needed when constructing requests and issuing results in NKF.

Java classes can be imported with the following ruby syntax:

include_class "java.util.Random"
	

Alternatively a Java package can be imported into a Ruby module and used by refering to the module eg.

module JavaIncludes
  include_package "java.util"
end

r=JavaIncludes::Random.new
	

Exception Handling

The ruby accessor maps Ruby exceptions into the NetKernel domain so they integrate well into the composite stack trace that NetKernel presents.

Example

Here's an example of a Ruby script for performing an XSLT, logging the result and returning the result as the response.

# Create and issue XSLT request
sr=$context.createSubRequest("active:xslt)
sr.addArgument("operand","data1.xml")
sr.addArgument("operator","style1.xsl")
rep=$context.issueSubRequest(sr)

# Log result
sr=$context.createSubRequest()
sr.setURI("active:log")
sr.addArgument("operand",rep)
$context.issueSubRequest(sr)

# Create response, set metadata and exit
resp=$context.createResponseFrom(rep)
resp.setMimeType("text/plain")
resp.setExpired()