Internal Structure

This page explores several options for module organization.

• Simple internal=external
• Rewrite external is rewritten to internal
• Mapper using XRL to provide dynamic mapping
• Layering passing inbound request through layered services
• Extension Match map all requests with a particular file extension to a service
• Path-to-argument put the path of a request into the argument on a service
• Transport Bridge map a request via a transport bridge

Export everything.

The simple pattern exports everything in the internal address space to the public interface of the module.

This simple mapping of the internal private address space to the module's exported public address space is very easy to set up. While suitable for simple modules in the early stages of development, it is not recommended for mature nor production modules because it by-passes an important level of encapsulation and sacrifices future flexibility.

hand-craft the address space interface

This pattern uses a regular expression rewrite rule to match a request on a publicly exported interface to an internal request in the internal module address space.

This example rewrites a specific path to a URI request to execute a DPML process. Any arguments on the active URI are captured and placed on the internal rewritten URI.

You can use the regular expression cooker to develop rewrite rules.

delegate the address space interface management to an Accessor

This pattern uses a regular expression rewrite rule to match all requests on a publicly exported interface to a delegated Accessor which is responsible for mapping the external URI to an internal URI.

The mapper pattern hands the URI request to an Accessor which interprets and then reissues a new request against the internal address space. It is relatively simple to implement a custom Accessor to implement this pattern. Alternatively you can use the XRL mapper accessor which implements the URI mappings defined in a links document. The mapper pattern of module definition is useful for service libraries since by delegating to an Accessor the public interface definition is dynamically defined.

layer services over the address space

A variation of the mapper pattern, this pattern uses a series of regular expression rewrite rules to match all requests on a publicly exported interface to a series of Accessor which performs a service on every requests before issuing the request to the next Accessor.

This example shows how the session Accessor can be layered over the XRL mapper. All requests are mapped to the session: Accessor and then all session: requests are mapped to the to the XRL mapper.

The layering pattern shows how NetKernel's active URI is a functional programming model. We can think of layered services as nested function evaluations. So, if f(x) is the session:.* rule and g(y) is the active:mapper rule then the combined operation performed on every request is g(f(x))

Technologies which use the layering pattern include session and URIGateKeeper

use a file extension (or path) to execute a category of processes

A rule which matches a file extension is used to filter all requests for a class of executable process to the executable runtime.

This pattern is implemented for modules created with the new module wizard - it is convenient since it allows all requests for a given filetype to initiate the execution of the process expressed in the file.

The file extension pattern is the conventional approach used by many web-serers (eg .php, .asp, .jsp). In NetKernel it is a little old fashioned since it ties the public interface of the module to the technology implementation of the service - NetKernel allows these to be completely decoupled and maintainable.

A variation of the extension match pattern is to map a path to an executable - for example mapping /cgi-bin/ to a runtime process.

use service path as internal service argument

A purist REST approach to a URI interface is to use the path of the service as part of the dynamic data for generating the result. This pattern extracts parts of the path and uses these parts as arguments on an active URI for a process execution.

This pattern extracts the first sub-path below /some/path and appends it, using the temp: URI scheme, as a named (here called 'subpath') URI argument to the DPML process.

The DPML process can use the toURI accessor to retrieve the subpath argument.

bridge from raw transport to application friendly requests

A special variation of the mapper/layering pattern, this pattern passes all raw requests from a transport through a bridge Accessor for pre-processing to an internally friendly form. This pattern is used by both the front-end and back-end fulcrums to pre-process the raw HTTP streams from the HTTP transport using the HTTPBridge accessor.

The example shows a rewrite rule in the mapping section of a module defintion. A Transport initiated request arrives in a fulrum's internal address space therefore the transport-bridge pattern rewrites all internal requests to map to the bridge.