App configuration

Introduction

The HFactory framework predefines a few per-application settings and also allows an application to define its own, specific settings.

A setting is a <name, value> pair where

  • the name is a string of dot-delimited identifiers which can be thought of as a hierarchy
  • the value can be of any type, provided an implicit instance of the StringConv typeclass for that type is in scope

Predefined setting types

The HFactory framework provides StringConv instances for the most common Scala base types: Boolean, Int, String, etc. For the full list, please refer to the API documentation of the typeclass.

System settings

HFactory currently recognizes the following system settings:

Setting Type Kind Description
happ.root.dir String Req The root directory of the app. Relative to its base path.
happ.root.isResource Boolean Opt Whether the root is in the app’s resources.
happ.i18n.defaultLocale String Opt Name of the default locale.
happ.libs String Opt Colon-separated list of library directories.
happ.start.timeout Duration Opt Time after which an app’s start is deemed failed.
happ.table.prefix String Opt Prefix to use for all the tables of the app.

where Req = required, Opt = optional.

Root settings

Setting happ.root.dir is mandatory. HServer will not load an application if the setting is not defined. See the next section on how to do that.

Setting happ.root.isResource specifies whether the app’s root directory is within the app’s resources (in the Java sense) or not. By default, this setting is false. If set to true, the path of the app’s root directory, specified by happ.root.dir, is the path within the jars in the app’s class path.

i18n settings

The default locale is the name of the locale to be used in case the locale requested by the client is not available. If both the requested locale and the default locale are not available, the client will see the web UI messages “unrendered”.

Library settings

Setting happ.libs is optional. It’s a colon-separated list of directories containing jars to be added to the app’s class path. Although absolute paths are accepted, we strongly recommend using relative paths (those start at the app’s base path).

As an example, say the Hotspot app makes use of a third-party library geohash-1.0.10.jar for computing the geohash of a location, and our own ipgeoloc-0.3.jar to find an IP address’s geolocation. These jars can be put in the same directory as the app’s own jar (Hotspot/lib/) but to keep things nice and tidy, they can also be put in separate directories, say Hotspot/3rdparty/ and Hotspot/mylibs, provided these directories are specified in the configuration file as follows:

happ.libs=3rdparty:mylibs

Note that regardless of the value of this setting, the app’s lib/ directory is always on the app’s class path.

Start settings

The start timeout setting is optional; it defaults to 15 seconds. If the application’s start takes longer than its value, the start is considered to be a failure.

The default timeout may seem high, but the checks performed by HServer prior to launching an application may take a long time: these checks include the verification that the application’s HBase tables are properly set up, and the connection to HBase can be long.

The timeout is expressed in the form <length><unit>, where <unit> is either a full unit name or a standard unit abbreviation. For example: 2s, 2 sec, 2 seconds are valid timeouts, as are 3.5 ms and 18 ns, etc…

Table settings

The entities of an application are stored in HBase tables. All applications in an HServer instance share the same HBase backend, so to avoid table name clashes between apps, it is advised to define a table prefix for each app.

This ability to define a per-app table prefix also allows several instances of the app to be installed in the appstore of a single HServer, provided said instances are installed in different directories and a different prefix is defined for each of them: then each instance will use its own tables.

Configuration file

The only place where an application’s settings (as described in the previous section) can be defined is in a configuration file. The default configuration file for an app A is A.conf and located in the app’s base directory.

In our User Directory example, the application is called userdir and thus its default configuration file is called userdir.conf and would contain at least the following setting:

happ.root.dir=/

Note that the above root directory value, /, which corresponds to the application’s base directory, is just an example. An application could define as root a sub-directory of its base directory, for instance happ.root.dir=/www (again, relative to the applications base directory).

Several configuration files may coexist for a given application. The configuration to use is specified at the start of the application. See the HFactory Server guide for more information.

Accessors

All settings, whether HFactory-defined or application-specific, are accessed through the following accessors:

  • getSetting[T](name) returns the value of the specified setting with the specified type. If the setting is not found, this accessor raises the MissingSetting exception.
  • getOptSetting[T](name) returns Some(<v>) if found (with <v> of type T), and None if not.