Configurations

In this chapter we see various configuration options available to the Axelor Open Platform applications.

Introduction

The application configuration is provided through various configuration files. These are:

  • application.properties - the application configuration

  • persistence.xml - hibernate/jpa configuration

  • log4j.properties - logging configuration

  • ehcache.xml - ehcache configuration

The most important of them is application.properties.

Application Configuration

The application.properties provides various configuration options for the application. It’s located under src/main/resources directory of the application project.

However, the application configuration can be provided from some external location using a JVM option.

$ export JAVA_OPTS="-Daxelor.config=/path/to/my-app.properties"

Of course the JAVA_OPTS can have other options too but it’s up to the user.

The configuration file generated from scaffolding template documents all the configuration options.

However, the database settings is most important:

# Database settings
# ~~~~~
# See hibernate documentation for connection parameters
db.default.dialect = org.hibernate.dialect.PostgreSQLDialect (1)
db.default.driver = org.postgresql.Driver (2)
db.default.ddl = update (3)
db.default.url = jdbc:postgresql://localhost:5432/my-database (4)
db.default.user = username (5)
db.default.password = secret (6)
1 the SQL dialect hibernate should use (depends on driver)
2 the JDBC driver (postgresql, mysql & hsql drivers are tested)
3 hbm2ddl option, (update, create, create-drop or validate)
4 the jdbc url to connect to
5 user name to be used to connect to the database server
6 user password to authenticate the user

If you want to use MySQL, MariaDB or any other compatible database server, use following settings:

# Database settings
# ~~~~~
# See hibernate documentation for connection parameters
db.default.dialect = org.hibernate.dialect.MySQL5InnoDBDialect (1)
db.default.driver = com.mysql.jdbc.Driver
db.default.ddl = update
db.default.url = jdbc:mysql://localhost:3306/my_database
db.default.user = username
db.default.password = secret
1 Only InnoDB/XtraDB engine is supported

Others settings :

  • application.name : application name

  • application.description : application description

  • application.version : application version

  • application.author : application author

  • application.copyright : application copyright

  • application.logo : header logo. Should be 40px in height with transparent background (default is img/axelor-logo.png)

  • application.home : home website. Link to be used with header logo.

  • application.help : link to the online help

  • application.mode : application deployment mode. Can be prod or dev (default is dev)

  • application.theme : CSS theme. If not defined, default theme is used.

  • application.locale : default locale (if not set, system default is used)

  • session.timeout : session timeout in minutes (default is 60)

  • file.upload.dir : storage path for upload files for attachments (default is \{user.home}/.axelor/attachments)

  • file.upload.size : maximum upload size in MB (default is 5 MB)

  • reports.design.dir : external directory for birt report designs (default is \{user.home}/.axelor/reports)

  • reports.output.dir : external directory for generated pdf reports (default is \{user.home}/.axelor/reports-gen)

  • data.export.encoding : data export (csv) encoding (default is ISO_8859_1)

  • data.export.dir : storage path for export action (default is \{user.home}/.axelor/data-export)

  • data.import.demo-data : whether to import demo data for the application (default is true)

  • template.search.dir : storage path for templates (default is \{user.home}/.axelor/templates)

  • view.single.tab: whether to use single tab layout (default is false)

  • view.menubar.location : set menu style. Can be left, top or both (default is left)

  • view.toolbar.titles : whether to show button titles in toolbar (default is false)

  • view.confirm.yes-no : whether show confirm dialog with yes/no buttons (default is Cancel/OK)

  • view.grid.selection : if set to checkbox, grid widgets will have checkbox selection enabled

All specified path can use specials variables :

  • {user.home} : reference to the home directory, System.getProperty("user.home")

  • {java.io.tmpdir} : reference to the tmp directory, System.getProperty("java.io.tmpdir")

The differences between prod and dev mode are :

  • use minify js/css file.

  • use browser cache.

  • don’t display technical popup.

JPA/Hibernate Configuration

