# Submit a java app

This document explains in detail, how to submit a JAVA application to 
Aalam apps server

File Format
-----------
The file to be uploaded is created by the Aalam's maven plugin
`aalam-maven-plugin`. When built using maven, the build plugin creates
a file at `target/aalam/package.tar.gz`. This is the file that needs to
be uploaded.


Framework Dependency in pom.xml
-------------------------------

In the list of dependencies for the application, `aalam-common` should be
included with the appropriate version, like

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

    <dependency>
        <groupId>cm.aalam.common</groupId>
        <artifactId>aalam-common</artifactId>
        <version>An appriate version</version>
    </dependency>

```

Build plugin in pom.xml
-----------------------

In the list of build plugins, one should add `aalam-maven-plugin` to create the
uploadable file. 

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

    <build>
        <plugins>
            <plugin>
                <groupId>cm.aalam.maven</groupId>
                <artifactId>aalam-maven-plugin</artifactId>
                <version>An appropriate version</version>
                <configuration>
                </configuration>
            </plugin>
        </plugins>
    </build>
```


Aalam build plugin configuration
---------------------------------

Following are the configuration items for building.

### `entryPoint`

This is **mandatory**.

The value refers to the entry point of the application code from the framework.
Value of the entryPoint should in the following format

    public.class.path:static_method_name

For example, if the entry point method is
`public static Callbacks app_entry(int state)` is in `cm/aalam/demo/TestApp.java`
the entry point will be

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

    <entryPoint>
        cm.aalam.demo.TestApp:app_entry
    <entryPoint>
```

- - - - - - - - - - -

### `staticsUrl`

This is *optional*

The prefix of the url on which all the static files are served. For the static
resources that are not served through urls starting with this prefix, has to
have a URL route registered for the same.

Following this prefix, the URL should have the path to the file. Files will
be looked up using `getResources()`. The resource name should be relative
to that of the resources folder. For example, for a URL
`/aalam/base/s/contacts/script.js` and a `staticsUrl` `/aalam/base/s`,
the file will be looked up as `getResources("/contacts/scripts.js")`.

With this setting, the application does not need to register explicit URLs
to serve static resources. The framework will automatically control the
response to these requests.

The value should be added to the configuration like

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

    <staticsUrl>
        /aalam/base/s
    </staticsUrl>
```

- - - - - - - - - - -

### `permissions`

Permissions are configured with multiple items.

Permissions of an app are grouped under a name. Every permission name will have
a group name. A permission of an app is identified by
`group-name/permission-name` within the app. And the same is referred as
`provider-code/app-code/group-name/permission-name` by other applications.


#### `groups`

This contains all the permission groups for this application. The child elements
this elements are the name of permission groups. It will of the following format

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

    <groups>
        <group>
            <name>PermissionGroupName1</name>
            <description>Description PermissionGroupName1</description>
        </group>
        <group>
            <name>PermissionGroupName2</name>
            <description>Description PermissionGroupName2</description>
        </group>
        .
        .
        <group>
            <name>PermissionGroupNameN</name>
            <description>Description PermissionGroupNameN</description>
        </group>
    </group>

```

The permission group name and the permission name should abide by the following
rules
- Can contain only alpha numeric character and hyphen '-'
- Should not start with hyphen


#### `permissions`

This is *optional*

This contains a list of `permission` items which inturn contains the details
of a permission item. Following is the format

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

    <permissions>
        <permission>
            <code>permissionName11</code>
            <description>Description for permissionName11</description>
            <group>PermGroupName1</group>
        </permission>
        <permission>
            <code>permissionName12</code>
            <description>Description for permissionName12</description>
            <group>PermGroupName1</group>
        </permission>
        <permission>
            <code>permissionName21</code>
            <description>Description for permissionName21</description>
            <group>PermGroupName2</group>
        </permission>
    </permissions>
```

Each permission item should have three children

- `code` - Should have the name for the permission item
- `description` - Shold hold the description for *this* permission item
- `group` - Should be the name of the group. This name should be present in the
            `permissionGroups`


#### `requires`

This contains a list of permissions required by the application. These
are the permissions of other application that this application needs to use
to access the APIs of other applications.

