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