HowTo Add Scripting to a NetKernel Web Site

This HowTo guide describes the addition of CGI-BIN type script support to a NetKernel web site.

Introduction

A previous HowTo Guide discussed the creation of a simple static web site with NetKernel. This guide will augment that description and add script support, similar to Apache CGI-BIN processing.

Scripting

NetKernel includes support for a variety of scripting languages including Python, BeanShell, Groovy, JavaScript, and dynamically-compiled Java.

While these languages are distributed as a part of NetKernel Standard Edition, they are not a core part of NetKernel, instead they are all services that are run within the NetKernel context. This is an important distinction for several reasons. First, it means that support for other languages can be added at any time (e.g. a custom, domain-specific language). Second, languages are activated with a call to an active: URI (we will examine details of this later). Third, all languages share the NetKernel resource model, exception handling framework, etc.

Running a Script

To run a script in NetKernel you actually run the language runtime and pass the script as a parameter. For example, to run a JavaScript program called index.js located at the root of the module, you would use this URI:

    active:javascript+operator@ffcpl:/index.js
 

This approach is not flexible as it binds a request to a specific script. A generalized approach uses rewrite rules in the module's module.xml file to map requests to various language runtimes based on the file extension. To map requests for files ending in ".js" to the JavaScript runtime, the following rewrite rule can be used:

    <rule>
      <match>(.*\.js)(.*)</match>
      <to>active:javascript+operator@$1$2</to>
    </rule>
 

This rule matches requests that end in ".js" and it captures parameters passed to the JavaScript program. These parameters are captured in the second matching rule and passed along in the "$2" reg-ex variable.

Adding Scripting Support

To add scripting support to a web site simply add a set of re-write rules and import the supporting libraries in the module.xml file. In this example we will add support for Python, Groovy, JavaScript, BeanShell, and DPML. The re-write rules are:

    <rule>
      <match>(.*\.idoc)(.*)</match>
      <to>active:dpml+operand@$1$2</to>
    </rule>
    <rule>
      <match>(.*\.bsh)(.*)</match>
      <to>active:beanshell+operator@$1$2</to>
    </rule>
    <rule>
      <match>(.*\.py)(.*)</match>
      <to>active:python+operator@$1$2</to>
    </rule>
    <rule>
      <match>(.*\.(groovy|gy))(.*)</match>
      <to>active:groovy+operator@$1$3</to>
    </rule>
    <rule>
      <match>(.*\.js)(.*)</match>
      <to>active:javascript+operator@$1$2</to>
    </rule>
 

The import statements required in the module's module.xml file are:

    <import>
      <uri>urn:org:ten60:netkernel:ext:script</uri>
    </import>
    <import>
      <uri>urn:org:ten60:netkernel:ext:dpml</uri>
    </import>
    <import>
      <uri>urn:org:ten60:netkernel:ext:sys</uri>
    </import>
    <import>
      <uri>urn:org:ten60:netkernel:ext:xml:core</uri>
    </import>
    <import>
      <uri>urn:org:ten60:netkernel:ext:xml:ura</uri>
    </import>
    <import>
      <uri>urn:org:ten60:netkernel:ext:kernel</uri>
    </import>
 

That is all that is required! Now, a request sent to the module ending in one of these file types will cause the associated language runtime to execute the script.

Calling Scripts

With support for scripting enabled for a web site, scripts may be called from a browser using standard URLs. For example, to call the script "time.js" on the demonstration web site use the following URL: http://demo.1060.org/demos/scriptdemo1/time.js. This will cause the time.js JavaScript program to be run.

While the details about each language and how to program a script is beyond the scope of this HowTo Guide, the following JavaScript code from time.js shows how to create an HTML template that uses a function call to get the current date and time. The "doc" variable is then passed as the response to the client with the MIME type text/html. (This example uses the E4X extension to JavaScript. A brief tutorial and article are available. Future HowTo guides will discuss this technology in more detail).

    //Import Java Libraries
    importPackage(Packages.org.ten60.netkernel.xml.representation);
    importPackage(Packages.java.lang);
    importPackage(Packages.java.util);
    importPackage(Packages.java.text);
    
    //Create Date and DateFormatter
    date=new Date( System.currentTimeMillis() );
    formatter=new SimpleDateFormat();
    
    //Create HTML literal
    doc=
    <html>
    <body>
    <h1>Time: { formatter.format(date) } GMT</h1>
    </body>
    </html>;
    
    //Create XmlObjectAspect and return as response
    xoa=new XmlObjectAspect(doc.getXmlObject() );
    resp=context.createResponseFrom(xoa);
    resp.setMimeType("text/html");    
 

The use of a file suffix to indicate treatment is similar to approaches using .asp or .aspx in .Net systems, .jsp in Java systems, and .php in PHP based systems. The disadvantage of this explicit mapping is that you are bound to a specific technology. A more flexible approach is to use RESTful addresses to activate services and map those internally. This approach will be described in another HowTo guide.

Demonstration

The following URLs call on scripts included in the download file.

Summary

NetKernel is a general purpose computing environment. This HowTo guide describes how to augment a NetKernel web site module to support CGI-BIN styled scripting.