Developing with NetKernel Guide

This is a short guide to configuring your development environment to develop with NetKernel. Note this concentrates on setting up an IDE for Java development of new Accessors etc. If you are developing an XML application all you need to do is boot the Kernel and edit your XML files in the module of your choice all changes will be detected automatically - you can change the poll interval in "configure global parameters" option in the "control panel".

Configuring and Booting the Kernel

For development the Kernel can be booted with com.ten60.netkernel.container.Container.

System.xml

The Kernel reads it's configuration from the first occurrence of system.xml in the classpath. In the standard distribution this is <install>/etc/system.xml. To use the standard configuration the <install>/etc/ directory must be in your classpath.

Creating and Building a new module

You can use the new module wizard to create a preconfigured module with a stubbed out Accessor. The new module will be placed in a directory under <install>/modules/. The following steps will allow you to build your new module's classes...

Step-by-step checklist

This checklist assumes you have installed NetKernel to an install directory refered to as <install> and that you will start developing modules in <install>/modules/

1. Add <install>/etc/ to your project classpath
2. Add <install>/lib/1060NetKernel-2.*.*.jar to your project classpath
3. Add all module libraries <install>/modules/*.jar to your project classpath - many of these are not necessary but this is the fastest way to get started. They will do no harm in the classpath. As you gain experience you will learn which are the core modules that your application really requires.
4. Add <install>/modules/YOUR_MODULE_NAME/ to your classpath
5. If your module uses other jar libraries place these in a directory lib/ in your module. For development you must add these to your project classpath, at runtime they will be automatically picked up (see below).
6. Build your module's classes using your IDE
7. Boot the Kernel by executing com.ten60.netkernel.container.Container in the 1060NetKernel-2.*.*.jar

You can add any number of module directories to the modules/ directory. Each new module directory should be added to your IDE classpath. New classes in the module should be built against the kernel and the the libraries you added to your classpath. You must cold restart the Kernel for it to discover the new modules you create.

Runtime vs Development-Time

At development-time new classes are built against the IDE classpath - the settings described above will allow new Accessors to be built. However it is important to make clear that at runtime all modules are dynamically mounted and linked by the Kernel from the moduleDir directories defined in system.xml.

Therefore, if you create a module which, for example, uses org.ten60.netkernel.xml.xahelper.XAccessor from the ext_xml-core module, you must ensure the module.xml configuration of your new module imports org:ten60:netkernel:ext:xml:core. At runtime a module can only access libraries in it's own module lib/ directory or those imported from other modules which export public classses - this is a stronger and safer encapsulation than the standard java classpath model.

XML Libraries

With JDK1.4.x Sun made XML a core part of the JDK platform. Unfortunately they mixed Apache libraries into the system classpath. The core system classpath always overrides any application mounted classpaths. The upshot is that newer application mounted Apache libraries such as Xalan cannot be accessed without using the JVM endorsed mechanism. Furthermore Sun used the Crimson DOM as their default, which has now been deprecated in favour of the new Xerces DOM. Xerces will be the reference DOM used for JDK1.5 which will hopefully sort this mess out!

What this means for NetKernel and XML development.

1. At runtime NetKernel uses the latest Xalan and Xerces libraries obtained from <install>/lib/endorsed by using the -endorsed JVM flag. Therefore runtime DOMs generated in any Accessor are the Xerces DOM.
2. Unless you override the JRE, development will be done with the Crimson DOM! In most cases the org.wrc.* package is JAXP complient and should work OK. However to guarantee consistency between development time and runtime we recommend you override the standard JVM JAXP libraries. To do this place xalan.jar, xercesImpl.jar, xml-apis.jar, xmlParserAPIs.jar in the jre/lib/endorsed/ of your JDK, you may need to create the endorsed directory if it doesn't exist. Note: this is only necessary for development compatibility - NetKernel takes care of all this for runtime deployment.
3. Life will be easier when Sun get this sorted out on JDK1.5!

Debugging/Sources

If you've set up your development environment as described so far your classes should be OK for interactive debugging in your IDE. You may want to access the source code of any modules you've built against. All source code is provided in each of the compressed modules in the modules/ directory. You can either use the source from the Jar or unzip the module jar file into a new directory and mount it in your IDE classpath.

Tools

A number of tools are provided to trace and debug development issues with creating and linking modules. It is very useful to test that a module is configured such that a resource request in a given module is resolved in the correct location.

You should now be all set to develop your modules.

Advanced: Setting up the System by Hand

The NetKernel distribution comes ready configured but for serious development you need a clean slate. This is a rough guide to setting up a clean system.

System.xml

Create a new directory in your NetKernel <install> directory - for illustration lets call this <install>/expt/. You need to tell the kernel to look for modules in this directory. Edit the kernel configuration file <install>/etc/System.xml and add the following

Any modules you create or add to expt/ will now be automatically discovered by the kernel at boot/reboot.

NetKernel picks up it's configuration from the first occurrence of system.xml in the classpath. You must have a system.xml with location of your module directories in the classpath.

Basepath

The Kernel resolves all relative paths with respect to the basepath specified in the system.xml. So far we've assumed you are using the install directory as the basepath. You can set a new basepath by editing system.xml. Note that all moduleDir declarations are relative to this basepath.

Creating a Fulcrum

A Fulcrum is a top most module that imports the other modules that will make up the application. Generally a fulcrum also imports and starts a transport. For an example of a fulcrum look at <install>/modules/fulcrum/mod_fulcrum_frontend - you can examine the fulcrum's module.xml configuration.

For your clean slate you can develop a fulcrum basd on these examples. The Module Guide provides great detail about creating and importing modules.