Configuration files

For the description of your application (under directory "app/")

  1. views/*.xml
  2. app.properties
  3. app-hidden.properties

For engine configuration (under directory "engine/")

  1. post-processors.xml
  2. xpath-functions.xml
  3. logger.properties

For service configuration (under directory "service/")

  1. service.properties
  2. routes.properties
  3. jsw.properties

For security-related issues (under directory "service/")

  1. authenticators.xml
  2. resource-allow.txt
  3. http-headers.properties

For the description of your application (under directory "app/")

views/*.xml

These files contain the description of your application.

Please refer to this documentation to learn how to write your own application with Lavoisier.

app.properties

This file is used to avoid hard-coding things like username or URL into the description of your application. The properties defined in this file can be read from your application by using the Lavoisier XPath function property(string).

The format of this file is based on the standard Java properties file format: 

# a comment
key1=value1
key2=value2

2 Lavoisier-specific features have been added to that standard properties format:

  • A property can be referenced from the value of another property: 
    key2={$key1}-suffix
  • Properties files can recursively include other properties files. This can be done by using the special key @INCLUDES: 
    @INCLUDES=file1.properties file2.properties

The properties defined in this file (and its included files) are added to the JVM system properties. The web console allows you to dump all the JVM system properties if you are a authenticated as a service administrator of this Lavoisier instance.

app-hidden.properties

This file is used to store sensitive content, such as passwords.

The reference to this file must be included in the app.properties file, using the special key @HIDDEN_INCLUDES (this key does not support recursion): 

@HIDDEN_INCLUDES=app/app-hidden.properties

Format and features are the same as the app.properties file, but there are 2 differences with this file:

  • Its content will not be dumped by the web console, even when authenticated as a service administrator.
  • If the included hidden properties file is found under directory ~/.lavoisier/app/ (where ~ is the home directory of the Lavoisier service instance owner), then this file will be loaded instead of the one possibly available in the Lavoisier 'etc/app/' directory.

For engine configuration (under directory "engine/")

post-processors.xml

This file is used to configure post-processors. See documentation about processors and XML template to know more about how to configure post-processors.

xpath-functions.xml

This file is used to extend the XPath language with your own functions. It describes the signature of the functions and their implementation written in XPath language (in attribute @eval).

These custom functions belongs to the namespace "http://software.in2p3.fr/lavoisier/functions.xsd", so you need to prefix them when you are using them.

Examples: 

  • <function name="apos" eval='concat("'", $string, "'")'>
    <argument>string</argument>
</function>
  • <namespace prefix="date">http://exslt.org/dates-and-times</namespace>
<function name="timestamp-to-date"
          eval="date:add(date:date('1970-01-01T00:00:00'),date:duration($timestamp))">
    <argument>timestamp</argument>
</function>
logger.properties

This file is used to configure the log filtering rules.

It contains 3 main parts:

  • The list of logging handlers
  • The configuration of these handlers (including the minimum log level and the format of the logs they handle)
  • The minimum log level by Java packages and/or classes

See the official documentation of the Java Util Logging system to know more about what you can do with it.

For service configuration (under directory "service/")

service.properties

This file is used to configure the service layer of your Lavoisier framework.

It supports the following properties to enable features:

  • lavoisier.http.disable: Boolean property used to disable listening to HTTP requests. When set to "true", any incoming HTTP request will be forwarded to HTTPS. The default value for this property is: false
  • lavoisier.http.port: Number property used to set the port for listening to HTTP requests. The default value for this property is: 8080
  • lavoisier.https.port: Number property used to set the port for listening to HTTPS requests. The default value for this property is: 8443
  • lavoisier.html.error: String property used to set the path of the HTML file to be used when displaying an error message. The default value for this property is: html/error.html
  • lavoisier.session.timeout: Number property used to set the timeout in seconds for a HTTP session. The default value for this property is: 600
  • lavoisier.session.logout.redirect: String property used to set This property has no default value.
  • lavoisier.ssl.keyStore: String property used to set the path to the server certificate in either JKS or PKCS12 format. This property has no default value.
  • lavoisier.ssl.keyStorePassword: String property used to set the passphrase protecting the server certificate set by the property lavoisier.ssl.keyStore. This property has no default value.
  • lavoisier.ssl.trustStore: String property used to set the path to the JKS file or the directory containing the trusted Certificate Authority Chains. This property has no default value.

It also supports any JVM system property. For example:

  • javax.net.debug: Set this property to value "ssl" to add some traces when debugging SSL issues.

For example, to set your service to support HTTPS requests, you will have to set the following properties with paths to your own files: 

# This activates the HTTPS listener:
lavoisier.ssl.keyStore=/path/to/your/javaKeyStore_or_pkcs12cert
lavoisier.ssl.keyStorePassword=changeit
lavoisier.ssl.trustStore=/path/to/your/javaTrustStore_or_caCertsDirectory

If your server certificate is in a format different from JKS or PKCS12, you will have to convert it by using respectively the command keytool or the command openssl. For example, to convert a certificate from CRT format to PKCS12 format: 

openssl pkcs12 -export -in localhost.crt -inkey localhost.key -out server_cert.p12
routes.properties

This file is used to set the routing rules for your web application.

It contains a list of key/value pair:

  • The key is the path of the source URL given by the user
  • The value is the path of the target view that is mapped to this URL.

This file supports mapping arguments from the source URL to the target view. It also supports mapping path to arguments and arguments to path. This is done by nesting the path item and/or the argument into braces: 

# application-specific routes example
/vo/{voName}?service\={serviceType} = myView/root/vo[@id='{voName}']?service={serviceType}-suffix
/vo/{voName}/service/{serviceType}  = myView/root/vo[@id='{voName}']?service={serviceType}

The order matters ; for a given URL, the first matching rule will be applied. Unless you know what you are doing, the default rules should not be removed: 

# default routes (do not remove)
/ = _default_?accept=html
jsw.properties

This file is used to extend the default configuration of the Java Service Wrapper module.

The Java Service Wrapper enables a Java Application to be run as a Windows Service or UNIX Daemon. It also monitors the health of your Application and JVM.

Editing its configuration file may be needed, for example:

  • to add a Java library to the classpath (for example the JDBC driver that you need to use to access your database) 
    wrapper.java.classpath=%REPO_DIR%/my-lib.1.0.jar
  • to pass some arguments to the JVM when starting the Lavoisier service (for example to add a system property) 
    wrapper.java.additional=-Dlavoisier.app.directory=../../etc/app/

The format and supported properties are the same as for the JSW configuration file, except that you don't need to number your properties when adding an item to a multi-values property.

When you make changes to this configuration file, you must run the Lavoisier command lavoisier-post-install to apply these changes to the JSW configuration file.

For security-related issues (under directory "service/")

authenticators.xml

This file is used to configure authentication by declaring chains of authenticator plugins. See documentation about authenticators to know more about how to configure authentication for Lavoisier data views.

resource-allow.txt

This file is used to set the list of allowed directories.

The authorisation is recursive: when a given directory is allowed, all its descendant directories will be allowed as well. If a directory is not allowed, or descendant of an allowed directory, then the access to its entries will be denied to any Lavoisier user (including those authenticated as service administrator).

Only the directories that are included in the Java classpath (including the Lavoisier etc/ directory) can be accessed through this resource mechanism.

However, you can still enable to files that are not included in the Java classpath by explicitly configuring a data view using the FileConnector and/or the DirectoryConnector for example. The resource-allow.txt file does not apply to this use-case.

http-headers.properties

This file is used to set the HTTP headers of Lavoisier service responses.

For example, to solve issues with cross-scripting protection, you may need to set the property Access-Control-Allow-Origin with the URL of the external site that you need to allow: 

Access-Control-Allow-Origin = http://example.com