Following is the format

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

    <requires>
        <require>
            <app>providerCode1/appCode1</app>
            <group>PermissionGroupName1</group>
            <permission>permissionName1</permission>
        </require>
        <require>
            <app>providercode2/appcode2</app>
            <group>permissiongroupName2</group>
            <permission>permissionName2</permission>
        </require>
        .
        .
        <require>
            <app>providercode-n/appcode-n</app>
            <group>permissiongroupName-n</group>
            <permission>permissionName-n</permission>
        </require>
    </requires>
```

Each children of `requires` are `require` which should have the following three items

- `app` - Application identifier in the format `provider-code/app-code`
- `group` - Name of the permission group that belongs to the `app` and
            contains the needed permission
- `permission` - The name of the permission.


Everything put together will like below

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

    <permissions>
        <groups>
            <group>
                <name>General</name>
                <description>Generic permission for the java application</description>
            </group>
        </groups>
        <permissions>
            <permission>
                <name>access</name>
                <description>Access the index page of the java testapp</description>
                <group>General</group>
            </permission>
            <permission>
                <name>create</name>
                <description>Create database entries</description>
                <group>General</group>
            </permission>
        </permissions>
        <requires>
            <require>
                <app>aalam/base</app>
                <group>Users</group>
                <permission>manage</permission>
            </require>
            <require>
                <app>aalam/base</app>
                <group>Contacts</group>
                <permission>create</permission>
            </require>
        </requires>
    </permissions>
```

- - - - - - - - - - -

### `messages`

This is *optional*

This contains a list of `message` items which contains the details of the 
message templates.

This item defines the list of message templates used while sending alerts. For example,
when an app is installed in a portal an alert will be posted to some users with a fixed
template.

Each key in the value refers to the name of a message group. Message can be grouped,
so that it becomes easier for the users to follow/unfollow all the message in a
group.

Each message template is identified by it's `index` value. The index value should be
unique across this message map.

Format is as below

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

    <messages>
        <message>
           <index>1</index>
           <body>Template value 1, {dynamic_variable}</body>
           <group>MessageGroupName1</group>
        </message>
        <message>
           <index>2</index>
           <body>Template value 2, {dynamic_variable}</body>
           <group>MessageGroup1</group>
        </message>
        <message>
           <index>3</index>
           <body>Template value 3, a static template</body>
           <group>MessageGroupName2</group>
        </message>
    </messages>
```

`body` contains the message template. Any dynamic value that needs to formatted
on the template should be put within `{}`. The value for the dynamic variables
will be given the application while posting the message. For example, when an
application is stopped, the template can have the `{app_name}` as a dynamic
variable and will supply the value for the `{app_name}` which is stopped, at
the time of posting this message.

A real world example will be like

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

    <messages>
        <message>
            <index>0</index>
            <body>
                Welcome to this portal. You are the administrator to this portal.
            </body>
            <group>WelcomeMessages</group>
        </message>
        <message>
            <index>1</index>
            <body>Welcome! You can check you permissions here.</body>
            <group>WelcomeMessages</group>
        </message>
        <message>
            <index>2</index>
            <body>New app - {app_name} is installed by {user}</body>
            <group>AppMessages</group>
        </message>
        <message>
            <index>3</index>
            <body>'{app_name}' is uninstalled by '{user}'</body>
            <group>AppMessages</group>
        </message>
    </messages>
```

In the above example, we have two groups.
- `WelcomeMessages` are the message that the application sends whenever a new
   user joing this portal. The index 0 mesage body is used for posted the owner
   and index 1 is posted for posting other users.
- `AppMessages` are the message sent when any app is installed or uninstalled.
   Items with `{}` will be replaced by relavant values.


- - - - - - - - - - -

### `settings`

This is *optional*

This item defines the list of `settings` variables for an application.
`settings` are variables for which the user chooses the values.

These variable will be listed under the app in the `Settings` app.

A setting variable is of two type
- Global
> Global settings are variables that is applicable to the entire portal. To
modify a global setting, a user needs to have `aalam/base/Settings/modify-globals`
permission. Example, date and time format is a global setting.

The value of these settings is the same for all the users.

- Personal
> Personal settings are the variables that are varies with the user's choice.
A user doesn't need any extra permission to modify personal settings. Example,
choice of a colour theme is a personal setting.

The value of these settings varies with the user's choice.

