Documentation 3.0 Beta
Page: Creating Custom Modules
Page: Configuring and Deploying a Custom Module
Page: Building and Deploying AKZ Files
Page: Using Routes
Page: Accessing the Message Body in a Route
Page: Using Modules
Page: Built-in Modules
Page: SQL Module
Page: Getting Binary Data with the SQL Module
Page: HTTP Module
Page: Cache Module
Creating Custom Modules
This section describes the following topics:
To create a custom module, you use Java. You should consider using an IDE such as Eclipse or IntelliJ to make development easier. This document assumes that you either are using an IDE or have some familiarity with creating Java projects.
To create a new module, you implement the AKModule interface. This interface provides API hooks to handle the user specific customizations needed for the module to process a request.
The API can be broadly classified into the following areas:
- Messaging API: Responsible for the messages that are passed between the modules.
- Module API: Registers a module, processes individual requests, and generates the response.
The messaging API consists of the following primary interfaces:
- AKExchange: The AKExchange interface represents the sole object travelling in a route as the request is being processed. The AKExchange acts as a container for the request object and the message object that is passed from one module to the next.
- AKRequest: The AKRequest interface contains methods to get information about the original HTTP request, including HTTP request parameters, attachments, and HTTP request body that are used for processing the request. The values in this object typically do not change: they remain the same as the request moves through its processing pipeline.
- AKMessage: The AKMessage interface contains the result of processing of a module. The AKMessage object is the object that you attach to the AKExchange as the output of one module so that it can be input of the next module in the route.
The module API consists of the following primary classes and interfaces:
- AKModule: The AKModule interface defines methods that every module implements to integrate with Akula's module API.
- AKRouteParameters : The AKRouteParameters class contains the URI, parameters, and properties that you can use to initialize a module.
- AKModuleServices: The AKModuleServices class provides helper methods for working with modules.
Tools for developing custom modules
In your development environment, add the Akula Server SDK's JAR file to your build path. This JAR file contains the class libraries for building new components.
For more information, see Creating a New Module Project.
Custom module samples
The documentation contains sample code that should help you get started when developing custom modules.
In addition, you can look at the source code for the Filter module. This simple module is provided as an example that shows some of the techniques that you use to write custom modules.
Another custom module included is the SQL Binary module. This module is used by the SQL module to allow certain databases to handle binary files.
Source code for the Filter module the SQL Binary module is available on the Downloads page (you must log in to access this page).
Deploying a custom module
To deploy a custom module:
- Compile the module into either a class file or JAR file.
- Edit your Akula project:
- Add the module's class or JAR file to the
- Use the custom module in one or more routes in your route configuration file.
- Map the class to a prefix in the prefix mapping file.
- Add the module's class or JAR file to the
- Archive your Akula project into an AKZ file with the Java
- Restart your app server.
These steps are described in detail in Configuring and Deploying a Custom Module.
Using multiple modules
You can use any number of custom modules in your routes. For example, you can use a filter module to reduce the amount of data, and then a sort module to sort the final data before returning it to the client. For more information, see Using Multiple Modules.
Sample custom module
Akula ships with a sample app scope that contains a custom module. For more information, see Server Hello World Sample App.
Debugging and logging
You can log messages from custom modules using Akula's built-in logging mechanism. For more information, see Creating custom logging messages.
You can remotely debug custom modules with your IDE. To do this, you must enable debugging in the Java app server that is running the Akula Server. For example, on Tomcat, add the following options to your catalina.bat (Windows) or catalina.sh (Linux/Mac) file:
rem Original setting:
rem set JAVA_OPTS=%JAVA_OPTS% %LOGGING_CONFIG%
rem New setting:
set JAVA_OPTS=%JAVA_OPTS% %LOGGING_CONFIG% -Xdebug -Xrunjdwp:transport=dt_socket,address=8081,server=y,suspend=n
debug option enables debugging in the server's JVM. The
runjdwp option defines the socket connection.
For other web servers, consult your documentation.
In your IDE, define a debug configuration that points to your Akula Server. Set the host and port to connect to the socket you defined in the JVM settings.
For example, in Eclipse, select Run > Debug Configurations to set the Host and Port Connection Properties:
After restarting your Java app server, you should be able to add breakpoints and work within the debugger when working with your custom module.