<context-param>
<param-name>configuration</param-name>
<param-value>deployment</param-value>
</context-param>
Core Config’n Properties
1. Configuration Properties
Apache Isis' own configuration properties are simple key-value pairs, typically held in the WEBINF/isis.properties file and other related files. This guide describes how to configure an Apache Isis application.
|
This guide covers only the core configuration properties (relating to Apache Isis' metamodel and runtime management). Configuration properties for the viewers can be found in the Wicket Viewer guide and the RestfulObjects viewer guide. Likewise details of configuring security (Apache Shiro) can be found in the Security guide, and details for configuring the DataNucleus Object Store can be found in the DataNucleus guide. |
|
By default the configuration values are part of the built WAR file. Details on how to override these configuration properties externally for different environments can be found in the Beyond the Basics guide, (deployment chapter). |
1.1. Other Guides
Apache Isis documentation is broken out into a number of user, reference and "supporting procedures" guides.
The user guides available are:
The reference guides are:
The remaining guides are:
-
Developers' Guide (how to set up a development environment for Apache Isis and contribute back to the project)
-
Committers' Guide (release procedures and related practices)
2. Deployment Types
Apache Isis distinguishes between the application being run in development mode vs running in production mode. The framework calls this the "deployment type" (corresponding internally to the DeploymentType class).
(For mostly historical reasons) development mode is actually called SERVER_PROTOTYPE, while production mode is called just SERVER. (There is also a deprecated mode called SERVER_EXPLORATION; for all intents and purposes this can considered as an alias of SERVER_PROTOTYPE).
When running in development/prototyping mode, certain capabilities are enabled; most notably any actions restricted to prototyping mode (using @Action#restrictTo()) will be available.
2.1. Using the Wicket Viewer
Most of the you’re likely to run Apache Isis using the Wicket viewer. In this case Apache Isis' "deployment type" concept maps to Wicket’s "configuration" concept:
| Apache Isis (Deployment Type) |
Apache Wicket (Configuration) |
Notes |
|---|---|---|
|
|
running in development/prototyping mode |
|
|
running in production mode |
Wicket’s mechanism for specifying the "configuration" is to use a context parameter in web.xml; Apache Isis automatically infers its own deployment type from this. In other words:
-
to specify SERVER (production) mode, use:
web.xml -
to specify
SERVER_PROTOTYPING(development) mode, use:web.xml<context-param> <param-name>configuration</param-name> <param-value>development</param-value> </context-param>
2.2. Restful Objects viewer only
Most Apache Isis applications will consist of at least the Wicket viewer and optionally the RestfulObjects viewer. When both viewers are deployed in the same app, then the bootstrapping is performed by Wicket, and so the deployment type is configured as described in the previous section.
In some cases though you may be using Apache Isis to provide a REST API only, that is, you won’t have deployed the Wicket viewer. In these cases your app will be bootstrapped using Apache Isis' IsisWebAppBootstrapper.
In this case the deployment type is specified through an Apache Isis-specific context parameter, called isis.deploymentType:
-
to specify
SERVER(production) mode, use:web.xml<context-param> <param-name>isis.deploymentType</param-name> <param-value>server</param-value> </context-param> -
to specify
SERVER_PROTOTYPE(development) mode, use:web.xml<context-param> <param-name>isis.deploymentType</param-name> <param-value>server-prototype</param-value> </context-param>
2.3. Overriding the deployment type
If bootstrapping the application using Apache Isis' org.apache.isis.WebServer then it is possible to override the deployment type using the -t (or --type) flag.
For example:
java -jar ... org.apache.isis.WebServer -t SERVERwhere "…" is the (usually rather long) list of JAR files and class directories that will make up your application.
This works for both the Wicket viewer and the RestfulObjects viewer.
3. Configuration Files
When running an Apache Isis webapp, configuration properties are read from configuration files held in the WEB-INF directory.
The WEBINF/isis.properties file is always read and must exist.
In addition, the following other properties are searched for and if present also read:
-
viewer_wicket.properties- if the Wicket viewer is in use -
viewer_restfulobjects.properties- if the RestfulObjects viewer is in use -
viewer.properties- for any other viewer configuration (but there are none currently) -
persistor_datanucleus.properties- assuming the JDO/DataNucleus objectstore is in use -
persistor.properties- for any other objectstore configuration.This typically is used to hold
JDBCURLs, which is arguably a slight violation of the file (because there’s nothing in Apache Isis to say that persistors have to useJDBC. However, it is generally convenient to put theseJDBCsettings into a single location. If you want, they could reside inin any ofpersistor_datanucleus.properties,persistor.propertiesor (even)isis.properties -
authentication_shiro.properties,authorization_shiro.propertiesassuming the Shiro Security is in use (but there are no security-related config properties currently; use shiro.ini for Shiro config)
-
authentication.properties,authorization.propertiesfor any other security-related config properties (but there are none currently).
You can if you wish simply store all properties in the isis.properties file; but we think that breaking properties out into sections is preferable.
4. Specifying components
Bootstrapping an Apache Isis application involves identifying both:
-
the major components (authentication, persistence mechanisms, viewers) of Apache Isis, and also
-
specifying the domain services and persistent entities that make up the application itself.
The recommended approach is to use an AppManifest, specified either programmatically or through the configuration properties. This allows the components, services and entities to be specified from a single class.
To specify the AppManifest as a configuration property, use:
| Property | Value (default value) |
Implements |
|---|---|---|
|
|
|
By convention this implementation resides in an |
From this the framework can determine the domain services, persistent entities and security (authentication and authorization) mechanisms to use. Other configuration (including fixtures) can also be specified this way.
In the AppManifest itself, there are two methods which specify how authentication and authorisation are configured:
public interface AppManifest {
...
String getAuthenticationMechanism();
String getAuthorizationMechanism();
...
}These can return either:
-
"shiro" - enable integration with Apache Shiro, as described in the security user guide
-
"bypass" - bypass security (in effect, configure a no-op implementation that allows everything).
Note that these are actually aliases for concrete implementations. It is also possible to specify a fully qualified class name to replace either of the two security components, implementing the appropriate interface.
4.1. Viewer Configuration
Viewers are specified by way of the filters and servlets in the web.xml file; these are not bootstrapped by the framework, rather it is the other way around.
5. Configuring Core
This section lists the core/runtime configuration properties recognized by Apache Isis.
|
Configuration properties for the JDO/DataNucleus objectstore can be found in the Configuring DataNucleus section later in this chapter, while configuration properties for the viewers can be found in the their respective chapters, here for Wicket viewer, and here for the Restful Objects viewer. |
5.1. Domain Events
| Property | Value (default value) |
Description |
|---|---|---|
|
|
|
Whether an event should be posted if |
|
|
|
Whether an event should be posted if |
|
|
|
Whether an event should be posted if |
|
In order for these events to fire the action/collection/propert must, at least, be configured with the relevant annotation (even if no attributes on that annotation are set). |
5.2. Lifecycle Events
| Property | Value (default value) |
Description |
|---|---|---|
|
|
|
Whether an event should be posted if |
|
|
|
Whether an event should be posted if |
|
|
|
Whether an event should be posted if |
|
|
|
Whether an event should be posted if |
|
|
|
Whether an event should be posted if |
|
|
|
Whether an event should be posted if |
|
|
|
Whether an event should be posted if |
|
In order for these events to fire the class must be annotated using |
5.3. UI Events
| Property | Value (default value) |
Description |
|---|---|---|
|
|
|
Whether an event should be posted if |
|
|
|
Whether an event should be posted if |
|
|
|
Whether an event should be posted if |
|
In order for these events to fire the class must be annotated using |
5.4. Services
| Property | Value (default value) |
Description |
|---|---|---|
|
|
|
NO LONGER REQUIRED; replaced by (It used to define the list of fully qualified class names of classes to be instantiated as domain services; this is now inferred from the list of modules provided to the app manifest). |
|
|
|
Whether the changed properties of objects should be automatically audited (for objects annotated with |
|
|
|
Whether action invocations should be automatically reified into commands (for actions annotated with
|
|
|
|
(Whether property edits should be automatically reified into commands (for properties annotated with |
|
|
|
(Whether the framework should support + By default this is disabled. This can help reduce application start-up times. |
|
|
|
Whether the framework should support + By default this is enabled (no change in |
|
|
|
Whether changed objects should be automatically published (for objects annotated with |
|
|
|
Whether actions should be automatically published (for actions annotated with |
|
|
|
Whether properties should be automatically published (for properties annotated with |
|
|
fully qualified package names (CSV) |
NO LONGER REQUIRED; replaced by (It used to define the list of packages to search for domain services; ; this is now inferred from the list of modules provided to the app manifest). |
5.5. MetaModel Introspection
| Property | Value (default value) |
Description | ||
|---|---|---|---|---|
|
|
|
Whether to build the metamodel in parallel (with multiple threads) or in serial (using a single thread). In general, parallelisation should result in faster bootstrap times. |
||
|
|
|
How complete to build the metamodel during bootstrapping. Setting to
|
5.5.1. Lazy vs Full introspection.
The framework performs classpath scanning to identify all domain classes (domain services, mixins, entities, view models and fixture scripts), and the class-level facets for all of these are always created during bootstrapping.
In addition, the members for all domain services and mixins are also created, because these can give rise to contributed members of the entities/view models.
Lazy introspection means that the class members (properties, collections and actions) and their respective facets are not created for all of the entities/view models in the domain model. Instead these are created only on first access. The purpose of this is primarily to speed up bootstrapping during development.
To enable lazy introspection, either set the isis.reflector.introspect.mode configuration property to "lazy" or to "lazy_unless_production" (the latter only if also running with a deployment type of "production").
However, the trade-off is that metamodel validation is not performed in lazy mode.
|
Note that integration tests are run in |
5.6. MetaModel Validation
Metamodel validation is only done if full introspection is configured, see the isis.reflector.introspect.mode configuration property.
| Property | Value (default value) |
Description |
|---|---|---|
|
|
|
Custom implementation of See Custom Validator to learn more. |
|
|
|
Whether to check that collection action parameters have a corresponding choices or autoComplete facet. In the current implementation such a facet is always required, so this configuration option has only been introduced as a feature flag in case it needs to be disabled for some reason. |
|
|
|
Whether deprecated annotations or naming conventions are tolerated or not. If not, then a metamodel validation error will be triggered, meaning the app won’t boot (fail-fast). See also |
|
|
|
Whether to check that all domain objects discovered reside under the top-level module of the app manifest. Note that the application must be bootstrapped using an |
|
|
|
Whether to ensure that all classes in the metamodel map to a different object type (typically either as explicitly specified using |
|
|
|
Whether to check that the class has an object type explicitly specified somehow. The object type is used by the framework as an alias for the object’s concrete class; it is one part of the object’s OID and can be seen in the URLs of the Wicket viewer and Restful Objects viewer, and is encoded in the If the object type is not specified explicitly, then this can cause data migration issues if the class is subsequently refactored (eg renamed, or moved to a different package). This configuration property can be used to enforce a rule that the object type must always be specified (for persistent entities and view models). |
|
|
|
Ensures that all JAXB view models are not |
|
|
|
Ensures that all JAXB view models are not inner classes (so can be instantiated). |
|
|
|
Ensures that all JAXB view models have a This isn’t actually required (hence not enabled by default) but is arguably good practice. |
|
|
|
Ensures that for all JAXB view models with properties that reference persistent entities, that those entities are annotated with |
|
|
|
Ensures that for all JAXB view models with properties that are dates or times, that those properties are annotated with |
|
|
|
Whether to check that the class name in JDOQL Only "SELECT" queries are validated; "UPDATE" queries etc are simply ignored. |
|
|
|
Whether to check that the class name in JDOQL Note that although JDOQL syntax supports multiple |
|
|
|
Mixins provide a simpler programming model to contributed domain services. If enabled, this configuration property will treat any contributed service as invalid. This is by way of possibly deprecating and eventually moving contributed services from the Apache Isis programming model. |
|
|
|
When searching for If enabled then will not search for supporting methods with the exact set of arguments as the method it was supporting (and any supporting methods that have additional parameters will be treated as invalid). Note that this in effect means that mixins must be used instead of contributed services. |
|
|
|
Domain services are stateless (at least conceptually) and so should not have any properties or collections; any that are defined will not be rendered by the viewers. If enabled, this configuration property will ensure that domain services only declare actions. |
Also:
| Property | Value (default value) |
Description |
|---|---|---|
|
|
|
Whether deprecated facets should be ignored or honoured. By default all deprecated facets are honoured; they remain part of the metamodel. If instead this property is set to In most cases this should reduce the start-up times for the application. However, be aware that this could also substantially alter the semantics of your application. To be safe, we recommend that you first run your application using |
5.7. UI Facet Config Properties
| Property | Value (default value) |
Description |
|---|---|---|
|
|
regex:css1, regex2:css2,… |
|
|
|
regex:fa-icon,regex2:fa-icon2,… |
Comma separated list of key:value pairs, where the key is a regex matching action names (eg See UI hints for more details. |
5.8. Programming Model
| Property | Value (default value) |
Description |
|---|---|---|
|
|
|
This property is now IGNORED. It was previously used to customize the programming model, this should now be done using |
|
|
|
Fully qualified class names of (existing, built-in) facet factory classes to be included to the programming model. See finetuning the programming model for more details. |
|
|
|
Fully qualified class names of (new, custom) facet factory classes to be included to the programming model. |
|
|
|
Fully qualified class names of classes to be instantiated to read layout metadata, as used in for file-based layouts. See Layout Metadata Reader for more information. |
5.9. Policy
| Property | Value (default value) |
Description |
|---|---|---|
|
|
|
Whether objects' properties and collections can be edited directly (for objects annotated with |
|
|
|
Whether action methods need to be explicitly annotated using The default is that any non- Note that properties and collections are still implicitly inferred by virtue of being "getters". |
|
|
|
Whether objects should be filtered for visibility. See section below for further discussion. |
5.9.1. Filtering visibility
The framework provides the isis.reflector.facet.filterVisibility configuration property that influences whether a returned object is visible to the end-user:
-
Action invocations:
If an action returns a collection that includes the object, then the object will be excluded from the list when rendered. If it returns a single object and the user does not have access to that object, then the action will seemingly return
null -
Collections:
If a parent object has a collection references another object to which the user does not have access, then (as for actions) the object will not be rendered in the list
-
Properties:
If an parent object has a (scalar) reference some other object to which the user does not have access, then the reference will be rendered as empty.
-
Choices and autoComplete lists:
If an object is returned in a list of choices or within an auto-complete list, and the user does not have access, then it is excluded from the rendered list.
The original motivation for this feature was to transparently support such features as multi-tenancy (as per the (non-ASF) Incode Platform's security module). That is, if an entity is logically "owned" by a user, then the multi-tenancy support can be arranged to prevent some other user from viewing that object.
By default this configuration property is enabled. To disable the visibility filtering, set the appropriate configuration property to false:
isis.reflector.facet.filterVisibility=falseFiltering is supported by the Wicket viewer and the Restful Objects viewer, and also by the WrapperFactory domain service (provided the wrapper’s execution mode is not "skip rules").
|
In order for the framework to perform this filtering of collections, be aware that the framework takes a copy of the original collection, filters on the collection, and returns that filtered collection rather than the original. There are no major side-effects from this algorithm, other than the fact that the referenced objects will (most likely) need to be resolved in order to determine if they are visible. This could conceivably have a performance impact in some cases. |
5.9.2. objects.editing
This configuration property in effect allows editing to be disabled globally for an application:
isis.objects.editing=falseWe recommend enabling this feature; it will help drive out the underlying business operations (processes and procedures) that require objects to change; these can then be captured as business actions.