Configuration Files

Appkit centralises configuration of the application using files found in the /conf folder. In a source project you will find this folder in /src/main/resources but in a packaged WAR file these can be default be found in the /WEB-INF/classes folder of the archive.

Configuration locations

The configuration files can be placed outside of the application and centrally accessed by multiple instances. To reference these in a different location set the twigkit.conf system property to the absolute file path of the /conf folder, for example:

-Dtwigkit.conf=file://${path-to-your-conf-folder}

Application-wide configuration files

Appkit contains two main, application-wide configuration files: twigkit.conf and cors.conf. Further to that you will find folders organised by function or module for centralised configuration of individual aspects of Appkit such as platforms, processors and services.

twigkit.conf

The Appkit application looks up various global settings from a twigkit.conf configuration file that the application tries to locate relative to /conf on the runtime classpath.

Configuration parameters

  • bundleTimeToLive (java.lang.Long) – The number of milliseconds a resource bundle (for example, a file like languages_en.properties), can remain in the Java resource bundle cache without being validated against the source file from which it was constructed. The value 0 indicates that a bundle must be validated each time it is retrieved from the cache. If bundleTimeToLive is negative, or missing, then the bundle cache will have no expiration control (that is, entries are only evicted from cache due to runtime or memory constraints).

  • license-file (java.lang.String) – Name of the license file, including the path to the file, for example, /twigkit.lic.

  • ui.trim-white-space (java.lang.String) – Whether to trim whitespace, true or false
    Default: false

cors.conf

CORS or Cross-Origin Resource Sharing is a recent W3C effort to introduce a standard mechanism for enabling cross-domain requests from web browsers to servers that want to handle them.

Appkit supports CORS filtering by default. You can control the options for the particular header attributes using the cors.conf file at the root of the /conf folder.

Configuration parameters

  • cors.allowOrigin (java.lang.String) Whitespace-separated list of origins that the CORS filter must allow. Requests from origins not included here will be refused with an HTTP 403 "Forbidden" response. If set to (asterisk), any origin is allowed.
    Default:

  • cors.supportedMethods (java.lang.String) List of the supported HTTP methods. These are advertised through the Access-Control-Allow-Methods header and must also be implemented by the actual CORS web service. Requests for methods not included here will be refused by the CORS filter with an HTTP 405 "Method not allowed" response.
    Default: GET, POST, DELETE, HEAD

  • cors.allowSubdomains (java.lang.Boolean) If true the CORS filter will allow requests from any origin which is a subdomain origin of the allowed origins. A subdomain is matched by comparing its scheme and suffix (host name or IP address and optional port number).
    Default: false

  • cors.supportsCredentials (java.lang.Boolean) Indicates whether user credentials, such as cookies, HTTP authentication or client-side certificates, are supported. The CORS filter uses this value in constructing the Access-Control-Allow-Credentials header.
    Default: false

  • cors.maxAge (java.lang.Integer) Indicates how long the results of a preflight request can be cached by the web browser, in seconds. If -1 unspecified. This information is passed to the browser via the Access-Control-Max-Age header.
    Default: 3600

Central configuration files versus inline configuration

Appkit supports configuring most aspects of Appkit modules (for example, platforms, services, processors) centrally using the configuration files found in the /conf folder. These configuration files support hierarchical cascading of the files via our open-source project Fig. Alternatively, configurations are provided inline in the JSP pages via the various Appkit tags such as the search:platform tag.

The configuration files are organised by horizontally by function or by module. The main ones are organised by folder as follows:

/conf
	/platforms
	/processors
	/security
	/services

Hierarchical configuration

To make version control and specialisation of configuration easier the configuration is loaded hierarchically. To give an example, in the /platforms folder you might find a folder for the /gsa and/or '`/solr`:

/conf
	/platforms
		/gsa
		/solr

Within the /gsa folder, you might find a configuration file with the same name as the folder, in this case /gsa/gsa.conf could contain these general attributes:

name: twigkit.search.gsa.GSA
host: http://gsa.acme.com/
defaultQuery: http

Within this folder, you might then find one or more configurations which inherit or extend this one, for example, /gsa/experts.conf and /gsa/internal.conf where the former could include for example, only this attribute:

siteCollections: INTERNAL_ONLY
defaultQuery: category:internal

To access a given configuration, you separate the levels using dot notation:

platforms.gsa.internal

In this case, the configuration system will traverse the hierarchy (no matter how deep) and aggregate the configuration files, where in this case it would combine (and override the defaultQuery attribute) to create:

name: twigkit.search.gsa.GSA
host: http://gsa.acme.com/
defaultQuery: category:internal
siteCollections: INTERNAL_ONLY

You can then refer to this platform instance in other configuration files or in the search:platform tag:

<search:platform conf="platforms.gsa.internal" />

In this case Appkit will use the platform as configured centrally, irrespective of the search engine behind it, effectively abstracting the data provider from the view.

Loading values from configuration files

To load values from a configuration file, you could use this syntax (for JSP):

<fig:config from="conf" load="my-config" var="myConfig" />

Then you have ${myConfig.my-value} for any value key in the configuration.

In Java code, the above operation would appear as:

import twigkit.fig.Config;
import twigkit.fig.Fig;
import twigkit.util.FigUtils;
...

Fig fig = Fig.getInstance(FigUtils.getApplicationLoader()); // alternatively, @Inject via Google Guice
Config config = fig.get("myConfig");
String value = config.value("my-value").as_string();

Troubleshooting

How do I add special characters to key names in configuration files?

To add special characters to key names in configuration files you must escape the special characters. For example, if a key name contained a whitespace, such as My key: value then you would must escape the whitespace for the configuration to be correctly loaded. In this case, the correct syntax would be:

My key: value

This rule does not just apply to whitespace but any special character that you might want to use within a key name.