Configuration Guide

Apache Isis' 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 Isis application.

Deployment Types

Apache Isis 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 Isis
deployment type
Apache Wicket library
configuration

prototyping

development

production

deployment

By default Apache Isis 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
  • isis.deploymentType system property

    -Disis.deploymentType=PROTOTYPING

It is also possible to explicitly specify production mode:

  • PRODUCTION system property

    -DPROTOTYPING=false
  • isis.deploymentType system property

    -Disis.deploymentType=PRODUCTION

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

IsisSystemEnvironment domain service

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

Specifying components

Components are pluggable parts of the Apache Isis 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) {
        IsisPresets.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 Isis v1.x) is the top-level Spring @Configuration. It looks like this:

AppManifest.java
@Configuration
@Import({
        IsisModuleCoreRuntimeServices.class,                    (1)
        IsisModuleSecurityShiro.class,                          (2)
        IsisModuleJpaEclipselink.class,                         (3)
        IsisModuleViewerRestfulObjectsJaxrsResteasy4.class,     (4)
        IsisModuleViewerWicketViewer.class,                     (5)
        ...
        ApplicationModule.class,                                (6)
        ...
})
public class AppManifest {
}
1 Mandatory - specifies the core of the Apache Isis framework
2 Enables the Shiro security mechanism. There are several security implementations, precisely one must be selected
3 Enables JPA/Eclipselink for persistence.

Alternatively, IsisModuleJdoDataNucleus5.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`IsisModuleXxx`, 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 IsisModuleXxx must be referenced using an @Import.

Configuration Properties

The core framework has a large number of configuration properties, as do the various components. For that matter, so do some of the subdomain libraries, bounded context mapping libraries and value type libraries.

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

IsisConfiguration domain service

Applications can discover the current configuration properties for the framework (under the isis top-level key) by injecting the IsisConfiguration 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 of 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
isis:
  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).