# Tutorials

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

### Setup

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

    /
        pom.xml
        src/main/
          java/io/aalam/testapp/
            HookHandler.java
            TestApp.java
            TestEntry.java
          resources/
            create_form.html
            items_access.html
            index.html

### Entry point

The application entry accepts one parameter which is the
[state](io/aalam/common/Callbacks.rst) of the application.

*TestEntry.java*

```eval_rst

.. code-block:: java

    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.

```eval_rst

.. code-block:: xml

            <entryPoint>io.aalam.testapp.TestEntry:entryHandler</entryPoint>

```

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

*TestEntry.java*

```eval_rst

.. code-block:: java

    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.
             */
            m.connect("/aalam/testapp/",
                      new String[]{"GET"},
                      "sendHomePage");

            /* Below url accepts input data, and it can be in xml/json format.
             * It allows only valid users with "Items/create" permission.
             */
            m.connect("/aalam/testapp/items",
                      new String[]{"PUT"},
                      "createItem",
                      Permissions.all("Items/create").deny_anon());

            /* 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.
             */
            m.connect("/aalam/testapp/item/{item_name}",
                      new String[]{"GET"},
                      "getItem",
                      Permissions().deny_anon());

            /* Below URL is used to update a setting, but will permit a user
             * to update the setting that is created by the same user.
             */
            m.connect("/aalam/testapp/item/{item_name}",
                      new String[]{"POST"},
                      "updateItem",
                      Permissions().deny_anon());

        }

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

*TestApp.java*

```eval_rst

.. code-block:: java

    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 {
        }
    }

```

### Hooks

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

*HookHandler.java*

```eval_rst

.. code-block:: java

    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
             */
        }
    }

```

### pom.xml

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][aalam-maven] can be found [here][aalam-maven].

[aalam-maven]: http://docs.aalam.io/_/apps/latest/java.html#framework-dependency-in-pom-xml

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

```eval_rst

.. code-block:: xml

      <plugin>
        <groupId>io.aalam.maven</groupId>
        <artifactId>aalam-maven-plugin</artifactId>
        <version>0.1.0</version>
        <configuration>
            <!-- All configuration items !-->
        </configuration>
      </plugin>
```

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

```eval_rst
.. code-block::xml

    <dependencies>
        <dependency>
          <groupId>io.aalam.common</groupId>
          <artifactId>aalam-common</artifactId>
          <version>0.1.0</version>
        </dependency>
    </dependencies>

```


### Testing


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](http://docs.aalam.io/_/apps/latest/sdk.html) 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.


### Downloadables

Following are the source for the test application

```eval_rst
| :download:`pom.xml <testapp/pom.xml>`
| :download:`src/main/java/io/aalam/testapp/HookHandler.java <testapp/src/main/java/io/aalam/testapp/HookHandler.java>`
| :download:`src/main/java/io/aalam/testapp/TestApp.java <testapp/src/main/java/io/aalam/testapp/TestApp.java>`
| :download:`src/main/java/io/aalam/testapp/TestEntry.java <testapp/src/main/java/io/aalam/testapp/TestEntry.java>`
| :download:`src/main/resources/resources/index.html <testapp/src/main/resources/index.html>`
| :download:`src/main/resources/create_form.html <testapp/src/main/resources/create_form.html>`
| :download:`src/main/resources/items_access.html <testapp/src/main/resources/items_access.html>`
```