Code First - Module

A NetKernel module is the fundamental unit of deployment. Like a regular Java JAR file it contains physical resources such as code, classes and static resources but it also declaratively specifies the logical URI address space that the module implements.

Physically a module exists either as a JAR file or as a directory. The directory form is handy for development. All elements of a module are easily available for editing and can be managed by a code repository system. The JAR form is valuable for distribution. NetKernel includes a Module Management Wizard which allows you to hot-install and remove modules in an operational system.

Physically at runtime a module uses its own custom classloader to bring its Java class files into memory. Other physical resource are requested with the ffcpl: URI scheme. ffcpl: is a little like file: only rather then obtaining resources from the host machines filesystem, it references resources in the NetKernel modular address space. Just like any other URI, ffcpl: URI requests are logically mapped to a physical accessor that provides access to the physical module resources. (This is why these components are called accessors.)

The logical structure of a module is defined by the metadata in the file module.xml which must be located in the root of the module. The major sections of module.xml are <identity>, <export>, <rewrite> and <mapping>. The mapping section defines the module's private internal logical address space. If the mapping section is empty then the private address space is empty. Each addition to the mapping section augments the address space. The following ura entries map two points in the address space to the two Java accessor classes used in the examples.

These entries define the mapping between the logical address space and the physical realm of Java code and objects. This is a critical point and bears repeating. Within a module a logical address is mapped to a physical code implementation of an accessor. This is exactly how web servers work - they are sent a logical resource address (such as www.1060research.com/) and they send a response with a physical representation of that resource (an HTML page in this case).

So then, how does the browser issued request in our example end up as a request for the resource ffcpl:/helloworld or ffcpl:/helloworld-java? We will look at this next.

In the module's rewrite section a rewrite rule

will match all requests for resources starting with ffcpl:/tutorial/... and rewrite them as ffcpl:/... essentially removing the /tutorial portion of the address. For example, the request ffcpl:/tutorial/helloworld will be rewritten as ffcpl:/helloworld

The module's export section contains:

The export section defines the portion of the address space exposed by a module for public use. This declaration tells NetKernel that the tutorial module exposes and will accept requests in the logical address space prefaced by ffcpl:/tutorial/ as well as the specific resource identified by ffcpl:/etc/HTTPBridgeConfig.xml.

Now we have part of the answer to our question about the browser's access to the example code. If the module is presented with a request for the resource ffcpl:/tutorial/helloworld it will accept the request, rewrite it as ffcpl:/helloworld and then locate the HelloWorld class to invoke its processRequest as the endpoint.

In the next section we will see how transports provide the connection between the browser and our module.