Configuration Guide

Apache Causeway' is a Spring Boot application, and so is typically configured using an application.properties or application.yml file.

The configuration can be obtained from a variety of external locations; see the Spring Boot documentation for more details.

The starter apps use application.yml for configuration that doesn’t change between environments, and config/application.properties for settings (such as JDBC URL) that does vary.

This chapter describes the configuration properties available to configure an Apache Causeway application.

Deployment Types

Apache Causeway distinguishes between the application being run in prototyping mode vs running in production mode. The framework calls this the "deployment type" (corresponding internally to the DeploymentType class).

A similar concept appears in the Apache Wicket framework (which is the library with which the Web UI (Wicket viewer) is implemented, of course). Wicket’s term is the "configuration".

Table 1. Wicket equivalent concepts
Apache Causeway
deployment type		 Apache Wicket library
configuration

prototyping

development

production

deployment

By default Apache Causeway runs in production mode. But if configured to run instead in prototyping mode, then any actions restricted to to prototype mode are visible. In particular, the "Prototyping" menu will appear, containing a number of framework-provided menu services - all restricted to prototyping mode. For example, menu items to run in fixture scripts are on this menu.

Prototyping mode can be enabled in a number of ways:

  • environment variable:

    export PROTOTYPING=true

  • PROTOTYPING system property

    -DPROTOTYPING=true

  • causeway.deploymentType system property

    -Dcauseway.deploymentType=PROTOTYPING

It is also possible to explicitly specify production mode:

  • PRODUCTION system property

    -DPROTOTYPING=false

  • causeway.deploymentType system property

    -Dcauseway.deploymentType=PRODUCTION

If (by a combination of mechanisms) both prototyping and production modes are specified, then production mode wins.

CausewaySystemEnvironment domain service

Applications can discover the prototyping mode by injecting the CausewaySystemEnvironment service.

Specifying components

Components are pluggable parts of the Apache Causeway framework that are responsible for the presentation layer, for security, or for persistence. Each component corresponds to one or more Maven module(s), and are specified using the Spring @Import statements from a top-level class annotated with Spring’s @Configuration annotation. These are then bootstrapped from a @SpringBootApplication or @SpringBootTest.

For example, the simpleapp starter app project is bootstrapped using SimpleApp, annotated with @SpringBootApplication:

@SpringBootApplication
@Import({
    AppManifest.class,                                          (1)
})
public class SimpleApp
            extends SpringBootServletInitializer {

    public static void main(String[] args) {
        CausewayPresets.prototyping();                              (2)
        SpringApplication.run(
                new Class[] { SimpleApp.class }, args);
    }
}
1 references the AppManifest, discussed below.
2 specifies prototyping mode. This enables actions marked for prototyping to become available, useful during the early stages of development.

In turn, the "app manifest" (the name has been retained from Apache Causeway v1.x) is the top-level Spring @Configuration. It looks like this:

AppManifest.java
@Configuration
@Import({
        CausewayModuleCoreRuntimeServices.class,                    (1)
        CausewayModuleSecurityShiro.class,                          (2)
        CausewayModuleJpaEclipselink.class,                         (3)
        CausewayModuleViewerRestfulObjectsJaxrsResteasy4.class,     (4)
        CausewayModuleViewerWicketViewer.class,                     (5)
        ...
        ApplicationModule.class,                                (6)
        ...
})
public class AppManifest {
}
1 Mandatory - specifies the core of the Apache Causeway framework
2 Enables the Shiro security mechanism. There are several security implementations, precisely one must be selected
3 Enables JPA/Eclipselink for persistence.

Alternatively, CausewayModuleJdoDataNucleus5.class would be specified in order to use JDO/DataNucleus instead.

Optional (though if omitted then only view models may be used, with hand-rolled persistence).
4 Enables the REST API (Restful Objects viewer).
5 Enables the Web UI (Wicket viewer)
6 References the application’s module(s), in this case just the one, ApplicationModule.

All of the components available are named in the form CausewayModuleXxx, so they are easy to discover.

Components currently do not use Spring Boot’s auto-configuration capabilities. That means that it’s not enough to just add the appropriate Maven module to the classpath; its corresponding CausewayModuleXxx must be referenced using an @Import.

Configuration Properties

The core framework has a large number of configuration properties, as do the various components. So do some of the extensions and value type libraries.

The remainder of this guide lists the various configuration properties available, broken out into logical sections.

CausewayConfiguration domain service

Applications can discover the current configuration properties for the framework (under the causeway top-level key) by injecting the CausewayConfiguration domain service. There are similar domain services for JPA/Eclipselink (EclipselinkConfiguration), JDO/DataNucleus (DatanucleusConfiguration) and RestEasy (RestEasyConfiguration), as used by REST API (Restful Objects viewer).

Applications can also create their own configuration properties file; the simpleapp starter app provides an example.

application.css

All the layout annotations provide the ability to specify adhoc CSS classes, associated with the corresponding element:

CSS can also be specified using the Xxx.layout.xml layout files. The viewer can then use this information within the rendered page. For example, the Web UI (Wicket viewer) adds the CSS as a style in a containing <div> for each element.

The serving of the CSS (containing the style definitions) is also viewer-specific. In the case of the Web UI (Wicket viewer) it uses Spring Boot to serve the CSS file, under static package on the classpath.

The name of the file under static is configurable, in either application.yml or application.properties. For example, the SimpleApp starter app uses application.yml:

application.yml
causeway:
  viewer:
    wicket:
      application:
        css: css/application.css

This corresponds to the static/css/application.css (in src/main/resources in the simpleapp’s webapp module).

If you change the contents of this file, you may find that your end users' browsers will still cache the old value. You can prevent this from occurring ("bust the cache") by setting this Spring Boot config value:

application.yml
spring:
  web:
    resources:
      cache:
        cachecontrol:
          max-age: 3600