Configuration

How to configure Civilian. Covers web.xml, civilian.ini, programmatic configuration and logging.

Minimal servlet configuration and web.xml

When deployed in a servlet container a Civilian application needs a web.xml file, placed into the WEB-INF directory. The minimal web.xml looks like this: 
<web-app version="3.0" ...3.0 schema-decls omitted...>
    <listener>
        <listener-class>org.civilian.server.servlet.ContextListener</listener-class>
    </listener>
</web-app>
The ContextListener will be run at server startup and bootstraps Civilian. It reads the config file WEB-INF/civilian.ini (see next section), initializes the application and dynamically creates all needed servlets.

The config file civilian.ini

The configuration file civilian.ini allows to configure most settings of Civilian.
When run in a servlet environment, the file is placed into the WEB-INF folder.

civilian.ini is a simple config file in java.util.Properties format, containing definitions in key = value form.

The config file of a newly scaffolded application (or of the samples) contains detailed comments which explain the various settings and their default values. We give an overview of the most important entries:

The develop flag controls if the Civilian Server and its applications run in development mode: 

develop = true
You can run one or more applications inside a Civilian server (This topic motivates why you would want to run more than one app). Every application config uses keys app.id.* with id being a unique identifier for each application.
The class entry gives the application class, path the relative path of the application under the server path. enabled allows to include/exclude the application from deployment. encoding is the default application encoding used for assets, HTML pages, etc. 
app.crm.class    = org.example.crm.web.CrmApp
app.crm.path     = /crm
app.crm.enabled  = true
app.crm.encoding = UTF-8
The locales and messages entries configure localization support and are explained here. 
app.crm.locales  = en-UK,de-CH,fr
app.crm.messages = resbundle:org/example/crm/text/message
The asset.location entries define the location of static resources (asset files), explained in detail here. 
app.crm.asset.location.0 = dir:assets
app.crm.asset.location.1 = dir:~/crm/files
app.crm.asset.location.2 = res:assets
Asynchronous processing of requests is enabled with the async entry: 
app.crm.async = true
To enable file uploads, upload definitions are needed. Take a look at UploadConfig to learn about these definitions which roughly correspond to a servlet MultipartConfig: 
app.crm.async.enabled           = true
app.crm.upload.enabled           = true
app.crm.upload.dir               = 
app.crm.upload.maxRequestSize    = 200000
app.crm.upload.maxFileSize       = 100000
app.crm.upload.fileSizeThreshold = 5000
Last there is a configuration which is only evaluated when development mode is turned on, explained in detail here. 
app.crm.dev.classreload = true

The built-in admin app can be configured with entries civ.admin.* which are similar to an application config: 

civ.admin.enabled = develop
civ.admin.path    = civadmin

Programmatic configuration

Almost all application settings of civilian.ini can also be changed programmatically by your implementation of the Application class. Some advanced settings can only be changed programmatically.
Programmatic configuration can be done in these methods: In addition
  • close() is called at application shutdown and can be used to release or close custom resources.
Please consult the javadoc of the config objects passed to the init-methods to learn about the configuration possibilities in detail.

Logging

Civilian uses SLF4J for logging. Please consult the SLF4J documentation how to configure SLF4J.
Log output is definitely not chatty, and hopefully to the point.

Civilian uses the following logger names for the corresponding part of the framework:

  • org.civilian.application
  • org.civilian.asset
  • org.civilian.classloader
  • org.civilian.controller
  • org.civilian.processor
  • org.civilian.request
  • org.civilian.response
  • org.civilian.server

Explicit servlet configuration

There can be situations when you want to have an explicit servlet declaration in your web.xml, instead of letting Civilian dynamically create servlets. Here is how you do it for an application with id myapp:

1. Prevent Civilian from dynamically creating the servlet, either in civilian.ini 

app.myapp.connect = false
or programmatically in init(AppConfig): 
protected void init(AppConfig config) {
    config.setConnect(false);
    ...
2. Define the following servlet in your web.xml: 
<web-app>
    ...
    <servlet>
        <servlet-name>myapp-servlet-name</servlet-name>
        <servlet-class>org.civilian.server.servlet.AppServlet</servlet-class>
        <init-param>
            <param-name>app.id</param-name>
            <param-value>myapp</param-value>
        </init-param>
    </servlet>
    <servlet-mapping>
        <servlet-name>myapp-servlet-name</servlet-name>
        <url-pattern>/mypath/*</url-pattern>
    </servlet-mapping>
    ...
<web-app>

Multiple applications in a server

Civilian allows to install more than one applications in a server. Of course it is perfectly fine to only use a single application, whose path equals the server path. Installing multiple application effectively means to segment the resource URL space below the server into multiple application spaces. The following gives some use-cases where multi-installations are usefull:
  • The admin app can be plugged-in into the application space and comes in handy during development to diagnose configuration problems.
  • The samples all run within the same Civilian server, not needing separate servlet contexts.
  • One can develop "module" applications which are not meant to run alone but to be added to another app, providing certain functionality.

Copyright © 2014-2016. All rights reserved.