You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@isis.apache.org by da...@apache.org on 2015/05/15 15:36:48 UTC
[2/9] isis git commit: ISIS-1133: security and runtime.
ISIS-1133: security and runtime.
Project: http://git-wip-us.apache.org/repos/asf/isis/repo
Commit: http://git-wip-us.apache.org/repos/asf/isis/commit/b538e164
Tree: http://git-wip-us.apache.org/repos/asf/isis/tree/b538e164
Diff: http://git-wip-us.apache.org/repos/asf/isis/diff/b538e164
Branch: refs/heads/master
Commit: b538e1645bbffe43accd2465be431e433d632d3e
Parents: 18011b9
Author: Dan Haywood <da...@haywood-associates.co.uk>
Authored: Thu May 14 09:42:25 2015 +0100
Committer: Dan Haywood <da...@haywood-associates.co.uk>
Committed: Thu May 14 09:42:25 2015 +0100
----------------------------------------------------------------------
adocs/documentation/Gemfile | 3 +
adocs/documentation/Gemfile.lock | 5 +
adocs/documentation/monitor.rb | 2 +-
.../documentation/src/main/asciidoc/index.adoc | 2 +
...amodel-finetuning-the-programming-model.adoc | 81 ----
.../_user-guide_appendices_migration-notes.adoc | 19 +
.../_user-guide_more-advanced_i18n.adoc | 238 +++++++++++
.../_user-guide_runtime-configuration.adoc | 32 --
..._runtime-configuration_configuring-core.adoc | 90 ----
...e-configuration_configuring-datanucleus.adoc | 21 -
...s_disabling-persistence-by-reachability.adoc | 93 ----
...atanucleus_eagerly-registering-entities.adoc | 43 --
...configuring-datanucleus_persistence-xml.adoc | 9 -
...tion_configuring-datanucleus_properties.adoc | 57 ---
...ring-datanucleus_using-jndi-data-source.adoc | 72 ----
...runtime-configuration_configuring-shiro.adoc | 419 -------------------
..._user-guide_runtime-configuration_files.adoc | 87 ----
...ser-guide_runtime-configuration_web-xml.adoc | 19 -
.../user-guide/_user-guide_runtime.adoc | 27 ++
..._user-guide_runtime_configuration-files.adoc | 87 ++++
.../_user-guide_runtime_configuring-core.adoc | 88 ++++
...r-guide_runtime_configuring-datanucleus.adoc | 21 +
...s_disabling-persistence-by-reachability.adoc | 93 ++++
...atanucleus_eagerly-registering-entities.adoc | 43 ++
...configuring-datanucleus_persistence-xml.adoc | 9 +
...time_configuring-datanucleus_properties.adoc | 57 +++
...ring-datanucleus_using-jndi-data-source.adoc | 72 ++++
.../user-guide/_user-guide_runtime_web-xml.adoc | 19 +
.../user-guide/_user-guide_security.adoc | 61 +++
...ser-guide_security_api-for-applications.adoc | 61 +++
...security_configuring-isis-to-use-bypass.adoc | 13 +
..._security_configuring-isis-to-use-shiro.adoc | 75 ++++
.../_user-guide_security_shiro-caching.adoc | 40 ++
.../_user-guide_security_shiro-ini-realm.adoc | 132 ++++++
...shiro-isis-enhanced-wildcard-permission.adoc | 62 +++
...er-guide_security_shiro-isis-ldap-realm.adoc | 145 +++++++
..._shiro-isisaddons-security-module-realm.adoc | 35 ++
.../_user-guide_security_shiro-jdbc-realm.adoc | 113 +++++
.../configure-isis-to-use-bypass.PNG | Bin 0 -> 12091 bytes
.../configure-isis-to-use-shiro.png | Bin 0 -> 11356 bytes
.../configure-shiro-to-use-ini-realm.PNG | Bin 0 -> 29914 bytes
.../configure-shiro-to-use-isis-ldap-realm.PNG | Bin 0 -> 32310 bytes
...ecurity-module-realm-with-delegate-realm.PNG | Bin 0 -> 45089 bytes
...-to-use-isisaddons-security-module-realm.PNG | Bin 0 -> 38713 bytes
.../configure-shiro-to-use-shiro-jdbc-realm.png | Bin 0 -> 33149 bytes
.../security-apis-impl/security-apis-impl.pptx | Bin 0 -> 56892 bytes
.../main/asciidoc/user-guide/user-guide.adoc | 5 +-
adocs/pom.xml | 58 +++
adocs/template/document.html.erb | 5 +
49 files changed, 1587 insertions(+), 1026 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/isis/blob/b538e164/adocs/documentation/Gemfile
----------------------------------------------------------------------
diff --git a/adocs/documentation/Gemfile b/adocs/documentation/Gemfile
index 7723995..5ea2ea7 100644
--- a/adocs/documentation/Gemfile
+++ b/adocs/documentation/Gemfile
@@ -9,6 +9,9 @@ gem 'wdm', '>= 0.1.0' if Gem.win_platform?
gem 'listen', '~> 2.7' # this prevents upgrading to 3.x
gem 'asciidoctor'
+#gem 'asciidoctor-diagram', '~> 1.2.0.pre
+gem 'asciidoctor-diagram', '~> 1.2.1'
+
gem 'tilt'
gem 'thread_safe'
gem 'coderay'
http://git-wip-us.apache.org/repos/asf/isis/blob/b538e164/adocs/documentation/Gemfile.lock
----------------------------------------------------------------------
diff --git a/adocs/documentation/Gemfile.lock b/adocs/documentation/Gemfile.lock
index 7af60f8..6a495d9 100644
--- a/adocs/documentation/Gemfile.lock
+++ b/adocs/documentation/Gemfile.lock
@@ -3,6 +3,9 @@ GEM
specs:
addressable (2.3.8)
asciidoctor (1.5.2)
+ asciidoctor-diagram (1.2.1)
+ asciidoctor (~> 1.5.0)
+ rjb (~> 1.4.8)
celluloid (0.16.0)
timers (~> 4.0.0)
coderay (1.1.0)
@@ -17,6 +20,7 @@ GEM
rb-fsevent (0.9.4)
rb-inotify (0.9.5)
ffi (>= 0.5.0)
+ rjb (1.4.9)
slop (4.1.0)
thread_safe (0.3.5)
tilt (2.0.1)
@@ -30,6 +34,7 @@ PLATFORMS
DEPENDENCIES
asciidoctor
+ asciidoctor-diagram (~> 1.2.1)
coderay
launchy (~> 2.4.3)
listen (~> 2.7)
http://git-wip-us.apache.org/repos/asf/isis/blob/b538e164/adocs/documentation/monitor.rb
----------------------------------------------------------------------
diff --git a/adocs/documentation/monitor.rb b/adocs/documentation/monitor.rb
index 2fe1639..1f00861 100644
--- a/adocs/documentation/monitor.rb
+++ b/adocs/documentation/monitor.rb
@@ -80,7 +80,7 @@ def process(file,srcBasePath,targetBasePath,templateDir,i,priming)
unless regenerate == "" then
- cmd = "asciidoctor #{regenerate} --backend html --eruby erb --template-dir '#{templateDir}' --destination-dir='#{targetRelDir}' -a imagesdir='' -a toc=right -a icons=font -a source-highlighter=coderay"
+ cmd = "asciidoctor #{regenerate} --require asciidoctor-diagram --backend html --eruby erb --template-dir '#{templateDir}' --destination-dir='#{targetRelDir}' -a imagesdir='' -a toc=right -a icons=font -a source-highlighter=coderay"
unless priming then
puts ""
http://git-wip-us.apache.org/repos/asf/isis/blob/b538e164/adocs/documentation/src/main/asciidoc/index.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/index.adoc b/adocs/documentation/src/main/asciidoc/index.adoc
index aba4aa8..3b324d1 100644
--- a/adocs/documentation/src/main/asciidoc/index.adoc
+++ b/adocs/documentation/src/main/asciidoc/index.adoc
@@ -23,3 +23,5 @@ Finding your way around:
* User Guide
** link:user-guide/user-guide.html[User Guide]
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/b538e164/adocs/documentation/src/main/asciidoc/user-guide/_/metamodel-finetuning-the-programming-model.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_/metamodel-finetuning-the-programming-model.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_/metamodel-finetuning-the-programming-model.adoc
deleted file mode 100644
index b40fe1c..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_/metamodel-finetuning-the-programming-model.adoc
+++ /dev/null
@@ -1,81 +0,0 @@
-Title: Fine-tuning the Programming Model
-
-== Core MetaModel
-
-The core metamodel defines APIs and implementations for building the Isis metamodel: a description of the set of entities, domain services and values that make up the domain model.
-
-The description of each domain class consists of a number of elements:
-
-* https://github.com/apache/isis/blob/master/core/metamodel/src/main/java/org/apache/isis/core/metamodel/spec/ObjectSpecification.java[ObjectSpecification]
-
-Analogous to `java.lang.Class`; holds information about the class itself and holds collections of each of the three types of class' members (below);
-
-* https://github.com/apache/isis/blob/master/core/metamodel/src/main/java/org/apache/isis/core/metamodel/spec/feature/OneToOneAssociation.java[OneToOneAssociation]
-
-Represents a class member that is a single-valued property of the class. The property's type is either a reference to another entity, or is a value type.
-
-* https://github.com/apache/isis/blob/master/core/metamodel/src/main/java/org/apache/isis/core/metamodel/spec/feature/OneToManyAssociation.java[OneToManyAssociation]
-
-Represents a class member that is a collection of references to other entities. Note that Isis does not currently support collections of values.
-
-* https://github.com/apache/isis/blob/master/core/metamodel/src/main/java/org/apache/isis/core/metamodel/spec/feature/ObjectAction.java[ObjectAction]
-
-Represents a class member that is an operation that can be performed on the action. Returns either a single value, a collection of entities, or is `void`.
-
-The metamodel is built up through the https://github.com/apache/isis/blob/master/core/metamodel/src/main/java/org/apache/isis/core/metamodel/progmodel/ProgrammingModel.java[ProgrammingModel], which defines an API for registering a set of https://github.com/apache/isis/blob/master/core/metamodel/src/main/java/org/apache/isis/core/metamodel/facets/FacetFactory.java[FacetFactory]s. Two special `FacetFactory` implementations - https://github.com/apache/isis/blob/master/core/metamodel/src/main/java/org/apache/isis/core/metamodel/facets/properties/accessor/PropertyAccessorFacetViaAccessorFactory.java[PropertyAccessorFacetFactory] and https://github.com/apache/isis/blob/master/core/metamodel/src/main/java/org/apache/isis/core/metamodel/facets/collections/accessor/CollectionAccessorFacetViaAccessorFactory.java[CollectionAccessorFacetFactory] - are used to identify the class members. Pretty much all the other `FacetFactory`s are responsible for installing https://github.com/apache/isis/blob/
master/core/metamodel/src/main/java/org/apache/isis/core/metamodel/facetapi/Facet.java[Facet]s onto the metamodel elements. There are many many such `Facet`s, and are used to do such things get values from properties or collections, modify properties or collections, invoke action, hide or disable class members, provide UI hints for class members, and so on. In short, the `FacetFactory`s registered defines the Isis programming conventions.
-
-== Modifying the Programming Model
-
-The default implementation of `ProgrammingModel` is https://github.com/apache/isis/blob/master/core/metamodel/src/main/java/org/apache/isis/progmodels/dflt/ProgrammingModelFacetsJava5.java[ProgrammingModelFacetsJava5], which registers a large number of `FacetFactory`s.
-
-By editing `isis.properties` you can modify the programming conventions either by (a) using the default programming model, but tweaking it to include new `FacetFactory`s or exclude existing, or (b) by specifying a completely different programming model implementation.
-
-Let's see how this is done.
-
-=== Fine-tuning the existing programming model
-
-Suppose that you wanted to completely remove support for the (already deprecated) `@ActionOrder` annotation. This would be done using:
-
-[source]
-----
-isis.reflector.facets.exclude=org.apache.isis.core.metamodel.facets.object.actionorder.annotation.ActionOrderFacetAnnotationFactory
-----
-
-Or, suppose you wanted to use the example https://github.com/apache/isis/blob/master/mothballed/misc/metamodel/namefile/src/main/java/org/apache/isis/example/metamodel/namefile/facets/NameFileFacetFactory.java["namefile"] `FacetFactory` as part of your programming conventions, use:
-
-[source]
-----
-isis.reflector.facets.include=org.apache.isis.example.metamodel.namefile.facets.NameFileFacetFactory
-----
-
-To include/exclude more than one `FacetFactory`, specify as a comma-separated list. And if you want to dig into this in more detail, the code that implements this logic is https://github.com/apache/isis/blob/master/core/metamodel/src/main/java/org/apache/isis/progmodels/dflt/JavaReflectorInstallerNoDecorators.java[JavaReflectorInstallerNoDecorators].
-
-=== Example
-
-This http://isis.markmail.org/thread/472c3mrvcgnripst[thread] from the users mailing list (in Apr 2014) shows a typical customization (to enable per-instance security).
-
-== Specifying a different LayoutMetadataReader
-
-While all facets can be specified using annotations, the facets that provide hints for the user interface can also be specified from a corresponding `.layout.json` file, described in more detail link:../components/viewers/wicket/dynamic-layouts.html[here]. It is the role of a `LayoutMetadataReader` to read/parse such a file and create the appropriate facets.
-
-In the case of the `.layout.json` file, the implementation used in `LayoutMetadataReaderFromJson`. This is also the default implementation. However, an alternative implementation can be specified using:
-
-[source]
-----
-isis.reflector.layoutMetadataReaders=org.apache.isis.core.metamodel.layoutmetadata.json.LayoutMetadataReaderFromJson
-----
-
-As of 1.8.0 there is only one implementation provided, but we anticipate other implementations in future releases.
-
-== Specifying a new programming model
-
-To specify a completely new programming model, you'll first need an implementation of `ProgrammingModel`. One option is to subclass from `ProgammingModelFacetsJava5`; in your subclass you could remove any `FacetFactory`s that you wanted to exclude, as well as registering your own implementations.
-
-To tell Isis to use your new programming model, use (something like):
-
-[source]
-----
-isis.reflector.facets=com.mycompany.myapp.isis.IsisProgrammingModel
-----
-
-Again, the code that implements this logic is https://github.com/apache/isis/blob/master/core/metamodel/src/main/java/org/apache/isis/progmodels/dflt/JavaReflectorInstallerNoDecorators.java[JavaReflectorInstallerNoDecorators].
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/b538e164/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_appendices_migration-notes.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_appendices_migration-notes.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_appendices_migration-notes.adoc
index ae537a0..10aa1d2 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_appendices_migration-notes.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_appendices_migration-notes.adoc
@@ -301,3 +301,22 @@ We also recommend that you add the `maven-enforcer-plugin` (if not used already)
</executions>
</plugin>
----
+
+
+== Migrating from v1.7.0 to 1.8.0
+
+Existing projects written against v1.7.0 should run against v1.8.0 without any changes. In particular (unlike 1.6.0 and
+ 1.7.0) there should be no need to update `pom.xml` files of existing projects. If you *do* encounter any difficulties
+then let us know via the [users mailing list](../../support.html), so we can support you and document issues here.
+
+That said, many of the existing annotations have been deprecated in 1.8.0, replaced with a simplified and rationalized
+ set of annotations; see [here](../../reference/recognized-annotations/about.html). To help you migrate your application
+ over to the new annotations, there is a new configuration property that can be set in `isis.properties`:
+
+ isis.reflector.validator.allowDeprecated=false
+
+If this flag is present and set to false, then metamodel validation errors will be thrown on startup if any deprecated
+annotations are encountered. These can be viewed either in the console or by browsing to the app (an error page will
+be displayed).
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/b538e164/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_more-advanced_i18n.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_more-advanced_i18n.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_more-advanced_i18n.adoc
index 4e5aef1..02327d7 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_more-advanced_i18n.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_more-advanced_i18n.adoc
@@ -362,3 +362,241 @@ This allows a translator to edit the appropriate `translations-xx-XX.po` file an
+
+== Migrating from v1.6.0 to 1.7.0
+
+In v1.7.0 we've continued the work started in link:migrating-to-1.6.0.html[1.6.0] in modularizing the framework. The most important change to note is that all Isis core modules (with the Maven `groupId` of `org.apache.isis.module` have now MOVED to [http://www.isisaddons.org](Isis Addons).
+
+In addition, we've retired some obsolete (and unused) functionality, specifically the `ProfileStore` component.
+
+To move up amounts to changing POM files and, where required, updating package names for any referenced modules.
+
+=== Reorganized 'modules'
+
+The following modules are no longer released as part of Isis core and have moved to Isis Addons (or in one case, back into Isis core).
+
+Minor changes are required to `pom.xml` files and (in some cases) to `isis.properties` config file.
+
+In one or two exceptional cases it may be necessary to fix up import statements if there are reference to changed package/class names in code (most likely any dependency on the `devutils` module or `settings` module).
+
+==== Audit module
+
+In `pom.xml`, replace:
+
+[source,xml]
+----
+<dependency>
+ <groupId>org.apache.isis.module</groupId>
+ <artifactId>isis-module-audit-jdo</artifactId>
+</dependency>
+----
+
+with:
+
+[source,xml]
+----
+<dependency>
+ <groupId>org.isisaddons.module.audit</groupId>
+ <artifactId>isis-module-audit-dom</artifactId>
+</dependency>
+----
+
+If necessary, also update any services registered in `isis.properties` (package/class names may have changed slightly).
+
+==== Command module
+
+In `pom.xml`, replace:
+
+[source,xml]
+----
+<dependency>
+ <groupId>org.apache.isis.module</groupId>
+ <artifactId>isis-module-command-jdo</artifactId>
+</dependency>
+----
+
+with:
+
+[source,xml]
+----
+<dependency>
+ <groupId>org.isisaddons.module.command</groupId>
+ <artifactId>isis-module-command-dom</artifactId>
+</dependency>
+----
+
+If necessary, also update any services registered in `isis.properties` (package/class names may have changed slightly).
+
+==== DevUtils module
+
+In `pom.xml`, replace:
+
+[source,xml]
+----
+<dependency>
+ <groupId>org.apache.isis.module</groupId>
+ <artifactId>isis-module-devutils-applib</artifactId>
+</dependency>
+----
+
+with:
+
+[source,xml]
+----
+<dependency>
+ <groupId>org.isisaddons.module.devutils</groupId>
+ <artifactId>isis-module-devutils-dom</artifactId>
+</dependency>
+----
+
+Remove any references to:
+
+[source,xml]
+----
+<dependency>
+ <groupId>org.apache.isis.module</groupId>
+ <artifactId>isis-module-devutils</artifactId>
+</dependency>
+----
+
+or to:
+
+[source,xml]
+----
+<dependency>
+ <groupId>org.apache.isis.module</groupId>
+ <artifactId>isis-module-devutils-impl</artifactId>
+</dependency>
+----
+
+These modules are no longer required (the `org.apache.isis.module:isis-module-devutils-applib`
+and `org.apache.isis.module:isis-module-devutils-impl` submodules have been combined
+into the new `org.isisaddons.module.devutils:isis-module-devutils-dom` module).
+
+If necessary, also update any services registered in `isis.properties` (package/class names may have changed slightly).
+
+==== Publishing module
+
+In `pom.xml`, replace:
+
+[source,xml]
+----
+<dependency>
+ <groupId>org.apache.isis.module</groupId>
+ <artifactId>isis-module-publishing-jdo</artifactId>
+</dependency>
+----
+
+with:
+
+[source,xml]
+----
+<dependency>
+ <groupId>org.isisaddons.module.publishing</groupId>
+ <artifactId>isis-module-publishing-dom</artifactId>
+</dependency>
+----
+
+If necessary, also update any services registered in `isis.properties` (package/class names may have changed slightly).
+
+==== Publishing Event Serializer RO module
+
+Remove any references to:
+
+[source,xml]
+----
+<dependency>
+ <groupId>org.apache.isis.module</groupId>
+ <artifactId>isis-module-publishingeventserializer-ro</artifactId>
+</dependency>
+----
+
+This module has been merged with `org.isisaddons.module.publishing:isis-module-publishing-dom`, above.
+
+==== Settings module
+
+In `pom.xml`, replace:
+
+[source,xml]
+----
+<dependency>
+ <groupId>org.apache.isis.module</groupId>
+ <artifactId>isis-module-settings-applib</artifactId>
+</dependency>
+----
+
+with:
+
+[source,xml]
+----
+<dependency>
+ <groupId>org.isisaddons.module.settings</groupId>
+ <artifactId>isis-module-settings-dom</artifactId>
+</dependency>
+----
+
+Remove any references to:
+
+[source,xml]
+----
+<dependency>
+ <groupId>org.apache.isis.module</groupId>
+ <artifactId>isis-module-settings</artifactId>
+</dependency>
+----
+
+or to:
+
+[source,xml]
+----
+<dependency>
+ <groupId>org.apache.isis.module</groupId>
+ <artifactId>isis-module-settings-impl</artifactId>
+</dependency>
+----
+
+These modules are no longer required (the `org.apache.isis.module:isis-module-settings-applib`
+and `org.apache.isis.module:isis-module-settings-impl` submodules have been combined
+into the new `org.isisaddons.module.settings:isis-module-settings-dom` module).
+
+If necessary, also update any services registered in `isis.properties` (package/class names may have changed slightly).
+
+==== Background module
+
+In `pom.xml`, remove:
+
+[source,xml]
+----
+<dependency>
+ <groupId>org.apache.isis.module</groupId>
+ <artifactId>isis-module-background</artifactId>
+</dependency>
+----
+
+The service classes have been moved into existing `org.apache.isis.core:isis-core-runtime` Maven module (that is, already be referenced in the `pom.xml`).
+
+If necessary, also update any services registered in `isis.properties` (package/class names may have changed slightly).
+
+=== Retired `ProfileStore` component
+
+As per <a href='https://issues.apache.org/jira/browse/ISIS-802'>ISIS-802</a>, the ProfileStore component has been removed. This functionality was not surfaced or available in the Wicket or Restful Objects viewers, so there is no meaningful loss of functionality. However, Maven `pom.xml` files will require updating:
+
+Specifically, remove any dependencies on `org.apache.isis:isis-core-profilestore`:
+
+[source]
+----
+<dependency>
+ <groupId>org.apache.isis.core</groupId>
+ <artifactId>isis-core-profilestore</artifactId>
+</dependency>
+----
+
+A number of corresponding classes/interfaces have also been removed from the Isis applib:
+
+* `org.apache.isis.applib.fixtures.userprofile.UserProfileService`
+* `org.apache.isis.applib.fixtures.userprofile.UserProfileServiceAware`
+* `org.apache.isis.applib.fixtures.UserProfileFixture`
+* `org.apache.isis.applib.profiles.Profile`
+* `org.apache.isis.applib.profiles.Perspective`
+
+It is highly unlikely that any existing production code references these classes.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/b538e164/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_runtime-configuration.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_runtime-configuration.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_runtime-configuration.adoc
deleted file mode 100644
index b7a4e45..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_runtime-configuration.adoc
+++ /dev/null
@@ -1,32 +0,0 @@
-= Runtime Configuration
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-Isis' own configuration properties are simple key-value pairs, typically held in the `WEBINF/isis.properties` file and other related files. This chapter describes how to configure an Apache Isis application.
-
-[NOTE]
-====
-Configuration properties for the viewers can be found in the <<Wicket Viewer>> chapter and the <<Restful Objects Viewer>> chapter.
-====
-
-[TIP]
-====
-The configuration values are "baked" into the WAR file. Details on how to override these configuration properties externally for different environments can be found in the <<Deployment>> chapter.
-====
-
-include::_user-guide_runtime-configuration_files.adoc[leveloffset=+1]
-
-include::_user-guide_runtime-configuration_configuring-core.adoc[leveloffset=+1]
-
-include::_user-guide_runtime-configuration_web-xml.adoc[leveloffset=+1]
-
-include::_user-guide_runtime-configuration_configuring-shiro.adoc[leveloffset=+1]
-
-include::_user-guide_runtime-configuration_configuring-datanucleus.adoc[leveloffset=+1]
-
-
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/b538e164/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_runtime-configuration_configuring-core.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_runtime-configuration_configuring-core.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_runtime-configuration_configuring-core.adoc
deleted file mode 100644
index 8f16943..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_runtime-configuration_configuring-core.adoc
+++ /dev/null
@@ -1,90 +0,0 @@
-= Configuring Core
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-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, Configuring DataNucleus>> section elsewhere in this chapter.
-
-Configuration properties for the viewers can be found in the <<Wicket Viewer>> chapter and the <<Restful Objects Viewer>> chapter.
-
-IMPORTANT: WIP...
-
-.Core Configuration Properties
-[cols="2a,1,3a", options="header"]
-|===
-|Property
-|Value +
-(_default value_)
-|Description
-
-|`isis.services`
-|`FQCN`,`FQCN2`,...
-|Fully qualified class names of classes to be instantiated as domain services. Each entry can be optionally prefixed by "n:" specifying the relative order on the menu (corresponds to `@DomainServiceLayout#menuOrder()`).
-
-|`isis.services.` +
-`container.disableAutoFlush`
-| `true`,`false` (`_false_`)
-|Whether the `DomainObjectContainer` should automatically flush pending changes prior to querying (via `allMatches()`, `firstMatch()` and so on).
-
-|`isis.services.` +
-`translation.po.mode`
-| `read`,`write`
-|Whether to force the `TranslationService` into either read or write mode. +
-See <<_i18n, i18n support>> to learn more about the translation service.
-
-|`isis.persistor.` +
-`disableConcurrencyChecking`
-| `true`,`false` (`_false_`)
-| Disables concurrency checking globally. Only intended for "emergency use" as a workaround while pending fix/patch to Isis itself. (Note that there is no "datanucleus" in the property).
-
-|`isis.reflector.facet.` +
-`cssClassFa.patterns`
-|regex:fa-icon,regex2:fa-icon2,...
-|Comma separated list of key:value pairs, where the key is a regex matching action names (eg `create.*`) and the value is a link:fortawesome.github.io/Font-Awesome/icons/[font-awesome] icon name (eg `fa-plus`) to be applied (as per `@CssClassFa()`) to all action members matching the regex. +
-See <<_user-guide_how-tos_ui-hints_action-icons-and-css, UI hints>> for more details.
-
-|`isis.reflector.facet.` +
-`cssClass.patterns`
-|regex:css1,regex2:css2,...
-|Comma separated list of key:value pairs, where the key is a regex matching action names (eg `delete.*`) and the value is a link:http://getbootstrap.com/css/[Bootstrap] CSS button class (eg `btn-warning) to be applied (as per `@CssClass()`) to all action members matching the regex. +
-See <<_user-guide_how-tos_ui-hints_action-icons-and-css, UI hints>> for more details.
-
-|`isis.reflector.facets`
-|`FQCN`
-|Fully qualified class names of a custom implementation of `ProgrammingModel` interface.
-See <<_finetuning, finetuning the programming model>> for more details.
-
-|`isis.reflector.facets.` +
-`include`
-|`FQCN`,`FQCN2`,...
-|Fully qualified class names of (new, custom) facet factory classes to be included to the programming model. +
-See <<_finetuning, finetuning the programming model>> for more details.
-
-|`isis.reflector.facets.` +
-`exclude`
-|`FQCN`,`FQCN2`,...
-|Fully qualified class names of (existing, built-in) facet factory classes to be included to the programming model. +
-See <<_finetuning, finetuning the programming model>> for more details.
-
-|`isis.reflector.validator`
-|`FQCN`
-|Custom implementation of `MetaModelValidator` (in the `org.apache.isis.core.metamodel.specloader.validator` package) +
-See <<_custom_validator, Custom Validator>> to learn more.
-
-|`isis.reflector.validator.` +
-`allowDeprecated`
-| `true`,`false` (`_true_`)
-| 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).
-
-|`isis.reflector.` +
-`layoutMetadataReaders`
-|`FQCN`,`FQCN2`,...
-|Fully qualified class names of classes to be instantiated to read layout metadata, as used in for <<_dynamic_object_layout, dynamic layout>>s. +
-See <<_layout_metadata_reader, Layout Metadata Reader>> for more information.
-
-|===
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/b538e164/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_runtime-configuration_configuring-datanucleus.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_runtime-configuration_configuring-datanucleus.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_runtime-configuration_configuring-datanucleus.adoc
deleted file mode 100644
index e1ea34f..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_runtime-configuration_configuring-datanucleus.adoc
+++ /dev/null
@@ -1,21 +0,0 @@
-= Configuring DataNucleus
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-Apache Isis programmatically configures DataNucleus; any Isis properties with the prefix `isis.persistor.datanucleus.impl` are passed through directly to the JDO/DataNucleus objectstore (with the prefix stripped off, of course).
-
-DataNucleus will for itself also and read the `META-INF/persistence.xml`; at a minimum this defines the name of the "persistence unit". n theory it could also hold mappings, though in Isis we tend to use annotations instead.
-
-Furthermore, DataNucleus will search for various other XML mapping files, eg `mappings.jdo`. A full list can be found http://www.datanucleus.org/products/datanucleus/jdo/metadata.html[here]. The metadata in these XML can be used to override the annotations of annotated entities; see <<_overriding_jdo_annotations, Overriding JDO Annotatons>> for further discussion.
-
-
-include::_user-guide_runtime-configuration_configuring-datanucleus_properties.adoc[leveloffset=+1]
-
-include::_user-guide_runtime-configuration_configuring-datanucleus_persistence-xml.adoc[leveloffset=+1]
-
-include::_user-guide_runtime-configuration_configuring-datanucleus_eagerly-registering-entities.adoc[leveloffset=+1]
-
-include::_user-guide_runtime-configuration_configuring-datanucleus_disabling-persistence-by-reachability.adoc[leveloffset=+1]
-
-include::_user-guide_runtime-configuration_configuring-datanucleus_using-jndi-data-source.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/b538e164/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_runtime-configuration_configuring-datanucleus_disabling-persistence-by-reachability.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_runtime-configuration_configuring-datanucleus_disabling-persistence-by-reachability.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_runtime-configuration_configuring-datanucleus_disabling-persistence-by-reachability.adoc
deleted file mode 100644
index 5c0b109..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_runtime-configuration_configuring-datanucleus_disabling-persistence-by-reachability.adoc
+++ /dev/null
@@ -1,93 +0,0 @@
-= Disabling Persistence by Reachability
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-By default, JDO/DataNucleus supports the concept of http://www.datanucleus.org/products/datanucleus/jdo/orm/cascading.html[persistence-by-reachability]. That is, if
-a non-persistent entity is associated with an already-persistent entity, then DataNucleus will detect this and will automatically persist the associated object. Put another way: there is no need to call Isis' `DomainObjectContainer#persist(.)` or `DomainObjectContainer#persistIfNotAlready(.)` methods.
-
-However, convenient though this feature is, you may find that it causes performance issues.
-
-[WARNING]
-====
-DataNucleus' persistence-by-reachability may cause performance issues. We strongly recommend that you disable it.
-====
-
-One scenario in particular where this performance issues can arise is if your entities implement the `java.lang.Comparable` interface, and you have used Isis' link:../../../reference/Utility.html[ObjectContracts] utility. The issue here is that `ObjectContracts` implementation can cause DataNucleus to recursively rehydrate a larger number of associated entities. (More detail below).
-
-We therefore recommend that you disable persistence-by-reachability by adding the following to `persistor_datanucleus.properties`:
-
-[source,ini]
-----
-isis.persistor.datanucleus.impl.datanucleus.persistenceByReachabilityAtCommit=false
-----
-
-This change has been made to the <<_simpleapp_archetype, SimpleApp Archetype>>
-
-If you do disable this feature, then you will (of course) need to ensure that you explicitly persist all entities using the `DomainObjectContainer#persist(.)` or `DomainObjectContainer#persistIfNotAlready(.)` methods.
-
-== Explanation of the issue in more detail
-
-Consider the entities:
-
-image::{_imagesdir}reference/configuration-properties/datanucleus-objectstore/party-agreementrole-agreement.png[width="750px"]
-
-
-[TIP]
-====
-[source]
-.DSL (http://yuml.me/edit/b8681268[yuml.me/b8681268])
-----
-[Party|reference]<--->*[AgreementRole|startDate]
-[AgreementRole]*<-->[Agreement|reference]
-----
-====
-
-
-In the course of a transaction, the `Agreement` entity is loaded into memory (not necessarily modified), and then new ``AgreementRole``s are associated to it.
-
-All these entities implement `Comparable` using `ObjectContracts`, and the implementation of ``AgreementRole``'s (simplified) is:
-
-[source,java]
-----
-public class AgreementRole {
- ...
- public int compareTo(AgreementRole other) {
- return ObjectContracts.compareTo(this, other, "agreement","startDate","party");
- }
-}
-----
-
-while ``Agreement``'s is implemented as:
-
-[source,java]
-----
-public class Agreement {
- ...
- public int compareTo(Agreement other) {
- return ObjectContracts.compareTo(this, other, "reference");
- }
-}
-----
-
-and ``Party``'s is similarly implemented as:
-
-[source,java]
-----
-public class Party {
- ...
- public int compareTo(Party other) {
- return ObjectContracts.compareTo(this, other, "reference");
- }
-}
-----
-
-DataNucleus's persistence-by-reachability algorithm adds the `AgreementRole` instances into a `SortedSet`, which causes `AgreementRole#compareTo()` to fire:
-
-* the evaluation of the "agreement" property delegates back to the `Agreement`, whose own `Agreement#compareTo()` uses the scalar `reference` property. As the `Agreement` is already in-memory, this does not trigger any further database queries
-
-* the evaluation of the "startDate" property is just a scalar property of the `AgreementRole`, so will already in-memory
-
-* the evaluation of the "party" property delegates back to the `Party`, whose own `Party#compareTo()` requires the uses the scalar `reference` property. However, since the `Party` is not yet in-memory, using the `reference` property triggers a database query to "rehydrate" the `Party` instance.
-
-In other words, in figuring out whether `AgreementRole` requires the persistence-by-reachability algorithm to run, it causes the adjacent associated entity `Party` to also be retrieved.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/b538e164/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_runtime-configuration_configuring-datanucleus_eagerly-registering-entities.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_runtime-configuration_configuring-datanucleus_eagerly-registering-entities.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_runtime-configuration_configuring-datanucleus_eagerly-registering-entities.adoc
deleted file mode 100644
index 3748ac3..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_runtime-configuration_configuring-datanucleus_eagerly-registering-entities.adoc
+++ /dev/null
@@ -1,43 +0,0 @@
-= Eagerly Registering Entity Types
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-[WARNING]
-====
-From 1.6.0+ this feature may be (partly?) broken; see https://issues.apache.org/jira/browse/ISIS-847[ISIS-847].
-====
-
-Both Apache Isis and DataNucleus have their own metamodels of the domain entities. Isis builds its metamodel by walking the graph of types from the services registered using `@DomainService` or explicitly registered in `isis.properties`. The JDO objectstore then takes these types and registers them with DataNucleus.
-
-In some cases, though, not every entity type is discoverable from the API of the service actions. This is especially the case if you have lots of subtypes (where the action method specifies only the supertype). In such cases the Isis and JDO metamodels is built lazily, when an instance of that (sub)type is first encountered.
-
-Isis is quite happy for the metamodel to be lazily created, and - to be fair - DataNucleus also works well in most cases. In some cases, though, we have found that the JDBC driver (eg HSQLDB) will deadlock if DataNucleus tries to submit some DDL (for a lazily discovered type) intermingled with DML (for updating).
-
-In any case, it's probably not good practice to have DataNucleus work this way. The `RegisterEntities` service can therefore be registered in order to do the eager registration. It searches for all `@PersistenceCapable` entities under specified package(s), and registers them all.
-
-
-== Specify the Package Prefix(es)
-
-In the `persistor_datanucleus.properties`, specify the package prefix(es) of your application, to provide a hint for finding the `@PersistenceCapable` classes.
-
-The value of this property can be a comma-separated list (if there is more than one package or Maven module that holds persistable entities).
-
-
-== Integration Testing
-
-The `IsisConfigurationForJdoIntegTests`, recommended for use in <<_integration_testing, Integration Testing>> provides the `#addRegisterEntitiesPackagePrefix()` method to set up this configuration property:
-
-[source,java]
-.Integration test bootstrapping
-----
-private static class SimpleAppSystemBuilder extends IsisSystemForTest.Builder {
- ...
- private static IsisConfiguration testConfiguration() {
- final IsisConfigurationForJdoIntegTests testConfiguration = new IsisConfigurationForJdoIntegTests();
- testConfiguration.addRegisterEntitiesPackagePrefix("domainapp.dom.modules"); // <1>
- return testConfiguration;
- }
-}
-----
-<1> specify the package prefix(es) for integration testing.
http://git-wip-us.apache.org/repos/asf/isis/blob/b538e164/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_runtime-configuration_configuring-datanucleus_persistence-xml.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_runtime-configuration_configuring-datanucleus_persistence-xml.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_runtime-configuration_configuring-datanucleus_persistence-xml.adoc
deleted file mode 100644
index 7933b17..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_runtime-configuration_configuring-datanucleus_persistence-xml.adoc
+++ /dev/null
@@ -1,9 +0,0 @@
-= `persistence.xml`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-IMPORTANT: TODO
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/b538e164/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_runtime-configuration_configuring-datanucleus_properties.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_runtime-configuration_configuring-datanucleus_properties.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_runtime-configuration_configuring-datanucleus_properties.adoc
deleted file mode 100644
index a76fa6a..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_runtime-configuration_configuring-datanucleus_properties.adoc
+++ /dev/null
@@ -1,57 +0,0 @@
-= Configuration Properties
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-IMPORTANT: WIP...
-
-These configuration properties are typically stored in `WEB-INF/persistor_datanucleus.properties`. However, you can place all configuration properties into `WEB-INF/isis.properties` if you wish (the configuration properties from all config files are merged together).
-
-== Configuration Properties for Apache Isis itself
-
-
-.JDO/DataNucleus Objectstore Configuration Properties
-[cols="2a,1,3a", options="header"]
-|===
-|Property
-|Value +
-(_default value_)
-|Description
-
-|`isis.persistor.datanucleus.` +
-`RegisterEntities.packagePrefix`
-| fully qualified package names (CSV)
-| of class names; specifies the entities early rather than allow DataNucleus to find the entities lazily. Strongly recommended (subtle issues can sometimes arise if lazy discovery is used).
-Further <<_registering_entity_types, discussion below>>.
-
-|`isis.persistor.datanucleus.` +
-`PublishingService.serializedForm`
-| zipped
-|
-
-|===
-
-
-
-== Configuration Properties passed through directly to DataNucleus.
-
-.JDO/DataNucleus Objectstore Configuration Properties
-[cols="2a,1,3a", options="header"]
-|===
-|Property
-|Value +
-(_default value_)
-|Description
-
-|`isis.persistor.datanucleus.impl.*`
-|
-| Passed through directly to Datanucleus (with `isis.persistor.datanucleus.impl` prefix stripped)
-
-|`isis.persistor.datanucleus.impl.` +
-`datanucleus.persistenceByReachabilityAtCommit`
-|`false`
-|We recommend this setting is disabled. +
-Further <<_disabling_persistence_by_reachability, discussion below>>.
-
-|===
-
http://git-wip-us.apache.org/repos/asf/isis/blob/b538e164/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_runtime-configuration_configuring-datanucleus_using-jndi-data-source.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_runtime-configuration_configuring-datanucleus_using-jndi-data-source.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_runtime-configuration_configuring-datanucleus_using-jndi-data-source.adoc
deleted file mode 100644
index 9888750..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_runtime-configuration_configuring-datanucleus_using-jndi-data-source.adoc
+++ /dev/null
@@ -1,72 +0,0 @@
-= Using JNDI DataSource
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-Isis' JDO objectstore can be configured either to connect to the database using its own connection pool, or by using a container-managed datasource.
-
-
-
-== Application managed connections
-
-Using a connection pool managed directly by the application (that is, by Isis' JDO objectstore and ultimately by DataNucleus) requires a single set of configuration properties to be specified.
-
-In the `WEB-INF\persistor_datanucleus.properties` file, specify the connection driver, url, username and password.
-
-For example:
-
-[source,ini]
-----
-isis.persistor.datanucleus.impl.javax.jdo.option.ConnectionDriverName=net.sf.log4jdbc.DriverSpy
-isis.persistor.datanucleus.impl.javax.jdo.option.ConnectionURL=jdbc:log4jdbc:hsqldb:mem:test
-isis.persistor.datanucleus.impl.javax.jdo.option.ConnectionUserName=sa
-isis.persistor.datanucleus.impl.javax.jdo.option.ConnectionPassword=
-----
-
-Those configuration properties that start with the prefix `isis.persistor.datanucleus.impl.` are passed through directly to DataNucleus (with the prefix removed).
-
-
-
-== Container managed (JNDI) datasource
-
-Using a datasource managed by the servlet container requires three separate bits of configuration.
-
-Firstly, specify the name of the datasource in the `WEB-INF\persistor_datanucleus.properties` file. For example:
-
-If connection pool settings are also present in this file, they will simply be ignored. Any other configuration properties that start with the prefix `isis.persistor.datanucleus.impl.` are passed through directly to DataNucleus (with the prefix removed).
-
-Secondly, in the `WEB-INF/web.xml`, declare the resource reference:
-
-[source,xml]
-----
-<resource-ref>
- <description>db</description>
- <res-ref-name>jdbc/simpleapp</res-ref-name>
- <res-type>javax.sql.DataSource</res-type>
- <res-auth>Container</res-auth>
-</resource-ref>
-----
-
-Finally, declare the datasource as required by the servlet container. For example, if using Tomcat 7, the datasource can be specified by adding the following to `$TOMCAT_HOME/conf/context.xml`:
-
-[source,xml]
-----
-<Resource name="jdbc/simpleapp"
- auth="Container"
- type="javax.sql.DataSource"
- maxActive="100"
- maxIdle="30"
- maxWait="10000"
- username="sa"
- password="p4ssword"
- driverClassName="com.microsoft.sqlserver.jdbc.SQLServerDriver"
- url="jdbc:sqlserver://127.0.0.1:1433;instance=.;databaseName=simpleapp"/>
-----
-
-You will also need to make sure that the JDBC driver is on the servlet container's classpath. For Tomcat, this means copying the driver to `$TOMCAT_HOME/lib`.
-
-[NOTE]
-====
-According to Tomcat's documentation, it is supposedly possible to copy the `conf/context.xml` to the name of the webapp, eg `conf/mywebapp.xml`, and scope the connection to that webapp only. I was unable to get this working, however.
-====
-
http://git-wip-us.apache.org/repos/asf/isis/blob/b538e164/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_runtime-configuration_configuring-shiro.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_runtime-configuration_configuring-shiro.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_runtime-configuration_configuring-shiro.adoc
deleted file mode 100644
index cc801a1..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_runtime-configuration_configuring-shiro.adoc
+++ /dev/null
@@ -1,419 +0,0 @@
-= Configuring Shiro
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-Apache Isis' security mechanism is configurable, specifying an `Authenticator` and an `Authorizor` (non-public) APIs. The Shiro security mechanism is an integration wih Apache Shiro that implements both interfaces.
-
-[TIP]
-====
-The <<_simpleapp_archetype, SimpleApp archetype>> is pre-configured to use Apache Shiro, so much of what follows is set up already.
-====
-
-== Specifying Shiro as the security mechanism
-
-To tell Apache Isis to use Shiro, update the `WEB-INF/isis.properties` file:
-
-[source,ini]
-----
-isis.authentication=shiro
-isis.authorization=shiro
-----
-
-This installs the appropriate implementation (the `ShiroAuthenticatorOrAuthorizor` class) that use Shiro's APIs to perform authentication and authorization.
-
-
-
-
-== Bootstrapping Shiro
-
-The Shiro environment (in essence, thread-locals holding the security credentials) needs to be bootstrapped using the following settings in the `WEB-INF/web.xml` file:
-
-[source,xml]
-----
-<listener>
- <listener-class>org.apache.shiro.web.env.EnvironmentLoaderListener</listener-class>
-</listener>
-
-<filter>
- <filter-name>ShiroFilter</filter-name>
- <filter-class>org.apache.shiro.web.servlet.ShiroFilter</filter-class>
-</filter>
-
-<filter-mapping>
- <filter-name>ShiroFilter</filter-name>
- <url-pattern>/*</url-pattern>
-</filter-mapping>
-----
-
-Based on this Shiro will then read `WEB-INF/shiro.ini` file to configure its Realm definitions for authentication and authorization.
-
-
-
-
-== `WEB-INF/shiro.ini`
-
-The `shiro.ini` file (at least as configured in the <<_simpleapp_archetype, SimpleApp archetype>>) is configured to use the built-in `$iniRealm`. This is achieved by the line:
-
-[source,ini]
-----
-securityManager.realms = $iniRealm
-----
-
-The file also (by way of example) include entries to setup an ldapRealm, but this is not wired in. For more information on LDAP, see link:./using-ldap.html[here].
-
-Specifying `$iniRealm` means that the usernames/passwords, roles and permissions are read from the `shiro.ini` file itself.
-
-* the users/passwords and their roles from the `[users]` sections;
-* the roles are mapped to permissions in the `[roles]` section.
-
-
-=== Users section
-
-The `[users]` section lists users, passwords and their roles. For example:
-
-[source,ini]
-----
-sven = pass, admin_role
-dick = pass, user_role, analysis_role, self-install_role
-bob = pass, user_role, self-install_role
-----
-
-=== Roles section
-
-The `roles` section lists roles and their corresponding permissions. For example:
-
-[source,ini]
-----
-user_role = *:ToDoItems:*:*,\
- *:ToDoItem:*:*,\
- *:ToDoAppDashboard:*:*
-analysis_role = *:ToDoItemAnalysis:*:*,\
- *:ToDoItemsByCategoryViewModel:*:*,\
- *:ToDoItemsByDateRangeViewModel:*:*
-self-install_role = *:ToDoItemsFixturesService:install:*
-admin_role = *
-----
-
-=== Permissions format
-
-The permission format is configurable. The default format is:
-
-[source,ini]
-----
-packageName:className:memberName:r,w
-----
-
-where:
-
-* `memberName` is the property, collection or action name.
-* `r` indicates that the member is visible
-* `w` indicates that the member is usable (editable or invokable)
-
-and where each of the parts of the permission string can be wildcarded using `*`.
-
-Because these are wildcards, a '*' can be used at any level. Additionally, missing levels assume wildcards. Thus:
-
-[source]
-----
-com.mycompany.myapp:Customer:firstName:r,w # view or edit customer's firstName
-com.mycompany.myapp:Customer:lastName:r # view customer's lastName only
-com.mycompany.myapp:Customer:placeOrder:* # view and invoke placeOrder action
-com.mycompany.myapp:Customer:placeOrder # ditto
-com.mycompany.myapp:Customer:*:r # view all customer class members
-com.mycompany.myapp:*:*:r # view-only access for all classes in myapp package
-com.mycompany.myapp:*:*:* # view/edit for all classes in myapp package
-com.mycompany.myapp:*:* # ditto
-com.mycompany.myapp:* # ditto
-com.mycompany.myapp # ditto
-* # view/edit access to everything
-----
-
-
-
-
-==== Using the Enhanced Isis Permission Syntax
-
-Shiro also allows the conversion to be mapped to alternative `Permission` instances; Isis provides its own `IsisPermission` which provides an extended and more flexible syntax.
-
-
-Isis defines its own extended syntax for permissions, following the format:
-
-[source,ini]
-----
-([!]?)([^/]+)[/](.+)
-----
-
-where:
-
-* the optional `!` prefix indicates this permission is a vetoing permission
-* the optional `xxx/` prefix is a permission group that scopes any vetoing permissions
-* the remainder of the string is the permission (possibly wildcarded, with :rw as optional suffix)
-
-For example:
-
-[source,ini]
-----
-user_role = !reg/org.estatio.api,\
- !reg/org.estatio.webapp.services.admin,\
- reg/* ; \
-api_role = org.estatio.api ;\
-admin_role = adm/*
-----
-
-sets up:
-* the user role with access to all permissions except those in `org.estatio.api` and `org.estatio.webapp.services.admin`
-* the api_role with access to all permissions in `org.estatio.api`
-* the admin_role with access to everything.
-
-The permission group concept is required to scope the applicability of any veto permission. This is probably best explained by an example. Suppose that a user has both `admin_role` and `user_role`; we would want the `admin_role` to trump the vetos of the `user_role`, in other words to give the user access to everything. Because of the permission groups, the two "+++!reg/...+""" vetos in user_role only veto out selected permissions granted by the "+++reg/*+++" permissions, but they do not veto the permissions granted by a different scope, namely "+++adm/*+++". The net effect is what we would want: that a user with both `admin_role` and `user_role` would have access to everything, irrespective of those two veto permissions of the `user_role`.
-
-To tell Shiro to use the Isis permission format, add the following to `shiro.ini`:
-
-[source,ini]
-----
-permissionResolver = org.apache.isis.security.shiro.authorization.IsisPermissionResolver
-xxxRealm.permissionResolver = $permissionResolver
-----
-
-where `xxxRealm` is the realm to be configured.
-
-
-
-== Multiple Realms
-
-A more sophisticated approach is to use external realms. For example, to configure two text-based realms defined, `realm1` and `realm2`, we would define a `resourcePath` for each, in the form:
-
-[source,ini]
-----
-realm1.resourcePath=classpath:webapp/realm1.ini
-----
-
-that is, the `src/main/resources/webapp/realm1.ini` file in the webapp project.
-
-The security manager for the app would then be told to use these two realms:
-
-[source,ini]
-----
-securityManager.realms = $realm1,$realm2
-----
-
-The the `[users]` and `[roles]` sections of `shiro.ini` would then be unused. Instead, you'll find these sections in both `realm1.ini` and `realm2.ini` (because both are coincidentally implementations of the same `org.apache.shiro.realm.text.IniRealm` class).
-
-
-
-
-== Configuring Shiro to use LDAP
-
-Isis ships with an implementation of http://shiro.apache.org[Apache Shiro]'s `Realm` class that allows user authentication and authorization to be performed against an LDAP server.
-
-The configuration required in the `WEB-INF/shiro.ini` file is:
-
-[source,ini]
-----
-contextFactory = org.apache.isis.security.shiro.IsisLdapContextFactory
-contextFactory.url = ldap://localhost:10389
-contextFactory.systemUsername = uid=admin,ou=system # <1>
-contextFactory.systemPassword = secret
-contextFactory.authenticationMechanism = CRAM-MD5 # <2>
-contextFactory.systemAuthenticationMechanism = simple
-
-ldapRealm = org.apache.isis.security.shiro.IsisLdapRealm
-ldapRealm.contextFactory = $contextFactory
-
-ldapRealm.searchBase = ou=groups,o=mojo # <3>
-ldapRealm.groupObjectClass = groupOfUniqueNames # <4>
-ldapRealm.uniqueMemberAttribute = uniqueMember # <5>
-ldapRealm.uniqueMemberAttributeValueTemplate = uid={0}
-
-# optional mapping from physical groups to logical application roles
-ldapRealm.rolesByGroup = \ # <6>
- LDN_USERS: user_role,\
- NYK_USERS: user_role,\
- HKG_USERS: user_role,\
- GLOBAL_ADMIN: admin_role,\
- DEMOS: self-install_role
-
-ldapRealm.permissionsByRole=\ # <7>
- user_role = *:ToDoItemsJdo:*:*,\
- *:ToDoItem:*:*; \
- self-install_role = *:ToDoItemsFixturesService:install:* ; \
- admin_role = *
-
-securityManager.realms = $ldapRealm
-----
-<1> user accounts are searched using a dedicated service account
-<2> SASL (CRAM-MD5) authentication is used for this authentication
-<3> groups are searched under `ou=groups,o=mojo` (where `mojo` is the company name)
-<4> each group has an LDAP objectClass of `groupOfUniqueNames`
-<5> each group has a vector attribute of `uniqueMember`
-<6> groups looked up from LDAP can optionally be mapped to logical roles; otherwise groups are used as role names directly
-<7> roles are mapped in turn to permissions
-
-The value of `uniqueMember` is in the form `uid=xxx`, with `xxx` being the uid of the user
-* users searched under `ou=system`
-* users have, at minimum, a `uid` attribute and a password
-* the users credentials are used to verify their user/password
-
-The above configuration has been tested against http://directory.apache.org/apacheds/[ApacheDS], v1.5.7. This can be administered using http://directory.apache.org/studio/[Apache Directory Studio], v1.5.3.
-
-
-
-=== Using a shared role/perms path
-
-As an alternative to injecting the `permissionsByRole` property, the role/permission mapping can alternatively be specified by injecting a resource path:
-
-[source,ini]
-----
-ldapRealm.resourcePath=classpath:webapp/myroles.ini
-----
-
-where `myroles.ini` is in `src/main/resources/webapp`, and takes the form:
-
-[source,ini]
-----
- [roles]
- user_role = *:ToDoItemsJdo:*:*,\
- *:ToDoItem:*:*
- self-install_role = *:ToDoItemsFixturesService:install:*
- admin_role = *
-----
-
-This separation of the role/mapping can be useful if Shiro is configured to support multiple realms (eg an LdapRealm based one and also an TextRealm)
-
-
-=== Active DS LDAP Configuration
-
-The screenshot below shows the ApacheDS using Apache Directory Studio. The setup here was initially base on http://krams915.blogspot.co.uk/2011/01/ldap-apache-directory-studio-basic.html[this tutorial]. However, user accounts have been moved to a separate node.
-
-==== Configure Mojo partition and nodes under Root
-
-Create a partition in order to hold the mojo node (holding the groups)
-
-image::{_imagesdir}/configuration/configuring-shiro/ldap/activeds-ldap-mojo-partition.png[ActiveDS LDAP Users]
-
-Create the `ou=groups,o=mojo` hierarchy
-
-image::{_imagesdir}/configuration/configuring-shiro/ldap/activeds-ldap-mojo-root-dse.png[ActiveDS LDAP Users]
-
-Configure SASL authentication. This means that the checking of user/password is done implicitly by virtue of Isis connecting to LDAP using these credentials.
-
-image::{_imagesdir}/configuration/configuring-shiro/ldap/activeds-ldap-sasl-authentication.png[ActiveDS LDAP Users]
-
-In order for SASL to work, it seems to be necessary to put users under `o=system`. (This is why the setup is slightly different than the tutorial mentioned above).
-
-image::{_imagesdir}/configuration/configuring-shiro/ldap/activeds-ldap-users.png[ActiveDS LDAP Users]
-
-Configure the users into the groups.
-
-image::{_imagesdir}/configuration/configuring-shiro/ldap/activeds-ldap-groups.png[ActiveDS LDAP Users]
-
-
-== Shiro Realm Mappings
-
-When configuring role based permission mapping, there can only be one of these entries per realm:
-
-[source]
-----
-realm.groupToRolesMappings = ...
-----
-
-and
-
-[source]
-----
-realm.roleToPermissionsMappings = ...
-----
-
-This forces you to put everything on one line for each of the above.
-
-This is, unfortunately, a Shiro "feature". The only solution to this is to use "\" to separate the mappings onto separate lines in the file so that it is at least maintainable.
-
-Use this technique for both group to roles mapping and role to permission mapping. If you use the '' after the "," that separates the key:value pairs it is more readable.
-
-If you repeat the entries above then it's "last one wins".
-
-[WARNING]
-====
-Configuring a [roles] section instead doesn't work because that triggers Shiro to use the simple "INI" realm and not your defined realm.
-
-In an enterprise environment you are most likely going to use either an LDAP realm or the realm that comes with the http://github.com/isisaddons/isis-module-security}[Isis addons' security] module (non-ASF); so the "simple" realm in Shiro isn't much use beyond prototyping work).
-====
-
-
-
-== Configuring Shiro to use the Security Isis Addons
-
-The Isisaddons https://github.com/isisaddons/isis-module-security[security module] (not ASF) provides a complete
-security subdomain for users, roles, permissions; all persisted as JDO domain objects. It also includes a Shiro realm
-integration.
-
-See the module's README for details of how to configure an existing app to use this module. Or, look at the the
-Isisaddons https://github.com/isisaddons/isis-app-todoapp[todoapp example] (not ASF), which is preconfigured to use
-the security module.
-
-
-
-== Configuring Shiro for JDBC
-
-Something like the following should do:
-
-[source,ini]
-----
-builtInCacheManager = org.apache.shiro.cache.MemoryConstrainedCacheManager
-securityManager.cacheManager = $builtInCacheManager
-
-ps = org.apache.shiro.authc.credential.DefaultPasswordService
-pm = org.apache.shiro.authc.credential.PasswordMatcher
-pm.passwordService = $ps
-
-aa = org.apache.shiro.authc.credential.AllowAllCredentialsMatcher
-sm = org.apache.shiro.authc.credential.SimpleCredentialsMatcher
-
-jdbcRealm=org.apache.shiro.realm.jdbc.JdbcRealm
-jdbcRealm.authenticationQuery = SELECT password from users where username = ?
-jdbcRealm.userRolesQuery = select r.label from users_roles ur inner join roles r on ur.role_id = r.id where user_id = (select id from users where username = ?);
-jdbcRealm.permissionsQuery=select p.permission from roles_permissions rp inner join permissions p on rp.permission_id = p.id where rp.role_id = (select id from roles where label = ?);
-jdbcRealm.permissionsLookupEnabled=true
-
-ds = com.mysql.jdbc.jdbc2.optional.MysqlDataSource
-ds ...etc
-securityManager.realms = $jdbcRealm
-----
-
-However, we would recommend you consider using the http://github.com/isisaddons/isis-module-security}[Isis addons' security] module instead of a home-grown JDBC solution.
-
-
-
-== Accessing user/roles from domain objects
-
-Generally speaking your domain objects should be agnostic of the user/roles that are interacting with them; applying security permissions is the responsibility of the framework.
-
-Still, on very rare occasion you may have a need, in which case use the `DomainObjectContainer` service:
-
-[source,java]
-----
-final UserMemento user = container.getUser();
-final List<RoleMemento> roles = user.getRoles();
-for (RoleMemento role : roles) {
- String roleName = role.getName();
- ...
-}
-----
-
-Each role's `name` property encodes both the realm that provided the role, and the role identity itself.
-
-For example, in the simpleapp, if logging in as `dick` with the following entries for `realm1`:
-
-[source,ini]
-----
-dick = pass, user_role, analysis_role, self-install_role
-----
-
-then this corresponds to the roles "realm1:user_role", "realm1:self-install_role" and "realm1:analysis_role".
-
-If using the Wicket viewer, then there will also be another role which is used internally (namely "org.apache.isis.viewer.wicket.roles.USER").
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/b538e164/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_runtime-configuration_files.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_runtime-configuration_files.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_runtime-configuration_files.adoc
deleted file mode 100644
index c5ddffe..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_runtime-configuration_files.adoc
+++ /dev/null
@@ -1,87 +0,0 @@
-= Configuration Files
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-When running an 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_2, Wicket UI (viewer)>> is in use
-
-* `viewer_restfulobjects.properties` - if the <<_restful_objects_viewer, Restful Objects REST API (viewer)>> is in use
-
-* `viewer.properties` - for any shared UI configuration
-
-* `persistor_datanucleus.properties` - assuming the JDO/DataNucleus objectstore is in use
-
-* `persistor.properties` - for any other objectstore configuration. This typically is used to hold `JDBC` ``URL``s
-
-* `authentication_shiro.properties`, `authorization_shiro.properties`
-+
-assuming the Shiro Security is in use (but there are no security-related config properties currently; use shiro.ini for Shiro config)
-
-* `authentication.properties`, `authorization.properties` +
-+
-for 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.
-
-
-== Specifying other components
-
-The `isis.properties` file has three configuration properties in particular that specify the major components of Isis to use. They are:
-
-.Core Configuration Properties
-[cols="2a,1,3a", options="header"]
-|===
-|Property
-|Value +
-(_default value_)
-|Implements
-
-|`isis.persistor`
-|`_datanucleus_`
-|`org.apache.isis.core.runtime.installerregistry.installerapi.` `PersistenceMechanismInstaller`
-
-|`isis.authentication`
-|`_shiro_` +
-`bypass`
-|`org.apache.isis.core.runtime.authentication.` `AuthenticationManagerInstaller`
-
-|`isis.authorization`
-|`_shiro_` +
-`bypass`
-|`org.apache.isis.core.runtime.authorization.` `AuthorizationManagerInstaller`
-
-|===
-
-[TIP]
-====
-The values "datanucleus", "shiro" etc are actually aliases for concrete implementations listed in Isis' `installer-registry.properties` file (in `isis-core-runtime.jar`). It is -- at least in theory -- possible to specify a fully qualified class name to replace any of these components. In practice only the two security APIs are actually simple enough for this to be viable.
-====
-
-As for the viewers, these are specified indirectly by way of the filters and servlets in the `web.xml` file (discussed <<_configuring_the_webapp, below>>). However, the configuration of which viewers to initialize is declared through a context parameter:
-
-
-[source,xml]
-----
-<context-param>
- <param-name>isis.viewers</param-name>
- <param-value>wicket,restfulobjects</param-value>
-</context-param>
-----
-
-The net effect of this configuration is simply to ensure that the `viewer_wicket.properties` and/or the `viewer_restfulobjects.properties` files are read.
-
-
-
-== Deployment Types
-
-IMPORTANT: TODO
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/b538e164/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_runtime-configuration_web-xml.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_runtime-configuration_web-xml.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_runtime-configuration_web-xml.adoc
deleted file mode 100644
index 8be8f26..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_runtime-configuration_web-xml.adoc
+++ /dev/null
@@ -1,19 +0,0 @@
-= `web.xml`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-IMPORTANT: TODO
-
-
-== Init Params
-
-`<isis.viewers>`
-
-== Filters
-
-
-== Servlets
-
-
-== Running Restful Objects Viewer only
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/b538e164/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_runtime.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_runtime.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_runtime.adoc
new file mode 100644
index 0000000..8bc64e6
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_runtime.adoc
@@ -0,0 +1,27 @@
+= Runtime
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+Isis' own configuration properties are simple key-value pairs, typically held in the `WEBINF/isis.properties` file and other related files. This chapter describes how to configure an Apache Isis application.
+
+[NOTE]
+====
+Configuration properties for the viewers can be found in the <<Wicket Viewer>> chapter and the <<Restful Objects Viewer>> chapter. Likewise, details of configuring security (Apache Shiro) can be found in the <<Security>> chapter.
+
+Also, note that 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 <<Deployment>> chapter.
+====
+
+include::_user-guide_runtime_configuration-files.adoc[leveloffset=+1]
+
+include::_user-guide_runtime_configuring-core.adoc[leveloffset=+1]
+
+include::_user-guide_runtime_web-xml.adoc[leveloffset=+1]
+
+include::_user-guide_runtime_configuring-datanucleus.adoc[leveloffset=+1]
+
+
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/b538e164/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_runtime_configuration-files.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_runtime_configuration-files.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_runtime_configuration-files.adoc
new file mode 100644
index 0000000..c5ddffe
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_runtime_configuration-files.adoc
@@ -0,0 +1,87 @@
+= Configuration Files
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+When running an 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_2, Wicket UI (viewer)>> is in use
+
+* `viewer_restfulobjects.properties` - if the <<_restful_objects_viewer, Restful Objects REST API (viewer)>> is in use
+
+* `viewer.properties` - for any shared UI configuration
+
+* `persistor_datanucleus.properties` - assuming the JDO/DataNucleus objectstore is in use
+
+* `persistor.properties` - for any other objectstore configuration. This typically is used to hold `JDBC` ``URL``s
+
+* `authentication_shiro.properties`, `authorization_shiro.properties`
++
+assuming the Shiro Security is in use (but there are no security-related config properties currently; use shiro.ini for Shiro config)
+
+* `authentication.properties`, `authorization.properties` +
++
+for 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.
+
+
+== Specifying other components
+
+The `isis.properties` file has three configuration properties in particular that specify the major components of Isis to use. They are:
+
+.Core Configuration Properties
+[cols="2a,1,3a", options="header"]
+|===
+|Property
+|Value +
+(_default value_)
+|Implements
+
+|`isis.persistor`
+|`_datanucleus_`
+|`org.apache.isis.core.runtime.installerregistry.installerapi.` `PersistenceMechanismInstaller`
+
+|`isis.authentication`
+|`_shiro_` +
+`bypass`
+|`org.apache.isis.core.runtime.authentication.` `AuthenticationManagerInstaller`
+
+|`isis.authorization`
+|`_shiro_` +
+`bypass`
+|`org.apache.isis.core.runtime.authorization.` `AuthorizationManagerInstaller`
+
+|===
+
+[TIP]
+====
+The values "datanucleus", "shiro" etc are actually aliases for concrete implementations listed in Isis' `installer-registry.properties` file (in `isis-core-runtime.jar`). It is -- at least in theory -- possible to specify a fully qualified class name to replace any of these components. In practice only the two security APIs are actually simple enough for this to be viable.
+====
+
+As for the viewers, these are specified indirectly by way of the filters and servlets in the `web.xml` file (discussed <<_configuring_the_webapp, below>>). However, the configuration of which viewers to initialize is declared through a context parameter:
+
+
+[source,xml]
+----
+<context-param>
+ <param-name>isis.viewers</param-name>
+ <param-value>wicket,restfulobjects</param-value>
+</context-param>
+----
+
+The net effect of this configuration is simply to ensure that the `viewer_wicket.properties` and/or the `viewer_restfulobjects.properties` files are read.
+
+
+
+== Deployment Types
+
+IMPORTANT: TODO
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/b538e164/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_runtime_configuring-core.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_runtime_configuring-core.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_runtime_configuring-core.adoc
new file mode 100644
index 0000000..99c5618
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_runtime_configuring-core.adoc
@@ -0,0 +1,88 @@
+= Configuring Core
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+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, Configuring DataNucleus>> section elsewhere in this chapter.
+
+Configuration properties for the viewers can be found in the <<Wicket Viewer>> chapter and the <<Restful Objects Viewer>> chapter.
+
+
+.Core Configuration Properties
+[cols="2a,1,3a", options="header"]
+|===
+|Property
+|Value +
+(_default value_)
+|Description
+
+|`isis.services`
+|`FQCN`,`FQCN2`,...
+|Fully qualified class names of classes to be instantiated as domain services. Each entry can be optionally prefixed by "n:" specifying the relative order on the menu (corresponds to `@DomainServiceLayout#menuOrder()`).
+
+|`isis.services.` +
+`container.disableAutoFlush`
+| `true`,`false` (`_false_`)
+|Whether the `DomainObjectContainer` should automatically flush pending changes prior to querying (via `allMatches()`, `firstMatch()` and so on).
+
+|`isis.services.` +
+`translation.po.mode`
+| `read`,`write`
+|Whether to force the `TranslationService` into either read or write mode. +
+See <<_i18n, i18n support>> to learn more about the translation service.
+
+|`isis.persistor.` +
+`disableConcurrencyChecking`
+| `true`,`false` (`_false_`)
+| Disables concurrency checking globally. Only intended for "emergency use" as a workaround while pending fix/patch to Isis itself. (Note that there is no "datanucleus" in the property).
+
+|`isis.reflector.facet.` +
+`cssClassFa.patterns`
+|regex:fa-icon,regex2:fa-icon2,...
+|Comma separated list of key:value pairs, where the key is a regex matching action names (eg `create.*`) and the value is a link:fortawesome.github.io/Font-Awesome/icons/[font-awesome] icon name (eg `fa-plus`) to be applied (as per `@CssClassFa()`) to all action members matching the regex. +
+See <<_user-guide_how-tos_ui-hints_action-icons-and-css, UI hints>> for more details.
+
+|`isis.reflector.facet.` +
+`cssClass.patterns`
+|regex:css1,regex2:css2,...
+|Comma separated list of key:value pairs, where the key is a regex matching action names (eg `delete.*`) and the value is a link:http://getbootstrap.com/css/[Bootstrap] CSS button class (eg `btn-warning) to be applied (as per `@CssClass()`) to all action members matching the regex. +
+See <<_user-guide_how-tos_ui-hints_action-icons-and-css, UI hints>> for more details.
+
+|`isis.reflector.facets`
+|`FQCN`
+|Fully qualified class names of a custom implementation of `ProgrammingModel` interface.
+See <<_finetuning, finetuning the programming model>> for more details.
+
+|`isis.reflector.facets.` +
+`include`
+|`FQCN`,`FQCN2`,...
+|Fully qualified class names of (new, custom) facet factory classes to be included to the programming model. +
+See <<_finetuning, finetuning the programming model>> for more details.
+
+|`isis.reflector.facets.` +
+`exclude`
+|`FQCN`,`FQCN2`,...
+|Fully qualified class names of (existing, built-in) facet factory classes to be included to the programming model. +
+See <<_finetuning, finetuning the programming model>> for more details.
+
+|`isis.reflector.validator`
+|`FQCN`
+|Custom implementation of `MetaModelValidator` (in the `org.apache.isis.core.metamodel.specloader.validator` package) +
+See <<_custom_validator, Custom Validator>> to learn more.
+
+|`isis.reflector.validator.` +
+`allowDeprecated`
+| `true`,`false` (`_true_`)
+| 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).
+
+|`isis.reflector.` +
+`layoutMetadataReaders`
+|`FQCN`,`FQCN2`,...
+|Fully qualified class names of classes to be instantiated to read layout metadata, as used in for <<_dynamic_object_layout, dynamic layout>>s. +
+See <<_layout_metadata_reader, Layout Metadata Reader>> for more information.
+
+|===
+
+