The settings format is as below

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

    <settings>
        <setting>
            <code>short_form_description. See "Code Specification"</code>
            <name>Detailed name, which will be seen by the user</name>
            <default>The default value to use till user chooses a value</default>
            <property>number/text/choices. See "Property specification"</property>
            <numberMax>Maximum number to accept. Applicable only of property is 'number'</numberMax>
            <numberMin>Minimum number to accept. Applicable only of property is 'number'</numberMin>
            <textMaxLen>Maximum length of text value to accept. Applicable only of property is 'text'</textMaxLen>
            <choicesType>(single | multiple). Applicable only if property is 'choices'</choicesType>
            <choicesMethod>(dropdown | boxes). Applicable only if property is 'choices'</choicesMethod>
            <choicesValues>
                <!-- This list of choices for the user to choose from.
                     Applicable only if the property is 'choices' !-->
                <value>Choice value 1</value>
                <value>Choice value 2</value>
                .
                .
                <value>Choice value 3</value>
            </choicesValues>
            <type>Global or Personal</type>
            <help>Information on how to input the values</help>
            <validator>Method name to be invoked for validation. See "Method Specification"</validator>
        <setting>
        .
        .
    </settings>
```

#### Code Specification
Settings code is a short for description for a setting variable. The code
value will not displayed to the user, it is to identify the setting 
by the framework and other applications.

It should abide by the following rule.

- Can contain only alpha numeric and hyphen `-` characters.
- Should not start with hyphen character.
- It should be unique for an application.


#### Property Specification:
Every setting can have following property type

- number
> Integer or decimal value
- text
> String
- Choices
> Let the user to choose from a list of choices. If the choice type and method
are 
> - single, dropdown: A listbox will be displayed to choose the value
> - single, boxes: A set of radio buttons will be displayed
> - multiple, dropdown: List box with support for multiple selection will be displayed
> - multiple, boxes: A set of check boxes will be displayed.


#### Method Specification:
This is the method that will invoked by the framework whenever this setting is
altered. The method name should be of the format

    public.class.path:method_name

The validator methods should accept two parameters

1. *Settings code*
   The code of defined for a setting in the application's settings map object.
2. *Input value*
   The value that was inputted by the user, for this `settings_code`

The method should return either of the following

- `null`
  When the method find the `input_value` to be valid for the `settings_code`
- `String message`
  When the validator find an error with the `input_value`. This message will be
  displayed to the user, so it will help if it is more informative.


A sample validator can be seen below


```eval_rst
.. code-block:: java

    public class SettingsValidators {
        public static String colorValidator(String settingsCode, String inputValue) {
            if (!Arrays.asList(new String[]{"red", "green", "blue"}).contains(inputValue)) {
                /* Invalid value, return a error message. */
                return "Value should be either 'red', 'green' or 'blue'"
            }
            /* Value is valid, so return null. */
            return null
        }
    }
```

- - - - - - - - - - -

### `hooks`

This lists the set of hooks that this application is interested in. Please see
the framework documentation for more information on hooks.

Value contains just child elements
- `items`
> List of URLs on other applications that this application wants to hook.
- `restricts`
> List of URLs on this application that it desires to restrict being hooked by other
applications. One can include exceptions to the restrictions. When restricted, a
URL can not be hooked by other applications.

`hooks` format is as below.

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

    <hooks>
        <items>
            <item>
                <app>The app to be hooked in the format provider-code/app-code</app>
                <url>Url to be hooked <!-- See Hook URL format !--></url>
                <type>A or B or BA (Before, After or Both)</type>
                <method>Method on the URL to be hooked</method>
                <handler>The callback method name <! -- See, Hook callback !--></handler>
            </item>
            <item>
                <!-- Same as above !-->
            </item>
        </items>
        <restricts>
            <restrict>
                <url>Url to be restricted <!-- See Hook URL format !--></url>
                <type>A or B or BA (Before, After or Both)</type>
                <method>URL method to be restricted</method>
                <exceptions>
                    <!-- The list of apps excluded for this restriction !-->
                    <exception>Application identification in the formation provider-code/app-code</exception>
                    <exception><!--Another app, in the format same as above!--></exception>
                </exceptions>
            </restrict>
            <restrict>
                <!-- Same as above !-->
            </restrict>
        </restricts>
    </hooks>
```


