Practicalities

XML Libraries

To ensure common behavior on all JVMs and to provide future flexibility, NetKernel takes full control of standard XML libraries. When NetKernel boots it uses the latest Xalan and Xerces libraries obtained from [install]/lib/endorsed by using the -endorsed JVM flag.

To guarantee consistency between your development environment and the NetKernel runtime environment you should override the standard JVM JAXP libraries. To do this place NetKernel's [install]/lib/endorsed versions of xalan.jar, xercesImpl.jar, xml-apis.jar, xmlParserAPIs.jar into the directory jre/lib/endorsed/ of your JDK (you may need to create the endorsed directory if it doesn't exist). These xml libraries will then take precedence over the default JVM supplied libraries. Note: this is only necessary for development compatibility - NetKernel takes care of this for runtime deployment.

Why is this necessary?

With JDK 1.4.x Sun made XML a core part of the JDK platform. Unfortunately they mixed Apache libraries into the system classpath and since the core system classpath overrides any application mounted classpaths then more recent, application mounted, Apache libraries such as Xalan cannot be accessed. Furthermore Sun used the Crimson DOM as their default, which has now been deprecated in favor of the Xerces DOM. Xerces is the reference DOM used for JDK 1.5 but there are still compatibility issues between the Java system libraries and other 3rd party tools and libraries.

Booting NetKernel

The quickest and easiest way to get started, no matter how you intend to finally deploy you application is to run NetKernel in Standalone Mode. This allows you to take advantage of all of the development tools included with NetKernel.

Advanced Customization

The NetKernel Standard Edition distribution comes ready configured but you may want to start with a clean slate. For detailed configuration information see the Kernel Configuration page.

Error Handling

NetKernel provides support for nested exception handling. Exceptions are rendered as XML documents with nested stack frames. Language runtimes such as DPML and XRL provide support for exception handling, many standard XML technologies provide no support for exceptions and will simply fail, throwing an exception out to the caller. Unhandled exception will propagate back to the initiating transport where they may be handled in a transport specific manner- the HTTP transport returns a 503 Internal Server Error response code and places the XML exception trace in the HTTP body.

More details of exceptions can be found in the Exceptions Guide.

Debugging Java with an IDE

Your IDE should be able to support interactive debugging of your NetKernel Java code. If you need to access NetKernel source code, configure your IDE to access the source in the [install]/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.

Configuration Troubleshooting

Symptom	Cause
On running the NetKernel Container I get a NetKernelException - "basepath not specified on command line or in system.xml".	The Kernel cannot find system.xml in the classpath - make sure you have placed the etc/ directory near the top of your runtime classpath.
I see a SAXException when viewing the index/control panel when executing NetKernel under the IDE	You have not endorsed the XML libraries - see section above.
I can't hot or cold restart NetKernel when running under the IDE.	This is because you've started the Kernel using the Container. If you need hot and cold restart for development start the Kernel using com.ten60.netkernel.bootload.BootLoader in the bootloader JAR located in the lib/ directory. Make sure the bootloader.cfg file is in the classpath and points to the NetKernel JAR. (see below about NetKernel in the classpath).
When starting NetKernel with the BootLoader I get a message "NetKernel classes found in class path".	The Bootloader dynamically loads the microkernel from the JAR file specified in bootloader.cfg. The microkernel JAR lib/NetKernel-2.x.x.jar must not be in your classpath at runtime - though it must be in the classpath for build time. A good IDE will allow you to set build and runtime preferences for your classpath.

For a list of other common Exceptions and their causes see here.