HowTo Expose the NetKernel Infrastructure in a Virtual Web Site

This HowTo describes how to develop a simple virtual web site that exposes the internals of a NetKernel module.

Introduction

NetKernel supports a computing abstraction founded on address spaces. Within NetKernel, each module has a private internal address space in which resources are identified by URIs. Similarly, a web site, such as www.1060.org/, represents an address space; it captures all URLs addresses starting with e.g. "www.1060.org/". For example, the resources "www.1060.org/index.html" and "www.1060.org/community/documentation/" are within the address space of the web site.

To create a web site with NetKernel we simply expose a NetKernel module's exported public address space to the HTTP transport and map it to an external address space starting with our website address (e.g. "www.1060.org/".)

Example Web Site

The example used in this HowTo is available for download. It is an implementation of a very simple web site that includes the single resource "index.html". The discussion will focus on exposing this module as the web site demo.1060.org/, however, with changes to the Apache mapping (discussed below), it can be mapped to any web site address.

Mappings

External

Two levels of mappings can be used for a web site implemented with NetKernel. In the first, a web site address space is captured and forwarded to NetKernel (typically running on port 8080 behind a firewall). In this example, Apache will be configured as a virtual host and will pass along all requests to NetKernel. This mapping:

    Internet
       |
       v
    Apache      (exposing port 80)
       |
       v
    NetKernel   (exposing port 8080)
 

Can be accomplished with the following entry in Apache's http.conf file:

<VirtualHost *:80>
  Servername demo.1060.org
  ServerAlias www.demo.1060.org
  ProxyPass / http://localhost:8080/demo/
</VirtualHost>

This is the same approach used for servers such as Jetty, JBoss, Tomcat, Resin, WebSphere, etc. It simply uses Apache as the entry point for client requests.

(Note: It is not necessary to expose NetKernel through a web server, in fact, NetKernel supports many types of transports, such as JMS. The use of other transports will be discussed in other HowTo guides.)

Internal

The second level of mapping occurs within NetKernel. In NetKernel, a web site can be contained in a single module. The web site module will export its public address space which is then imported into a fulcrum module. (A fulcrum is a module that includes a transport.) The fulcrum module then exposes its complete address space (which includes the mapping to the module's address space -- see below) on a transport making it available to the world outside of NetKernel. This is shown in the following diagram:

As you might expect, multiple web site modules can be imported by a fulcrum, each responsible for a different portion of the fulcrum's total address space. In the following diagram, Module A is mapped to the web site address sub-space starting with "/demo" while Module B is mapped to "/documentation" and Module C is mapped to "/forum").

The mapping of a module to an address sub-space occurs because of two things:

• A module exports a public address space (for example "/demo/.*") and
• The fulcrum module imports the web site module.

When a request for a resource is sent to the fulcrum module (by the HTTP transport), the fulcrum searches its list of imported modules until it find the first module that claims responsibility. Once a match to an imported module is made, the request is fully delegated to that module. Conceptually, an imported module will consume requests that fall into the address spaces it exports.

A module's structure is defined in the file module.xml located at the root of the module's physical layout. The following portion of a module.xml file declares that a module exports and claims responsibility for the "/demo" address space using regular expression pattern matching:

    <export>
      <uri>
        <match>.*:/demo/.*</match>
      </uri>
    </export>
 

Module Details

Next we examine how a module services requests sent to the "/demo" address space and contains a single resource, "index.html".

A module in NetKernel is the unit of physical code deployment and address space management. The module's address space is private and infinitely large. Within this space, all resources and services are addressed using URIs and the NetKernel REST requests (e.g. SOURCE, SINK, NEW, DELETE, EXISTS) specify the operation to perform. NetKernel does not use the http: scheme internally because the HTTP protocol is most appropriate for communication between computers. Instead, schemes such as ffcpl: are used. ffcpl: is suited to access files within a module. For example, the URI "ffcpl:/index.html" refers to the file "index.html" at the root of the module. A NetKernel SOURCE request to "ffcpl:/index.html" returns the contents of the file.

The similarities between the world of URLs, browsers, and the World Wide Web and NetKernel are not accidental. Because of these similarities, it is simple to set up a mapping between the external and internal address spaces. The mapping that we need is shown in this diagram:

    http://localhost:8080/demo/index.html  (outside of NetKernel)
      |
      |                                    (mapping by HTTPBridge)
      v
    ffcpl:/demo/index.html                 (external to module)
      |
      |                                    (mapping defined in module.xml)
      v
    ffcpl:/index.html                      (internal to module)      
 

The first mapping to note is from the HTTP protocol to the internal ffcpl: scheme. This (and many other tasks) is accomplished by the HTTPBridge service located in the fulcrum. The HTTPBridge accepts the first request address, translates it to an equivalent ffcpl: request and re-injects the request into the fulcrum. Because our web site module claims that it handles requests with the pattern "*./demo/.*", the request is next injected into our web site module. Within the module.xml file the following rule:

    <rule>
      <match>(.*)/demo/(.*)</match>
      <to>$1/$2</to>
    </rule>
 

Accomplishes the final mapping that removes the "/demo/" portion of the request.

When you download the example module you will discover the following directory structure and contents:

  /
    module.xml
    index.html
 

That is all that is required: a file with the meta-information (module.xml) and the web site contents. From this simple structure, adding content to a NetKernel web site proceeds just as with any other technology, add a /images directory, additional HTML files, etc.

Summary

Setting up a virtual web site with NetKernel requires some up-front configuration and address space mapping. Once that is accomplished, you can start to take advantage of the capabilities of NetKernel; these extensions will be described in other HowTo guides.