Page: Handling Module Exceptions
Page: Handling Errors in a Route
Page: Getting Binary Data with the SQL Module
Page: HTTP Module
Page: Convert Module
Page: Working With the Request
Page: Getting HTTP Query String Parameters
Page: Getting Request Path Parameters
Page: Getting HTTP Headers
Page: Getting the Module Directive
Page: Getting Route Parameters
Handling Module Exceptions
This section describes the following topics:
The information in this section assumes that Developer Mode on the Akula Server is enabled. When disabled, error messages are minimized. For more information, see Enabling and disabling Developer Mode.
You can throw an exception in a custom module just as you would any Java class. The result is that the module stops processing, and the exception is converted to a JSON error object and returned to the client. No other modules in the route are called after a module throws an exception.
The following example shows a module that throws an IOException:
In this example, the client receives the following JSON object:
The Akula Server adds a transaction ID, error code, error description, and an information object to the JSON output by default. This output is sent directly to the client as a response. In addition to these properties, the Akula Server can also include the stack trace, if there is one.
The following table describes the properties that can be part of the JSON error response:
|Property||Description||Developer Mode required?|
A unique ID that Akula assigns to each request. Akula includes the transaction ID in all AKExceptions, and by default writes them to the log files when an exception is thrown.
This property can be useful for sorting and searching log files where multiple clients might be encountering similar issues.
|The error code that Akula assigned to the exception. For example, "IN_ROUTE_EXCEPTION". For a complete list of error codes, see Handling Exceptions and Errors.||No|
|A brief description of the error code.||No|
A child object that contains properties about the original request from the client. Not all error responses include the information object.
The information object is only included in the error response when Developer Mode is enabled.
|A property of the information object. The server endpoint that triggered the current route.||Yes|
|A property of the information object. The name of the current route.||Yes|
|A property of the information object. The HTTP method (such as GET, PUT, POST, or DELETE) that the original HTTP request used.||Yes|
A child object that contains propeties about the originating exception, if there is one.
The cause object is only included in the error response when Developer Mode is enabled.
|A property of the cause object. The error message output by the original exception.||Yes|
|A property of the cause object. The stack trace for the original exception.||Yes|
Most properties of the error respons are only included if Developer Mode is enabled. For more information, see Enabling and disabling Developer Mode.
In addition to creating a JSON object for send to the client, the Akula Server also sets the value of the HTTP status code of the response. In this case, the HTTP status code of the response would be 500, but you can set it to whatever you want. (Note that although the example module above sets the output message's status code to 200, this is ignored when an exception is thrown. The Akula Server determines what the status code should be, based on the error that was thrown.)
Setting HTTP status codes
In your custom module, you can set the HTTP status code for the response to some value other than 200 (OK). If you do this in a module that is not the last module in the route, the status code is ignored (by default) and the next module in the route will execute as normal. If you set the HTTP status code in the last module in the route, then the HTTP response that the Akula Server generates sets the HTTP status to that value.
The following example sets the status code of the response to 400 (Bad Request). The body of the output message is returned to the client, but the HTTP status code is set to 400:
It is up to the client app to determine how to handle an HTTP status code. If, for example, you use a browser to view the response, the browser will typically interpret anything other than a 2xx or 3xx status code as an error, and will render its own error page. Mobile clients can be configured to check the status code and modify their output accordingly.
The Akula Server has its own exception class, AKException, that you can use to throw custom errors and thereby generate custom error responses to return to the client.
To throw an AKException, instantiate an AKException object and then use the Java
throw statement, as the following example shows:
As with any thrown Java Exception, the Akula Server immediately stops processing the route and returns the error to the client. Akula converts the AKException object into a JSON object error and sets the
The following example shows a typical HTTP response that the Akula Server sends to the client when an AKException is thrown:
In this case, the Akula Server also sets the HTTP status code of the response to 442.
The previous example shows one common constructor of the AKException class. This class has many constructors, which you can use based on how much information you want to include in the response. Another common constructor adds more information about the Exception:
The previous example adds the infoMap object to the output. The Akula Server extracts the values inside the infoMap and inserts a new JSON child object
information into the error response:
You can also include the exception's stack trace in the response. To do this, you include a Throwable object when constructing the AKException, as the following example shows:
When the Akula Server encounters an AKException with a Throwable in it, the server extracts the stack trace and adds it to the JSON error response as a
cause child object. The Akula Server defines the
msg (the error message) and
stacktrace (the stack trace) properties on the cause object. If there are nested causes, the Akula Server adds up to four additional child
cause objects with the corresponding
After Akula throws an exception and returns the error, a client app can process the response. For information on handling exceptions in a client app, see Handling Exceptions and Errors.
For a complete list of AKException constructors, see the API reference for the AKException class.