Internal Module Patterns
The entries in the module definition file allow a developer to
describe the exported address space, the internal private
address space, and the mapping between the two (in
the rewrite section).
Architectural and design artifacts can be created using
patterns described in this section.
Simple
Exports everything.
Discussion
No architectural or design artifacts are created with this pattern.
The whole of the internal private address space is exposed
through the exported address space.
This approach is fine for quick development experimentation.
It is
not
recommended for production systems.
Implementation
The simple pattern exports everything in the internal
private address space to the public interface of the module.
Export
<export>
<uri>
<match>.*</match>
</uri>
</export>
Rewrite
Hand-craft the address space interface.
Discussion
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.
Implementation
This pattern uses an regular expression rewrite rule to
match a request on a publicly exported interface to an internal request in the
internal module address space.
Export
<export>
<uri>
<match>ffcpl:/some/path/to/myservice/</match>
</uri>
</export>
Rewrite
<rewrite>
<rule>
<match>ffcpl:/some/path/to/myservice/(.*)</match>
<to>active:dpml+operand@ffcpl:/internal/process.idoc$1</to>
</rule>
</rewrite>
Mapper
Delegate the address space interface management to an accessor.
Discussion
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.
Implementation
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 ht external URI to an internal URI.
Export
<export>
<uri>
<match>ffcpl:/some/path/.*</match>
</uri>
</export>
Rewrite
<rewrite>
<rule>
<match>ffcpl:/some/path/(.*)</match>
<to>active:mapper+operator@ffcpl:/internal/links.xml+operand$1</to>
</rule>
</rewrite>
Mapping
<mapping>
<import>urn:org:ten60:netkernel:ext:xrl</import>
<this>
<match>ffcpl:/internal/links.xml</match>
</this>
</mapping>
Layering
Layer services over the address space.
Discussion
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 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.
Implementation
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 accessors which performs a service
on every request before issuing the request to the next accessor.
Export
<export>
<uri>
<match>ffcpl:/some/path/.*</match>
</uri>
</export>
Rewrite
<rewrite>
<rule>
<match>(.*)</match>
<to>active:sessionmapper:$1</to>
</rule>
<rule>
<match>(.*)</match>
<to>active:mapper+operator@ffcpl:/internal/links.xml+operand$1</to>
</rule>
</rewrite>
Mapping
<mapping>
<import>urn:org:ten60:netkernel:ext:xrl</import>
<import>urn:org:ten60:netkernel:ext:session</import>
<this>
<match>ffcpl:/internal/links.xml</match>
</this>
</mapping>
Extension Match
Use a file extension (or path) to execute a category of processes.
Discussion
This pattern is implemented for modules created with the new module
wizard - it is convenient since it allows al 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 servers
(e.g. .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.
Implementation
A rule which matches a file extension is used to filter all requests for a class
of executable processes to the executable runtimes.
Export
<export>
<uri>
<match>ffcpl:/some/path/.*</match>
</uri>
</export>
Rewrite
<rewrite>
<rule>
<match>(.*\.idoc.*)</match>
<to>active:dpml+operand@$1</to>
</rule>
</rewrite>
Path-to-Argument
Use service path as internal service argument.
Discussion
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.
Implementation
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.
Export
<export>
<uri>
<match>ffcpl:/some/path/.*</match>
</uri>
</export>
Rewrite
<rewrite>
<rule>
<match>ffcpl:/some/path/(.*?)/(.*)</match>
<to>active:dpml+operand@ffcpl:/internal/process.idoc+subpath@temp:$1$2</to>
</rule>
</rewrite>
Transport-Bridge
Bridge from raw transport to application friendly requests.
Discussion
The example shows a rewrite rule in the mapping
section of a module definition.
A transport initiated request arrives in a fulcrum's
internal address space therefor the transport-bridge
pattern rewrites all internal requests to map to the bridge.
Implementation
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 frontend and backend fulcrums to
pre-process the raw HTTP streams from the HTTP transport using the HTTPBridge
accessor.
Mapping
<mapping>
<rewrite>
<match>(.*)</match>
<to>http-bridge:$1</to>
</rewrite>
</mapping>