Module Development Guide

Module Development

The 1060 NetKernel accesses resources in packages called modules. Every aspect of the system from Caches and Transports to Application Libraries and High-Level Applications is provided by modules. Before reading this step-by-step guide to developing a module we recommend you read the module guide which provides a comprehensive discussion of a module's architecture and how they interact with the Kernel and each other.

Step by Step Guide

This guide shows how to create, register and configure a module by hand. Alternatively the new module wizard can also be used to create and automatically install a new module.

Step1 - Create a xar 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.

Register your Module

Starting with NetKernel 2.1.0 modules must be registered in the moduleDeployment.xml document. Add an entry to <install>/etc/deployedModules.xml.

Step2 - 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.

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

Step3 - 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.

Step4 - 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.

Step5 - 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.

Step6 - 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 up the call stack. See module guide for details.

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

Step7 - 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 salisbury 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.

Detecting development changes

Modules are auto-discovered but it is important to understand how changes and new resources are picked up.

• Module configuration files are only parsed at NetKernel during a restart. For development it is best to perform a cold restart.
• Changes to resources in a module are automatically detected. For development we recommend you set the defaultResourceExpiry to be 500ms - the ModuleManager will frequently verify that a module file has changed and use the most recent. For deployment this places an overhead on the system and the value should be set to a large value since deployed modules are generally not changed.

Jar Libraries

If your module uses jar libraries these can also be auto discovered by the Kernel. Jars are discovered in the /lib directory of your module. Changes to the Jar libraries will only be detected after a cold restart of NetKernel.

Transports and Cachelets

You may wish to configure your module to be the home for a transport. Transports are declared in the transports section of the module definition file. In general transports need only be added to a fulcrum module.

A module can declare that it requires a specific cache implementation. The cache for a module is declared in the cache section of the module definition.

The backend module definition gives an example of specifying both a transport and a cachelet.

Step8 - 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.

Deployment

A packaged module is installed by registering it in the module deployment file <install>/etc/deployedModules.xml.

The Kernel will interogate your module's module.xml configuration. It performs a dependency evaluation for other modules that the deployed module may depend upon. If dependencies are not satisified this will be indicated in the installed module tool.