#### Hook url format
If the url needs to be matched statically, then a static url can be used. For
example, if you want to hook `GET /aalam/base/user/user@test.test`, you
can input URL path as is.
But if you want to include a wildcard match you have to use 

    /aalam/base/user/*

The asterik `*` matches an element with the slashes `/<matches-only-this-value/`. For
example, the above will match the following url

    /aalam/base/user/user1@test.test
    /aalam/base/user/user2@test.test

But will not match 

    /aalam/base/user/user1@test.test/status

Wherever you want to add a wildcard match, keep an asterik `*`. For exampl,

    /aalam/base/*/user1@test.test/*

Will match the following urls

    /aalam/base/user/user1@test.test/status
    /aalam/base/user/user1@test.test/info
    /aalam/base/permissions/user1@test.test/assign


#### Hook Callback
Method name should be like

    public.class.path:method_name


Refer the [java framework documentation](http://docs.aalam.io/_/javacommon/latest/hooks.html)
for more information on the parameters and the return values of the hook callback methods.

- - - - - - - - - - -

### `libdeps`

libdeps are the additional dependencies in the form other than Java maven packages.
For example, if your app depends on some libraries like libjpeg or libz those
dependencies can be listed under libdeps.

The libdeps is nothing but a listing of a set of commands which fetches or builds
some program or library and it's artifacts that will be used by your app.

The packager runs on a tiny core linux based distribution. You can use
`tce-load` to install `.tcz` packages.

For example, let's say your app has a dependency for some Java package
which has a native library which inturn depends on `libz.so` and `libjpeg.so`.
`libz.so` is available from the tiny core linux package `zlib_base-dev.tcz`
and `libjpeg.so` is available from the package `libjpeg-turbo-dev.tcz`.
For your app to run properly, you would need these libraries.

In such a case your libdeps should be like the following

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

    <libdeps>
      <libdep>
        <name>
          libz
        </name>
        <actions>
          <value>tce-load -wic zlib_base-dev</value>
        </actions>
        <artifacts>
          <value>/usr/lib/libz.so</value>
        </artifacts>
      </libdep>
      <libdep>
        <actions>
          <value>tce-load -wic libjpeg-turbo-dev</value>
        </actions>
        <artifacts>
          <value>/usr/local/lib/libjpeg.so.62</value>
        </artifacts>
      </libdep>
    </libdeps>

```

In the above example, you can just have one action/artifact object to install
both the libraries in one command.

Alternatively, you can even build libraries from source using make and gcc.
If the building process needs libraries like autoconf, libtool etc, you can add
an action to install these required `.tcz` packages before running the actual
command to build the app.

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

    <libdeps>
      <libdep>
        <name>Compile from source</name>
        <actions>
          <value>tce-load -wic cmake autoconf libtool curl</value>
          <value>curl -v https://url.of.the.source.archive | tar -xz -C /tmp/source-path</value>
          <value>cd /tmp/source-path &amp;&amp; ./configure &amp;&amp; make</value>
        </actions>
        <artifacts>
          <value>/tmp/source-path/buid-dir/lib.so</value>
        </artifacts>
      </libdep>
    </libdeps>

```
- - - - - - - - - - -

### `publicRootable`

By setting this property to `True`, you mean that this web application can
serve the `'/' (slash/root)` page for the public (anonymous) users. The users
can choose one such public rootable app from their apps list to serve it as a
website for the public users.
Apps that are publicly rootable should have the routes register for the same.

For example, if your app is public rootable, then you should be having a route
for `'/'`. These routes work only for the anonymous users. For
users who are authenticated, these routes will never be used. For authenticated
users, routes starting with `/<provider-code>/<app-code>/` alone will work.

``eval_rst
.. note:: Except `'/'` all the other routes should begin with `'/_/'`. Only
then the requests will be routes to the public rootable app.
``

The value should be added to the configuration like

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

    <publicRootable>True</publicRootable>
```

This is *optional*

- - - - - - - - - - -

### `depends`

When your application depends on other applications, those dependecies must be
listed under this section.

These dependencies are used while installing or updating any application. Each
dependency should be given in the following format.

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

    <depends>
      <depend>
        <provider_code>Provider code of the dependee app</provider_code>
        <app_code>App code of the dependee app</app_code>
        <pattern>The version as is or a regex pattern to match more than one version</pattern>
      </depend>
    <depends>

```

You can still use APIs for other apps from your application even without listing
them under this section. But there is no guarentee that that API will be
successfull. For example, the Aalam Invoicer application depends on Aalam Stock
app. It lists the Stock app unders its `depends` section. But the Aaalam
invoicer can call API of other app say a payment service application. Since the
payment service app is not listed under it's list of dependencies, there is no
guarentee that the payment service is present or not, event it is present,
there is not guarentee that it's version is suitable for it's version.