Berlioz mode

The Berlioz mode is a special immutable configuration value that Berlioz uses to determine which set of configuration files it should load.

It is generally used to distinguish between types of servers that may require slightly different configurations such as a production server and a local development server.

For example, when on a development server, some configuration values related to the host may be different or the logging may include debug information.

Current mode

To determine what mode is currently being used by Berlioz, you can look at the Berlioz initialisation log. When the Berlioz initialisation servlet starts, Berlioz prints on the system output the main initialisation log, including the version number and mode as well as how it was computed.

For example:

[BERLIOZ_INIT] ===============================================================
[BERLIOZ_INIT] Initialing Berlioz 0.10.2...
[BERLIOZ_INIT] Application Base: /srv/berlioz/sampleapp/WEB-INF
[BERLIOZ_INIT] Mode: derived from XML configuration file.
[BERLIOZ_INIT] Mode: 'dev'
...

Setting the mode

The mode is loaded when the Berlioz starts. More specifically, it is loaded by the Berlioz initialization servlet: InitServlet. This usually happens when the application or application server is restarted.

The Berlioz initialization servlet will load the first possible value from:

1. The initialization parameter of the InitServlet
2. The system property berlioz.mode
3. The only config-[mode].xml that exists
4. "default"

1. Initialization parameter

The mode can set by assigning the "mode" initialization parameter to the InitServlet in the Web descriptor (/WEB-INF/web.xml).

<servlet>
  <servlet-name>Initialiser</servlet-name>
  <servlet-class>org.pageseeder.berlioz.servlet.InitServlet</servlet-class>
  <init-param>
    <param-name>mode</param-name>
    <param-value>[mode]</param-value>
  </init-param>
  <load-on-startup>1</load-on-startup>
</servlet>

This method will override any other method.

2. System property

Alternatively, the mode can be set using a Java System Property .

This is usually set when the Java Virtual Machine starts using the -D command line option:

java  ... -Dberlioz.mode=[mode] ...

Typically, if your application server (such as Jetty, Tomcat, etc...) starts with a service, this can be set as one of the command line options on the service.

On Linux, this file would be in the /etc/init.d/ folder.

On Windows, this can be inserted in the .cmd or .bat file when starting Java.

3. Single configuration file

If the mode wasn't set using an initialization parameter or a system property, Berlioz will try to guess the mode by looking at the config files available in the /WEB-INF/config/ folder.

If there is only one file matching "config-[mode].xml" Berlioz will assume that the mode is to use the value of [mode].

If there are multiple files or no such files, Berlioz will fall back on "default".

Example

A developer works on Windows and wants to have all debugging messages displayed on the console while developing the application. The production server is a Linux machine and only warnings should be stored as logs. Also the application is using an API key to a third party app and the development machine is using a different API key.

The developer can create a "dev" mode and store his development API key in "config-dev.xml" and the logging configuration in "logback-dev.xml". They leave these mode specific files in the /WEB-INF/config and start the application server locally, relying on Berlioz to pick up the correct mode.

In production, they define the mode as "production" and specifies it directly in the service file to ensure that only that mode can be used on the server. The "config-production.xml" and "logback-production" contain the appropriate configuration for the server.

Created on 10 December 2015 , last edited on 08 January 2016 at 13:45