Concise Guide

Introduction

This guide is a concise guide to NetKernel. It assumes the reader has a reasonable comprehension of the following standard technologies.

• URIs and the parts of a URI (scheme, path, fragment, query) including but not limited to URL's
• REST WWW infrastructure inc HTTP, Servlets and/or CGIs
• Regular Expressions (regex)
• XML - syntax and standard usage patterns (parsing, transformation, serialization)
• Java - at least minimal understanding of the Java classpath model and what a class is
• Basic Operating Systems - the concept of software which manages and executes other software. In particular what a scheduler does.

Things you don't need to know but which will eventually be useful.

• Java programming language
• Higher level XML technologies ( XSLT, XQuery...)

Exec Summary

NetKernel is a URI request scheduler. All resources are requested through Universal Resource Acccessors (a generalization of servlet/CGI). There are two types of URA - data accessor and active accessor. URAs can make requests for other resources provided by other URAs. A process is a managed series of URA requests.

NetKernel Scheduler

NetKernel is a micro-kernel for scheduling and issuing Universal Resource Identifier (URI) requests. All NetKernel processes are comprised of URI requests. URI Requests are resolved and issued to Universal Resource Accessors (URAs). URAs are services configured to receive and process URI requests. URA's are generally implemented as Java classes - URA's are a generalization of earlier URI endpoint service technologies such as CGI or Servlet.

URI requests to a URA may be of the following types

• Source - Requests a representation of a resource for a given URI
• Sink - Stores a representation of a resource to a given URI
• New - Creates a new resource for a given URI
• Delete - Deletes the resource of a given URI
• Exists - Tests if the resource exists for a given URI

These types are NetKernel/URA specific and, though analogous, are nothing to do with HTTP (Get/Post/Put etc).

A resource is anything at all. It could be an image file, an XML document, a PDF,... equally, since all processes are URI requests, a resource can be dynamically created as the result of process. However all resources are accessed through URAs.

Example: file: scheme

All requests for URI's with the file: scheme are handled by the File URA. eg file:///C:\path\to\my\file.txt or file:///home/user/my/file.txt. The File URA is a service for interacting with resources in the local filesystem. The File URA allows files to be retrieved, stored, created, deleted and tested for existence.

There are two broad categories of URA. Data Accessors handle an entire URI scheme. The File Accessor is a data acccessor. Active Accessors are software components addressed by URI. Most URAs are active accessors.

Modules and URAs

URAs are made available in modules. Generally technology specific URA's are grouped together in a single module - for example standard XML URA's are in the ext_xml-ura module.

A module publishes a public URI address space. Any URI request that matches this address space may be handled in the module. A module also has an internal URI address space, it may import another module's public address space into it's internal address space. In this way modules can be combined into applications. An in depth guide to the module architecture is available here.

A URA is bound to a module's internal URI address space by a regular expression mapping defined in the module's definition. In the example above the File URA is provided in the ext_layer1 module. A URI request matching the regex pattern file:.* is issued by the scheduler to the Java class org.ten60.netkernel.layer1.accessor.NewSimpleNetAccessor. The URI space which a URA can handle may be exported in the public address space of a module - this makes the URA accessible from outside.

Example: xslt URA

XSLTs are performed by the XSLT Accessor in the ext_xml-core module. The XSLT accessor is exported in the public address space as active:xslt\+.*. All requests for the URI "active:xslt..." will be issued to an instance of the class org.ten60.netkernel.xml.accessor.xslt.XSLTAccessor. XSLT's can be used in another module by importing the ext_xml-ura module.

Active URIs

The XSLT example above shows the active: URI scheme. Active URI is the scheme by which NetKernel usually issues requests for dynamically generated resources. An active URI is an IETF submitted standard for multi-part nested URIs. An active URI has the form

active:someidentifier+name1@URI1+name2@URI2...

It is a URI which may contain named sub-parts each of which is also a URI, active URI's can therefore be nested to any depth. NetKernel's active URI implementation ensures that all the URIs in an active URI are appropriately escaped.

Active URIs are used to create or process a resource. For example here is an active URI to apply the XSL Transform style.xsl to an xml document doc.xml

active:xslt+operator@style.xsl+operand@doc.xml

This example is pass-by-reference. It is also possible to use active URI's to pass by value. (see URRequest Javadoc).

URA requests

A URA is not just the end of a request chain. A URA can also issue requests to the scheduler for resources. A process on NetKernel is therefore a tree of interactions between multiple URA services.

Synchronous/Asynchronous URAs

URAs which issue requests can be written to be synchronous or asynchronous. The scheduler supports either model. If a synchronous request is issued the scheduler will ensure that the number of underlying Java threads is adequate to prevent deadlock. Accessors such as DPML are optimized to issue asynchronous requests. In general for custom URAs it is fine to develop synchronous accessors.

Thread Safety

URAs are assumed not to be threadsafe by default. The scheduler manages thread scheduling to an accessor and will not concurrently schedule requests to an accessor. URAs which are written to be threadsafe can be marked threadsafe, the scheduler may then issue concurrent requests.

Exceptions

Uncaught or runtime exceptions are handled by the scheduler. The scheduler will issue the request up the request call stack to any parent requestors. A URA may choose to handle received exceptions. An Accessor may also issue an Exception as the result of any request. The exception stack trace, including the requestor chain which caused an exception, is available in XML form.

High-Level Languages

All NetKernel processes consist of sequence of URI requests. It is possible to write an entire process in a URI though generally hand crafting active URIs is not appropriate. A high-level language on NetKernel is an active URI compiler and request initiator. For example the DPML-runtime simply builds active URIs and issues the requests. DPML manages application state in the form of variables. Often variables are placed as pass-by-value arguments to an active URI request.