A simple application

This tutorial goes through a test application line-by-line. This application tries to register the following URLs

  1. Accepts json input data, and returns an empty response if successfull
  2. Returns a html page
  3. Returns a json data
  4. Accepts some parameters and returns an empty response


Apart from your application source code, you will have to add certain a pom.xml which contains the list dependencies and the build configuration for the maven application.

For this example we are having a directory structure as shown below


Entry point

The application entry accepts one parameter which is the state of the application.


public class TestEntry {
    public static entryHandler(int state) {
        if (state != Callbacks.STATE_VALIDATION) {
            /* do the initialization here. */

        /* entry point should return a Callbacks object. */
        return new TestCallbacks();

The above entry point does not have anything to initialize or migrate. The list of callbacks should be returned no matter in what state the application is started.

This entry point has to be mentioned in the pom.xml of this project, under aalam maven plugin configuration.


Callbacks object

The above entry point is returning Callbacks object. Callbacks is an interface which needs to be implemented by the application. Since this is a small application we will write just the routes() method and stub the others.


class TestCallbacks implements Callbacks {
    public void routes(Mapper mapper) {
        /* We have the same handler for all the below urls. If not for submapper,
         * we will have to define 'handler' in each of the mapper.connect().
        Mapper.SubMapper m = mapper.subMapper(new TestApp())

        /* Below url sends an index page. The static prefix will be
         * used inside the html page to access the static resources.
         * no permissions attribute means it can be accessed by anyone.
                  new String[]{"GET"},

        /* Below url accepts input data, and it can be in xml/json format.
         * It allows only valid users with "Items/create" permission.
                  new String[]{"PUT"},

        /* Below URL will send a json output. We do not have a serializer
         * for this, because the framework will by default use the json
         * serializer for response data.
         * This api is denied for anonymous requests.
                  new String[]{"GET"},

        /* Below URL is used to update a setting, but will permit a user
         * to update the setting that is created by the same user.
                  new String[]{"POST"},


    /* Stub all the other methods in the Callbacks interface. */
    public void cleanup() {}
    public void migrate(String fromVersion) {}
    public void migrateCompleted() {}

Route Handler

Route handler is a public class which should define methods for all the action methods used in the URLs using this handler. The action methods should public static and should return Object.

In the routes() callback, the handler object is passed to the mapper using the submapper. TestApp should be a public class which has a construct that accepts no arguments.


public class TestApp {
    public static Object sendHomePage(HttpRequest request) {

    public static Object createItem(HttpRequest request) throws HttpException {

    public static Object getItem(HttpRequest request, String itemName) {

    public static Object updateItem(HttpRequest request, String itemName) throws HttpException {


We will present this application to any valid user in the front HTML page of this portal. To do so, we need to hook the base applications apps palette API. This is a ‘B’ hook, and the hook information should be present in this application’s pom.xml. The hook callback will look like the below code


public class HookHandler {
    public static Object indexHookHandler(HttpRequest request) {
        /* We present different entry points
         *   For admin user or users with Items/create permisssion
         * create form will be shown
         *   For authenticated users who is not authorized enought to create
         * items, can still access the items and items search page will
         * shown
         *   For the anonymous users, a general information will be shown


The pom.xml should contain the list dependencies and the aalam maven plugin configuration details. The maven plugin configuration should include details like the entry point, hooks, permissions, etc. Detailed explanation of the aalam-maven-plugin can be found here.

Following is how Aalam’s maven plugin has to be included in the pom.xml

      <!-- All configuration items !-->

Aalam common library has to be included in the list of dependencies. Following is how one can do that


We have successfully written the test application. But before submitting it to the apps server, it is better we test it. We can use our SDK to do the same.

Create a provider account with your provider code (aalam) in the SDK and create an app with your app’s code (testapp) inside the app’s provider account.

The packager accepts the file built by the aalam maven plugin specified in the pom.xml of this project. mvn install should create a file doc/testapp/target/aalam/package.tar.gz and this should be submitted to the SDK. The SDK starts packaging and if it successfully packages, a new version for the app will be created.

If you have a prior version of this app, you can either migrate your app to this version or you can set the running version of the app to the version that you just created. Since this is the first version we are creating, we can just use the “Set as current version” option.

After you choose the version to be the current version, the app will be started in the SDK. You can browse through your app’s url in a web browser from the same machine.