The persistence.xml located under src/main/resources/META-INF provides JPA/Hibernate configuration.

See the hibernate docs for more details.

Using non-jta DataSource

By default, Axelor Open Platform applications uses local database connections but sometime it’s desirabled to use container managed non-jta datasource as the database connection.

Benefits of using non-jta-datasource are:

  • no need to store db user/passwd in application source

  • no need to configure database connection pool

In order to use non-jta-datasource, change the application configuration like this:

First, remove all the database settings from application.properties.

Second, change the META-INF/persistence.xml as follows:

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<persistence xmlns="http://java.sun.com/xml/ns/persistence"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" version="2.0"
  xsi:schemaLocation="http://java.sun.com/xml/ns/persistence
    http://java.sun.com/xml/ns/persistence/persistence_2_0.xsd">
  <persistence-unit name="persistenceUnit" transaction-type="RESOURCE_LOCAL">
    <provider>org.hibernate.ejb.HibernatePersistence</provider>
    <non-jta-data-source>java:comp/env/ds/AxelorDS</non-jta-data-source>
    <shared-cache-mode>ENABLE_SELECTIVE</shared-cache-mode>
    <properties>
      <property name="hibernate.dialect" value="org.hibernate.dialect.PostgreSQLDialect" />
      <property name="hibernate.hbm2ddl.auto" value="update" />
    </properties>
  </persistence-unit>
</persistence>

Now, configure the tomcat installation with required datasource.

  • Configure a new global resource in conf/server.xml

Add the following <Resource> element to <GlobalNamingResources>.

<Resource name="ds/AxelorDS" auth="Container"
    type="javax.sql.DataSource"
    factory="org.apache.tomcat.jdbc.pool.DataSourceFactory"
    maxActive="100"
    maxIdle="30"
    maxWait="10000"
    username="username"
    password="password"
    driverClassName="org.postgresql.Driver"
    url="jdbc:postgresql://localhost:5432/axelor-demo"/>

  • Configure a datasource context for the WAR in conf/server.xml

To link the name ds/AxelorDS to the jndi global name ds/AxelorDS for WAR consumption, add the following <Context> element inside the <Host> element.

The docBase is very important, it must match the WAR file or the application directory name deployed under webapps. 
<Context reloadable="true" docBase="axelor-demo" path="/axelor-demo">
  <ResourceLink
    global="ds/AxelorDS"
    name="ds/AxelorDS"
    type="javax.sql.DataSource"/>
</Context>

See tomcat documentation on for more details.

Finally, build the application war and deployed it on the configured tomcat instance.

Logging Configuration

The log4j.properties located under src/main/resources provides logging configuration.

EhCache Configuration

The ehcache.xml located under src/main/resources provides ehcache configuration.

Please see ehcache documentation for more details.

Global Context Configuration

Besides the static configuration values, we can also provide configuration for dynamic global context with context. prefix. It’s used by actions and script handlers when evaluating expressions and domain filters. The values can be referenced from expressions with special variable context.

# Custom context
# ~~~~~

# instance
context.hello = com.axelor.script.TestContext

# instance method
context.world = com.axelor.script.TestContext:hello

# static method
context.some = com.axelor.script.TestContext:staticMethod

# static field
context.thing = com.axelor.script.TestContext:STATIC_FIELD

# static values
context.flag = true
context.string = some static text value
context.number = 100

Now, we can use them in expressions like this:

<field ... value="#{__context__.hello.message}" /> (1)
<field ... value="#{__context__.world}" /> (2)
<field ... value="#{__context__.some}" /> (3)
<field ... value="#{__context__.thing}" /> (4)
<field ... value="#{__context__.flag}" /> (5)
1 calls getter on the instance
2 calls an instance method
3 calls a static method
4 public static final field value
5 any constant value

A special context setting config.appLogo can be used to to dynamically change header logo per user. For example:

config.appLogo = com.axelor.custom.LogoService:getLogo

The getLogo() method then can return link to user specific application logo.