Exception HandlingException Handling
Exception handling in a multi-language application
Home > Books > Solutions Developer Guide > Exception Handling

Rate this page:
Really useful
Satisfactory
Not helpful
Confusing
Incorrect
Unsure
Extra comments:


NetKernel Exception Handling

Thrown exceptions are treated uniformly as representations. Because all resource requests are handled by the microkernel if an exception is thrown within any code and not handled in that code's frame the exception is sent back to the microkernel. Some exceptions are handled directly by the microkernel such as the Java exceptions ThreadDeath and OutOfMemoryError. Other exceptions are rethrown into the context of the requestor and if not handled there, propagated up the context stack until it reaches the transport issuing the initial root request.

Because any service in NetKernel can be written in any supported language, NetKernel's exception handling system effectively propagates exceptions across programming languages. For example, an exception thrown in a Ruby service can be caught and handled in a JavaScript service. With appropriate support in a transport, NetKernel can throw and catch exceptions in a distributed environment.

NetKernel exceptions have the physical representation NetKernelException which can be serialized as an XML resource for processing by DPML and the XML resource model tools. Within a DPML script it can be caught in an <exception> block. Other languages would use their native exception handling to catch NetKernelException.

If an exception propagates up to a transport it will handle the exception in an appropriate manner. For example the HTTP transport will return a 500 code response along with an XSLT formatted rendering of the exception information.

Understanding an Exception 'Stack Trace'

A NetKernel exception captures detailed information about the complete request hierarchy that has resulted in an error. The original request is found at the top of the request exception stack. The deepest request is always last and is the point at which the exception was issued.

Since NetKernel is logically linked, each request in a hierarchy will usually be executed by a different thread. Each frame of the exception represents a different request and each shows the Java stacktrace showing where that request's thread was when the exception occurred. Keep in mind that the lowest level request is the actual point where the request was thrown - usually this is the only frame of the exception that you need to look at the Java stacktrace.

Each exception frame also has an ID field which is used to provide a means of classifying application exceptions - some standard NetKernel exception IDs are shown below.

Each frame provides the URI of the resource being requested, the verb for the URI operation and the Java Aspect class that was specified. This information is present for each request frame and allows you track the request hierarchy down from the originating transport (at the top of the request stack) down to the lowest level, and problem causing, request (at the bottom).

Detailed Example

Here is an example of a typical exception stack trace: http://localhost:8080/workbench/example_exception/broken-script.bsh

This runs a beanshell script that deliberately throws an exception. If you click "Exception Trace" in the line "A detailed Exception Trace is available, please report this to the system administrator or use it to identify the source of the problem.", the complete Exception request stack trace will be displayed.

Starting at the deepest frame we can see its Id: "Example Stacktrace" and a descriptive message "This is an example of an exception thrown from a script". And below that is the JavaStack trace of the active thread which encountered the exception. In this case it is showing we are inside the Beanshell Runtime engine.

Stepping up to the next frame we see that we get a report that there is an "Unhandled Exception in BeanShellEngine" and we see that it was evaluating a script at line 10.

Stepping up we see the request was for active:beanshell+operator@ffcpl:/workbench/example_exception/broken-script.sh - this tells us that the request is executing the beanshell broken-script.bsh and the Java accessor class that was being called is the ScriptEngineNKFAccessor.

Stepping up to the top frame we see that the originating request was from the Jetty HTTP transport.

Distributed Exception Handling

NetKernel is able to handle exceptions in a distributed environment. For example, the HTTP transport and the HTTP client tools in NetKernel are capable of sending an exception across an HTTP request and re-issuing the exception in the client code. For a detailed discussion refer to the section on HTTP Transport Exception Handling.

NetKernel Exceptions

Exception ID Description
URI Resolution Failure A request was made by a module which could not be resolved within its private address space. A request resolution trace is added to the exception to aid tracking down the problem.
No Transreptor Found A request was made for a resource of a specific data-type (aspect). The resource was successfully accessed but the result could not be transrepted to the desired type because no transreptor could be located within the current module or its imports.
Unrecognized Fragment Identifier A request was made for resource referenced by a URI with a fragment identifier. No Fragmentor could be found to apply the fragment identifier because the combination of fragment identifier structure and the MIMEtype of the resource could not be matched to a registered Fragmentor.
Deadlock detected A request has been dispatched but no activity has occurred for at least the deadlock period specified in the System Configuration. The request has been interrupted.
Attempt to use IAspectVoid A service has returned a void response. This exception is thrown because a void response cannot be converted into any other type.
Exception during request processing An exception occurred whilst processing this request. A sub-exception will always occur inside.
Error sourcing resource A resource SOURCE request resolved to an ffcpl: resource however no underlying resource could be found or because of a filesystem access error.
Error sinking resource A resource SINK request resolved to an ffcpl: resource but failed because of a filesystem access error.
External sink denied A resource SINK or DELETE request resolved to an ffcpl: module resource but failed because it was initiated outside the owning module.
Unsupported Request Type A request type outside the supported types was issued on the kernel.
Null result returned An accessor returned Java null.
Service Unavailable An external request was rejected due to throttle overload.

NetKernel Exception Document

An exception document consists of a root <ex> element with the following elements:

Element Description
id An identifier for the exception type- analogous to a Java exception class name.
message A specific message, if necessary describing the error.
timestamp The timestamp that the exception was thrown
originator The originating kernel component, accessor, transreptor, etc
stack If relevant a Java stack trace is captured to a depth defined in the System Configuration . Each level in the stack trace is inside a sub <level> element.
requestid The request which was being executed when the exception occurred.
ex One or more nested causes.
© 2003-2007, 1060 Research Limited. 1060 registered trademark, NetKernel trademark of 1060 Research Limited.