Simple templated modules can be created and installed automatically using the new module wizard. Alternatively this document provides a step-by-step guide to hand building a module.

Step 1 - Create a module development directory

By default modules are located in the <install>/modules/ directory under your NetKernel installation path. Create a new folder in this directory which is unique and is related to the name of your module. This folder will be the base directory of your module and all its resources will be made available to the Kernel via the ffcpl: URI scheme.

For example suppose we are creating a module for sprocket processing - we might want to call this SprocketModule, we would therefore create a directory <install>/modules/SprocketModule/ . This directory is now the base path for all resources associated with this module.

Step 2 - Register your Module

Modules must be registered in the deployedModules.xml document. Add an entry to <install>/etc/deployedModules.xml .

Step3 - Create a Module Definition

A module is declared through a module definition resource. This is an XML file, module.xml, located in the root of the module. Many parts of the module definition file contain regular expressions or regexps, if you are unfamiliar with them please see the Regexp Cookbook .

In our example we should create a module definition <install>/modules/SprocketModule/module.xml . This should contain the following basic module specification.

Step4 - Create and Register an Internal Resource URI Address Space

A module has a private internal URI address space. To create an internal address space we need to create some resources and register their address space.

Suppose we now create a subdirectory com/sprocketsrus/myDir/ below the SprocketModule/ base. In this directory we place myDoc.xml.

Say we want all resources below com/sprocketsrus/myDir to be available in the internal address space. We do this by providing a this mapping entry in the mapping section of the module.xml module definition.

This makes myDoc.xml internally accessible with the URI ffcpl:/com/sprocketsrus/myDir/myDoc.xml.

Step5 - Export a public URI Address Space

In order to be used by other modules your module must export a public URI address space.

Suppose we want to expose a public interface ffcpl:/com/sprocketsrus/myDir/public/ , so that everything below public is externally accessible. We would do this with an entry in the export section of the module definition.

Step6 - Create external to internal URI Rewrite Rules

It is useful to be able to map external requests to internal requests using rewrite rules. These are declared in the rewrite section.

In our example let's suppose that a higher level module might issue a request for an idoc. Rather than serve the idoc as an xml document we want the request to execute the idoc in the DPML runtime. We need to rewrite the request so that it will result in a request to the DPML runtime accessor. This is accomplished with the following rule.

For details of how to define rewrite rules see the Regexp Cookbook.

Step7 - Import Other Modules and Reference Super

If your module requires resources from other modules they must be imported in the mapping section. Typically other modules may provide Java classes which your Accessors need, XML libraries, or application components. A module is imported by specifying an import declaration in the mapping section. The position in the list of mappings is significant and resources will be resolved in top down order.

In our example let's imagine that we are developing a URA that uses the ext_layer1 and ext_xml_ura modules. Let's also import the the ext_dpml DPML runtime module so that we can execute idocs. Our mapping section now looks like this:

You'll notice we've ended the mapping section with a reference to <super>. This is important if our module is to be used as a library by other modules since it allows resource resolution requests to be handed back to the caller of services in this module. See URI Address Space document for details of how requests are resolved.

Within this mapping element you can also register any accessors that are declared by this module. See the Accessor Development Guide for details.

Step8 - Develop away

The module definition is sufficient for you to proceed with developing whatever you wish to complete your module.

Create your idocs, classes and resources within your module. Items placed in the public sub-directory will be externally accessible. For example if you create an idoc with the relative path com/sprocketsrus/myDir/public/index.idoc you can execute this externally from another module using the URL ffcpl:/com/sprocketsrus/myDir/public/index.idoc. You might want to import your module into the front-end-fulcrum module which has the HTTP transport registered. You can then execute the idoc using your web browser at http://localhost:1060/com/sprocketsrus/myApp/public/index.idoc.

For more details of setting up you IDE for development see the Practicalities page.

Step9 - Package

Once you are happy with a module you can package it up into a .jar file for distribution. Use the jar tool supplied with the Java Development Kit or your favourite zip application.