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/07/09 18:29:33 UTC
[4/9] isis git commit: ISIS-1133: added blurb to user guide, ref guide,
dev guide. Moved runtime config section from ug to rg. Also...
http://git-wip-us.apache.org/repos/asf/isis/blob/7db02393/adocs/documentation/src/main/asciidoc/guides/_rg_runtime_configuring-datanucleus_using-jndi-data-source.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_runtime_configuring-datanucleus_using-jndi-data-source.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_runtime_configuring-datanucleus_using-jndi-data-source.adoc
new file mode 100644
index 0000000..1cac414
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_runtime_configuring-datanucleus_using-jndi-data-source.adoc
@@ -0,0 +1,75 @@
+[[_rg_runtime_configuring-datanucleus_using-jndi-data-source]]
+= 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
+
+Using a connection pool managed directly by the application (that is, by Apache 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)
+
+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/7db02393/adocs/documentation/src/main/asciidoc/guides/_rg_runtime_deployment-types.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_runtime_deployment-types.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_runtime_deployment-types.adoc
new file mode 100644
index 0000000..04c1363
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_runtime_deployment-types.adoc
@@ -0,0 +1,111 @@
+[[_rg_runtime_deployment-types]]
+= Deployment 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/
+
+
+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 xref:rg.adoc#_rg_annotations_manpage-Action_restrictTo[`@Action#restrictTo()`]) will be available.
+
+
+
+== Using the Wicket Viewer
+
+Most of the you're likely to run Apache Isis using the xref:ug.adoc#_ug_wicket-viewer[Wicket viewer]. In this case Apache Isis' "deployment type" concept maps to Wicket's "configuration" concept:
+
+.Apache Isis' deployment type corresponds to Apache Wicket's configuration
+[cols="1,1,2", options="header"]
+|===
+| Apache Isis +
+(Deployment Type)
+| Apache Wicket +
+(Configuration)
+| Notes
+
+| `SERVER_PROTOTYPE`
+| `development`
+| running in development/prototyping mode
+
+| `SERVER`
+| `deployment`
+| 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: +
++
+[source,xml]
+.`web.xml`
+----
+<context-param>
+ <param-name>configuration</param-name>
+ <param-value>deployment</param-value>
+</context-param>
+----
+
+* to specify `SERVER_PROTOTYPING` (development) mode, use: +
++
+[source,xml]
+.`web.xml`
+----
+<context-param>
+ <param-name>configuration</param-name>
+ <param-value>deployment</param-value>
+</context-param>
+----
+
+
+== Restful Objects viewer only
+
+Most Apache Isis applications will consist of at least the xref:ug.adoc#_ug_wicket-viewer[Wicket viewer] and optionally the xref:ug.adoc#_ug_restfulobjects-viewer[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' xref:rg.adoc#_rg_runtime_web-xml_servlet-context-listener[ `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: +
++
+[source,xml]
+.`web.xml`
+----
+<context-param>
+ <param-name>isis.deploymentType</param-name>
+ <param-value>server</param-value>
+</context-param>
+----
+
+* to specify `SERVER_PROTOTYPE` (development) mode, use: +
++
+[source,xml]
+.`web.xml`
+----
+<context-param>
+ <param-name>isis.deploymentType</param-name>
+ <param-value>server-prototype</param-value>
+</context-param>
+----
+
+
+
+== Overriding the deployment type
+
+If bootstrapping the application using Apache Isis' xref:ug.adoc#_ug_deployment_cmd-line[`org.apache.isis.WebServer`] then it is possible to override the deployment type using the `-t` (or `--type`) flag.
+
+For example:
+
+[source,bash]
+----
+java -jar ... org.apache.isis.WebServer -t SERVER
+----
+
+where "..." is the (usually rather long) list of JAR files and class directories that will make up your application.
+
+This works for both the xref:ug.adoc#_ug_wicket-viewer[Wicket viewer] and the xref:ug.adoc#_ug_restfulobjects-viewer[RestfulObjects viewer].
+
http://git-wip-us.apache.org/repos/asf/isis/blob/7db02393/adocs/documentation/src/main/asciidoc/guides/_rg_runtime_specifying-components.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_runtime_specifying-components.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_runtime_specifying-components.adoc
new file mode 100644
index 0000000..0c40fa4
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_runtime_specifying-components.adoc
@@ -0,0 +1,72 @@
+[[_rg_runtime_configuring-components]]
+= Specifying components
+: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/
+
+
+
+The `isis.properties` file has four configuration properties in particular that specify the major components of Apache Isis to use.
+
+They are:
+
+.Core Configuration Properties
+[cols="2a,1,3a", options="header"]
+|===
+|Property
+|Value +
+(_default value_)
+|Implements
+
+|`isis.authentication`
+|`shiro`, `bypass`, `FQCN` +
+(`_shiro_`)
+|`o.a.i.core.runtime.authentication.` `AuthenticationManagerInstaller`
+
+|`isis.authorization`
+|`shiro`, `bypass`, `FQCN` +
+(`_shiro_`)
+|`o.a.i.core.runtime.authorization.` `AuthorizationManagerInstaller`
+
+|`isis.persistor`
+|`datanucleus`, `inmemory`, `FQCN` +
+(`_datanucleus_`)
+|`o.a.i.core.runtime.installerregistry.installerapi.` `PersistenceMechanismInstaller`
+
+|`isis.services-installer`
+|`configuration`, `configuration-and-annotation`, `FQCN` +
+(`_configuration_`)
+|`org.apache.isis.core.runtime.services.` `ServicesInstaller` +
+
+The mechanism to discover and load domain services:
+
+* `configuration-and-annotation` will search for `@DomainService`-annotated classes and also read from `isis.services` configuration property
+
+* `configuration` will only read from the `isis.services` configuration property. +
+
+* Otherwise an alternative implementation of the `o.a.i.core.runtime.services.ServicesInstaller` internal API can be provided.
+
+
+
+|===
+
+[TIP]
+====
+The values "datanucleus", "shiro" etc are actually aliases for concrete implementations listed in Apache 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. This is probably feasible for the two security APIs and the `services-installer` API; but replacing the persistor (JDO/DataNucleus) is much trickier because we rely on the JDO/DN for certain functionality (such as object dirtying and lazy loading) that is not defined within this API.
+
+As for the viewers, these are specified indirectly by way of the filters and servlets in the `web.xml` file (discussed xref:rg.adoc#_rg_runtime_web-xml[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.
+
http://git-wip-us.apache.org/repos/asf/isis/blob/7db02393/adocs/documentation/src/main/asciidoc/guides/_rg_runtime_web-xml.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_runtime_web-xml.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_runtime_web-xml.adoc
new file mode 100644
index 0000000..72204d5
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_runtime_web-xml.adoc
@@ -0,0 +1,43 @@
+[[_rg_runtime_web-xml]]
+= `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/
+
+
+
+NOTE: TODO
+
+
+== Init Params
+
+`<isis.viewers>`
+
+
+
+[[_rg_runtime_web-xml_servlet-context-listener]]
+== Servlet Context Listener
+
+NOTE: TODO
+
+`IsisWebAppBootstrapper`
+
+
+
+== Filters
+
+NOTE: TODO
+
+
+
+
+== Servlets
+
+NOTE: TODO
+
+
+
+
+== Running RO Viewer only
+
+NOTE: TODO
http://git-wip-us.apache.org/repos/asf/isis/blob/7db02393/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-ClockService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-ClockService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-ClockService.adoc
index 21f1c86..2e8b4d8 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-ClockService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-ClockService.adoc
@@ -49,8 +49,8 @@ The default `ClockService` implementation in fact simply delegates to another cl
* there are two subclasses implementations `Clock`, namely `SystemClock` and `FixtureClock`.
* the first implementation that is instantiated registers itself as the singleton.
-* if running in xref:ug.adoc#_ug_runtime_deployment-types[production] (server) mode, then (unless another implementation has beaten it to the punch) the framework will instantiate the ``SystemClock`. Once instantiated this cannot be replaced.
-* if running in xref:ug.adoc#_ug_runtime_deployment-types[prototype] mode, then the framework will instead instantiate `FixtureClock`. This _can_ be replaced if required.
+* if running in xref:rg.adoc#_rg_runtime_deployment-types[production] (server) mode, then (unless another implementation has beaten it to the punch) the framework will instantiate the ``SystemClock`. Once instantiated this cannot be replaced.
+* if running in xref:rg.adoc#_rg_runtime_deployment-types[prototype] mode, then the framework will instead instantiate `FixtureClock`. This _can_ be replaced if required.
The `FixtureClock` will behave as the system clock, unless its is explicitly set using `FixtureClock#setDate(...)` or `FixtureClock#setTime(...)` and so forth.
http://git-wip-us.apache.org/repos/asf/isis/blob/7db02393/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-CommandContext.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-CommandContext.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-CommandContext.adoc
index a97d19b..a382b34 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-CommandContext.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-CommandContext.adoc
@@ -122,7 +122,7 @@ public class ToDoItem ... {
====
As an alternative to annotating every action with `@Action#command()`, alternatively this can be configured as the default using `isis.services.command.actions` configuration property.
-See xref:rg.adoc#_rg_annotations_manpage-Action_command[`@Action#command()`] and xref:ug.adoc#_ug_runtime_configuring-core[runtime configuration] for further details.
+See xref:rg.adoc#_rg_annotations_manpage-Action_command[`@Action#command()`] and xref:rg.adoc#_rg_runtime_configuring-core[runtime configuration] for further details.
====
http://git-wip-us.apache.org/repos/asf/isis/blob/7db02393/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-DomainObjectContainer_object-persistence-api.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-DomainObjectContainer_object-persistence-api.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-DomainObjectContainer_object-persistence-api.adoc
index fb89e51..4772ef4 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-DomainObjectContainer_object-persistence-api.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-DomainObjectContainer_object-persistence-api.adoc
@@ -56,7 +56,7 @@ container.persistIfNotAlready(cust);
You should be aware that by default Apache Isis queues up calls to `#persist()` and `#remove()`. These are then executed either when the request completes (and the transaction commits), or if the queue is flushed. This can be done either implicitly by the framework, or as the result of a direct call to `#flush()`.
-By default the framework itself will cause `#flush()` to be called whenever a query is executed by way of `#allMatches(Query)`, as documented xref:rg.adoc#_rg_services-api_manpage-DomainObjectContainer_generic-repository-api[above]. However, this behaviour can be disabled using the xref:ug.adoc#_ug_runtime_configuring-core[configuration property] `isis.services.container.disableAutoFlush`.
+By default the framework itself will cause `#flush()` to be called whenever a query is executed by way of `#allMatches(Query)`, as documented xref:rg.adoc#_rg_services-api_manpage-DomainObjectContainer_generic-repository-api[above]. However, this behaviour can be disabled using the xref:rg.adoc#_rg_runtime_configuring-core[configuration property] `isis.services.container.disableAutoFlush`.
http://git-wip-us.apache.org/repos/asf/isis/blob/7db02393/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-DomainObjectContainer_properties-api.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-DomainObjectContainer_properties-api.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-DomainObjectContainer_properties-api.adoc
index 43b95d9..fb70834 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-DomainObjectContainer_properties-api.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-DomainObjectContainer_properties-api.adoc
@@ -9,7 +9,7 @@
= Properties API
-The properties API allows domain objects to read the configuration properties aggregated from the various xref:ug.adoc#_ug_runtime_configuration-files[configuration files].
+The properties API allows domain objects to read the configuration properties aggregated from the various xref:rg.adoc#_rg_runtime_configuration-files[configuration files].
[source,java]
----
http://git-wip-us.apache.org/repos/asf/isis/blob/7db02393/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-EmailService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-EmailService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-EmailService.adoc
index fd16f10..99f6ac3 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-EmailService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-EmailService.adoc
@@ -45,7 +45,7 @@ To use this service the following properties must be configured:
* `isis.service.email.sender.address`
* `isis.service.email.sender.password`
-and these properties may optionally be configured (each has a default to use gmail, documented xref:ug.adoc#_ug_runtime_configuring-core[here]):
+and these properties may optionally be configured (each has a default to use gmail, documented xref:rg.adoc#_rg_runtime_configuring-core[here]):
* `isis.service.email.sender.hostname`
* `isis.service.email.port`
http://git-wip-us.apache.org/repos/asf/isis/blob/7db02393/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-EventBusService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-EventBusService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-EventBusService.adoc
index 181580e..bad2527 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-EventBusService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-EventBusService.adoc
@@ -323,7 +323,7 @@ If you do provide your own implementation of this SPI, be aware that your subscr
The implementation of `EventBusService` provided by Apache Isis will by default use link:https://code.google.com/p/guava-libraries/[Guava]'s https://code.google.com/p/guava-libraries/wiki/EventBusExplained[`EventBus`] as the underlying in-memory event bus. Alternatively the link:http://www.axonframework.org/[AxonFramework]'s link:http://www.axonframework.org/docs/2.4/single.html#d5e1489[SimpleEventBus] can be used.
-To specify which, add the xref:ug.adoc#_ug_runtime_configuring-core[configuration property] `isis.services.eventbus.implementation`:
+To specify which, add the xref:rg.adoc#_rg_runtime_configuring-core[configuration property] `isis.services.eventbus.implementation`:
[source,ini]
----
http://git-wip-us.apache.org/repos/asf/isis/blob/7db02393/adocs/documentation/src/main/asciidoc/guides/_rg_services-spi_manpage-ContentNegotiationService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_services-spi_manpage-ContentNegotiationService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_services-spi_manpage-ContentNegotiationService.adoc
index b152af2..0adf8e0 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_services-spi_manpage-ContentNegotiationService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_services-spi_manpage-ContentNegotiationService.adoc
@@ -171,14 +171,14 @@ image::{_imagesdir}reference-services-spi/ContentNegotiationService/accept-json.
[_rg_services-spi_manpage-ContentNegotiationService_Configuration]]
== Configuration
-The default `ContentNegotiationServiceXRoDomainType` implementation provides a xref:ug.adoc#_ug_runtime_configuring-core[configuration property] which controls whether a mapped domain object is pretty-printed (formatted, indented) or not:
+The default `ContentNegotiationServiceXRoDomainType` implementation provides a xref:rg.adoc#_rg_runtime_configuring-core[configuration property] which controls whether a mapped domain object is pretty-printed (formatted, indented) or not:
[source,ini]
----
isis.services.ContentNegotiationServiceXRoDomainType.prettyPrint=true
----
-If the property is not set, then the default depends on the xref:ug.adoc#_ug_runtime_deployment-types[deployment type]; production mode will disable pretty printing, while prototyping mode will enable it.
+If the property is not set, then the default depends on the xref:rg.adoc#_rg_runtime_deployment-types[deployment type]; production mode will disable pretty printing, while prototyping mode will enable it.
http://git-wip-us.apache.org/repos/asf/isis/blob/7db02393/adocs/documentation/src/main/asciidoc/guides/_rg_services-spi_manpage-ExceptionRecognizer.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_services-spi_manpage-ExceptionRecognizer.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_services-spi_manpage-ExceptionRecognizer.adoc
index 04fbd03..7fbf4ab 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_services-spi_manpage-ExceptionRecognizer.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_services-spi_manpage-ExceptionRecognizer.adoc
@@ -121,5 +121,5 @@ Prior to 1.9.0, the `ExceptionRecognizerCompositeForJdoObjectStore` also require
====
-If the JDO exception recognizers are not required (rather unlikely), then they can be disabled en-masse using the xref:ug.adoc#_ug_runtime_configuring-core[configuration property] `isis.services.ExceptionRecognizerCompositeForJdoObjectStore.disable`.
+If the JDO exception recognizers are not required (rather unlikely), then they can be disabled en-masse using the xref:rg.adoc#_rg_runtime_configuring-core[configuration property] `isis.services.ExceptionRecognizerCompositeForJdoObjectStore.disable`.
http://git-wip-us.apache.org/repos/asf/isis/blob/7db02393/adocs/documentation/src/main/asciidoc/guides/_rg_services-spi_manpage-UserRegistrationService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_services-spi_manpage-UserRegistrationService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_services-spi_manpage-UserRegistrationService.adoc
index 3cb9cec..7c43f8f 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_services-spi_manpage-UserRegistrationService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_services-spi_manpage-UserRegistrationService.adoc
@@ -78,4 +78,4 @@ The most common use case is to allow users to sign-up through Apache Isis' Wicke
* xref:rg.adoc#_rg_services-spi_manpage-EmailNotificationService[`EmailNotificationService`]
* `UserRegistrationService` (this service)
-The `EmailService` in particular requires additional xref:ug.adoc#_ug_runtime_configuring-core[configuration properties] to specify the external SMTP service.
\ No newline at end of file
+The `EmailService` in particular requires additional xref:rg.adoc#_rg_runtime_configuring-core[configuration properties] to specify the external SMTP service.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/7db02393/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_philosophy_domain-driven-design.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_philosophy_domain-driven-design.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_philosophy_domain-driven-design.adoc
index 764df57..e132bac 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_philosophy_domain-driven-design.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_philosophy_domain-driven-design.adoc
@@ -4,8 +4,6 @@
:_basedir: ../
:_imagesdir: images/
-This section describes some of the core ideas and architectural patterns upon which Apache Isis builds.
-
There's no doubt that we developers love the challenge of understanding and deploying complex technologies. But understanding the nuances and subtleties of the business domain itself is just as great a challenge, perhaps more so. If we devoted our efforts to understanding and addressing those subtleties, we could build better, cleaner, and more maintainable software that did a better job for our stakeholders. And there's no doubt that our stakeholders would thank us for it.
A couple of years back Eric Evans wrote his book link:http://www.amazon.co.uk/Domain-driven-Design-Tackling-Complexity-Software/dp/0321125215[Domain-Driven Design], which is well on its way to becoming a seminal work. In fact, most if not all of the ideas in Evans' book have been expressed before, but what he did was pull those ideas together to show how predominantly object-oriented techniques can be used to develop rich, deep, insightful, and ultimately useful business applications.
http://git-wip-us.apache.org/repos/asf/isis/blob/7db02393/adocs/documentation/src/main/asciidoc/guides/_ug_deployment_cmd-line.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_deployment_cmd-line.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_deployment_cmd-line.adoc
index 07db1d8..e63ae70 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_deployment_cmd-line.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_deployment_cmd-line.adoc
@@ -7,19 +7,119 @@
NOTE: TODO
-## `WebServer` class
+== `WebServer` class
-`org.apache.isis.WebServer`
+The `org.apache.isis.WebServer` utility class provides a `main(String[])` method so that an Apache Isis application can be run from within the IDE or command line, without the need to package the app as a WAR file and deploying to a servlet container. Internally the class it uses jetty to programmatically bootstrap the app.
-For example:
-* `--fixture`
-* `--services`
+The utility class also supports a number of command line arguments:
-etc...
+.Command line args for `org.apache.isis.Webserver`
+[cols="1,1,1,2", options="header"]
+|===
+| Flag
+| Long format
+| Values (default)
+| Description
+
+|-t
+|--type
+|`server_prototype`,`server` +
+(`server`)
+|Deployment type
+
+|-f
+|--fixture
+|
+|
+
+|-u
+|--user
+|
+|
+
+|-p
+|--password
+|
+|
+
+|-D
+|
+|
+|Additional property, in form `-Dxxx=yyy`
+
+|-h
+|--help
+|
+|
+
+
+|===
+
+
+
+The utility class also supports a number of other flags, but their usage is extremely rare (and some may be removed in the future):
+
+.Command line args for `org.apache.isis.Webserver`
+[cols="1,1,1,2", options="header"]
+|===
+| Flag
+| Long format
+| Values (default)
+| Description
+
+
+|-l
+|--reflector
+|FQCN
+|Implementing `ObjectReflectorInstaller`
+
+|-r
+|--persistor
+|FQCN
+|implementing `PersistenceMechanismInstaller`
+
+|-c
+|--config
+|
+|
+
+|-s
+|--nosplash
+|
+|
+
+|
+|--diagnostics
+|
+|
+
+|
+|--version
+|
+|
+
+
+|
+|--debug
+|
+|
+
+|
+|--verbose
+|
+|
+
+|
+|--quiet
+|
+|
+
+
+|===
-## `Dummy` class
+== `Dummy` class
`org.apache.isis.Dummy`
http://git-wip-us.apache.org/repos/asf/isis/blob/7db02393/adocs/documentation/src/main/asciidoc/guides/_ug_deployment_externalized-configuration.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_deployment_externalized-configuration.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_deployment_externalized-configuration.adoc
index 551e765..8323391 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_deployment_externalized-configuration.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_deployment_externalized-configuration.adoc
@@ -6,7 +6,7 @@
-As described xref:ug.adoc#_ug_runtime_configuration-files[here], by default Apache Isis itself bootstraps from the `isis.properties` configuration file. It will also read configuration from the (optional) component/implementation-specific configuration files (such as
+As described xref:rg.adoc#_rg_runtime_configuration-files[here], by default Apache Isis itself bootstraps from the `isis.properties` configuration file. It will also read configuration from the (optional) component/implementation-specific configuration files (such as
`persistor_datanucleus.properties` or `viewer_wicket.properties`), and also (optional) component-specific configuration
files (such as `persistor.properties` or `viewer.properties`).
http://git-wip-us.apache.org/repos/asf/isis/blob/7db02393/adocs/documentation/src/main/asciidoc/guides/_ug_deployment_tomcat.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_deployment_tomcat.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_deployment_tomcat.adoc
index 2841921..1728cfe 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_deployment_tomcat.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_deployment_tomcat.adoc
@@ -31,4 +31,4 @@ You can hint the JVM to unload dynamically created classes which ClassLoaders ar
== Using a JNDI Datasource
-See the guidance in the xref:ug.adoc#_ug_runtime_configuring-datanucleus_using-jndi-data-source[configuring datanucleus] section.
\ No newline at end of file
+See the guidance in the xref:rg.adoc#_rg_runtime_configuring-datanucleus_using-jndi-data-source[configuring datanucleus] section.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/7db02393/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_ui-hints_action-icons-and-css.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_ui-hints_action-icons-and-css.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_ui-hints_action-icons-and-css.adoc
index 82474dc..ca7a0b1 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_ui-hints_action-icons-and-css.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_ui-hints_action-icons-and-css.adoc
@@ -21,7 +21,7 @@ Alternatively, you can specify these hints dynamically in the xref:rg.adoc#_rg_o
Rather than annotating every action with xref:rg.adoc#_rg_annotations_manpage-ActionLayout_cssClassFa[`@ActionLayout#cssClassFa()`] and xref:rg.adoc#_rg_annotations_manpage-ActionLayout_cssClass[`@ActionLayout#cssClass()`] you can instead specify the UI hint globally using regular expressions.
-The xref:ug.adoc#_ug_runtime_configuring-core[configuration property] `isis.reflector.facet.cssClassFa.patterns` is a comma separated list of key:value pairs, eg:
+The xref:rg.adoc#_rg_runtime_configuring-core[configuration property] `isis.reflector.facet.cssClassFa.patterns` is a comma separated list of key:value pairs, eg:
[source,ini]
----
@@ -40,7 +40,7 @@ isis.reflector.facet.cssClassFa.patterns=\
where the key is a regex matching action names (eg `create.*`) and the value is a link:http://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.
-Similarly, the xref:ug.adoc#_ug_runtime_configuring-core[configuration property] `isis.reflector.facet.cssClass.patterns` is a comma separated list of key:value pairs, eg:
+Similarly, the xref:rg.adoc#_rg_runtime_configuring-core[configuration property] `isis.reflector.facet.cssClass.patterns` is a comma separated list of key:value pairs, eg:
[source,ini]
----
http://git-wip-us.apache.org/repos/asf/isis/blob/7db02393/adocs/documentation/src/main/asciidoc/guides/_ug_more-advanced_decoupling_db-schemas.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_more-advanced_decoupling_db-schemas.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_more-advanced_decoupling_db-schemas.adoc
index 6e91b1c..ccaab99 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_more-advanced_decoupling_db-schemas.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_more-advanced_decoupling_db-schemas.adoc
@@ -49,7 +49,7 @@ CREATE TABLE isisaudit."AuditEntry" (
[TIP]
====
-If for some reason you don't want to use schemas (though we strongly recommend that you do), then note that you can override the `@PersistenceCapable` annotation by providing XML metadata (the `mappings.jdo` file); see the section on xref:ug.adoc#_ug_runtime_configuring-datanucleus[configuring DataNucleus Overriding Annotations] for more details.
+If for some reason you don't want to use schemas (though we strongly recommend that you do), then note that you can override the `@PersistenceCapable` annotation by providing XML metadata (the `mappings.jdo` file); see the section on xref:rg.adoc#_rg_runtime_configuring-datanucleus[configuring DataNucleus Overriding Annotations] for more details.
====
http://git-wip-us.apache.org/repos/asf/isis/blob/7db02393/adocs/documentation/src/main/asciidoc/guides/_ug_more-advanced_i18n.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_more-advanced_i18n.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_more-advanced_i18n.adoc
index ab9cecc..66c08c3 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_more-advanced_i18n.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_more-advanced_i18n.adoc
@@ -90,8 +90,8 @@ If however the service is configured to run in write mode, then it instead recor
To make the service as convenient as possible to use, the service configures itself as follows:
-* if running in prototype mode xref:ug.adoc#_ug_runtime_deployment-types[deployment type] or during integration tests, then the service runs in *write* mode, in which case it records all translations into the `.pot` file. The `.pot` file is written out when the system is shutdown.
-* if running in server (production) mode xref:ug.adoc#_ug_runtime_deployment-types[deployment type], then the service runs in *read* mode. It is also possible to set a configuration setting in `isis.properties` to force read mode even if running in prototype mode (useful to manually test/demo the translations).
+* if running in prototype mode xref:rg.adoc#_rg_runtime_deployment-types[deployment type] or during integration tests, then the service runs in *write* mode, in which case it records all translations into the `.pot` file. The `.pot` file is written out when the system is shutdown.
+* if running in server (production) mode xref:rg.adoc#_rg_runtime_deployment-types[deployment type], then the service runs in *read* mode. It is also possible to set a configuration setting in `isis.properties` to force read mode even if running in prototype mode (useful to manually test/demo the translations).
When running in write mode the original text is returned to the caller untranslated. If in read mode, then the translated `.po` files are read and translations provided as required.
http://git-wip-us.apache.org/repos/asf/isis/blob/7db02393/adocs/documentation/src/main/asciidoc/guides/_ug_restfulobjects-viewer_features.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_restfulobjects-viewer_features.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_restfulobjects-viewer_features.adoc
index 9ad39e2..1da655b 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_restfulobjects-viewer_features.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_restfulobjects-viewer_features.adoc
@@ -16,7 +16,7 @@ The Restful Objects spec can be downloaded link:http://restfulobjects.org[here].
== Pretty printing
-The JSON representations generated by the Restful Objects viewer are in compact form if the xref:ug.adoc#_ug_runtime_deployment-types[deployment type] is SERVER (ie production), but will automatically be "pretty printed" (in other words indented) if the deployment type is PROTOTYPE.
+The JSON representations generated by the Restful Objects viewer are in compact form if the xref:rg.adoc#_rg_runtime_deployment-types[deployment type] is SERVER (ie production), but will automatically be "pretty printed" (in other words indented) if the deployment type is PROTOTYPE.
http://git-wip-us.apache.org/repos/asf/isis/blob/7db02393/adocs/documentation/src/main/asciidoc/guides/_ug_runtime.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_runtime.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_runtime.adoc
deleted file mode 100644
index eeef111..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_runtime.adoc
+++ /dev/null
@@ -1,29 +0,0 @@
-[[_ug_runtime]]
-= 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 xref:ug.adoc#_ug_wicket-viewer[Wicket Viewer] chapter and the xref:ug.adoc#_ug_restfulobjects-viewer[RestfulObjects viewer] chapter. Likewise[details of configuring security (Apache Shiro) can be found in the xref:ug.adoc#_ug_security[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 xref:ug.adoc#_ug_deployment[Deployment] chapter.
-====
-
-
-include::_ug_runtime_deployment-types.adoc[leveloffset=+1]
-include::_ug_runtime_configuration-files.adoc[leveloffset=+1]
-include::_ug_runtime_specifying-components.adoc[leveloffset=+1]
-include::_ug_runtime_configuring-core.adoc[leveloffset=+1]
-include::_ug_runtime_configuring-datanucleus.adoc[leveloffset=+1]
-include::_ug_runtime_web-xml.adoc[leveloffset=+1]
-include::_ug_runtime_application-specific.adoc[leveloffset=+1]
-
-
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/7db02393/adocs/documentation/src/main/asciidoc/guides/_ug_runtime_application-specific.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_runtime_application-specific.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_runtime_application-specific.adoc
deleted file mode 100644
index b8396b7..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_runtime_application-specific.adoc
+++ /dev/null
@@ -1,13 +0,0 @@
-[[_ug_runtime_application-specific]]
-= Application-specific CSS and JS
-: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/
-
-NOTE: TODO
-
-
-include::_ug_runtime_application-specific_application-css.adoc[leveloffset=+1]
-include::_ug_runtime_application-specific_application-js.adoc[leveloffset=+1]
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/7db02393/adocs/documentation/src/main/asciidoc/guides/_ug_runtime_application-specific_application-css.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_runtime_application-specific_application-css.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_runtime_application-specific_application-css.adoc
deleted file mode 100644
index 75cbaf9..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_runtime_application-specific_application-css.adoc
+++ /dev/null
@@ -1,8 +0,0 @@
-[[_ug_runtime_application-specific_application-css]]
-= `application.css`
-: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/
-
-NOTE: TODO - `WEB-INF/css/application.css`
-
http://git-wip-us.apache.org/repos/asf/isis/blob/7db02393/adocs/documentation/src/main/asciidoc/guides/_ug_runtime_application-specific_application-js.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_runtime_application-specific_application-js.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_runtime_application-specific_application-js.adoc
deleted file mode 100644
index 6f00726..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_runtime_application-specific_application-js.adoc
+++ /dev/null
@@ -1,9 +0,0 @@
-[[_ug_runtime_application-specific_application-js]]
-= `application.js`
-: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/
-
-
-
-NOTE: TODO - `WEB-INF/scripts/application.js`
http://git-wip-us.apache.org/repos/asf/isis/blob/7db02393/adocs/documentation/src/main/asciidoc/guides/_ug_runtime_configuration-files.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_runtime_configuration-files.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_runtime_configuration-files.adoc
deleted file mode 100644
index 58da346..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_runtime_configuration-files.adoc
+++ /dev/null
@@ -1,40 +0,0 @@
-[[_ug_runtime_configuration-files]]
-= 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 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 xref:ug.adoc#_ug_wicket-viewer[Wicket UI (viewer)] is in use
-
-* `viewer_restfulobjects.properties` - if the xref:ug.adoc#_ug_restfulobjects-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, which is arguably a slight violation of the file (because there's nothing in Apache Isis to say that persistors have to use `JDBC`. However, it is generally convenient to put these `JDBC` settings into a single location. If you want, they could reside inin any of `persistor_datanucleus.properties`, `persistor.properties` or (even) `isis.properties`
-
-* `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.
-
-
-
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/7db02393/adocs/documentation/src/main/asciidoc/guides/_ug_runtime_configuring-core.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_runtime_configuring-core.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_runtime_configuring-core.adoc
deleted file mode 100644
index 6dcbf88..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_runtime_configuring-core.adoc
+++ /dev/null
@@ -1,273 +0,0 @@
-[[_ug_runtime_configuring-core]]
-= 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.
-
-[NOTE]
-====
-Configuration properties for the JDO/DataNucleus objectstore can be found in the xref:ug.adoc#_ug_runtime_configuring-datanucleus[Configuring DataNucleus] section later in this chapter, while configuration properties for the viewers can be found in the their respective chapters, xref:ug.adoc#_ug_wicket-viewer_configuration-properties[here for Wicket viewer], and xref:ug.adoc#_ug_restfulobjects-viewer_configuration-properties[here for the Restful Objects viewer].
-====
-
-
-
-.Core Configuration Properties
-[cols="2a,1,3a", options="header"]
-|===
-|Property
-|Value +
-(default value)
-|Description
-
-|`isis.object.` +
-`editing`
-| `true`,`false` (`true`)
-|Whether objects' properties and collections can be edited directly (for objects annotated with xref:rg.adoc#_rg_annotations_manpage-DomainObject_editing[`@DomainObject#editing()`]); see xref:ug.adoc#_ug_runtime_configuring-core_isis-objects-editing[below] for further discussion.
-
-
-|`isis.persistor.` +
-`disableConcurrencyChecking`
-| `true`,`false` (`false`)
-| Disables concurrency checking globally. +
-
-Only intended for "emergency use" as a workaround while pending fix/patch to Apache Isis itself. (Note that there is no "datanucleus" in the property).
-
-|`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 xref:ug.adoc#_ug_how-tos_ui-hints_action-icons-and-css[UI hints] for more details.
-
-|`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:http://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 xref:ug.adoc#_ug_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 xref:ug.adoc#_ug_extending_programming-model_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 xref:ug.adoc#_ug_extending_programming-model_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 xref:ug.adoc#_ug_extending_programming-model_finetuning[finetuning the programming model] for more details.
-
-
-|`isis.reflector.` +
-`layoutMetadataReaders`
-|`FQCN`,`FQCN2`,...
-|Fully qualified class names of classes to be instantiated to read layout metadata, as used in for xref:rg.adoc#_rg_object-layout_dynamic[dynamic layout]s. +
-
-See xref:ug.adoc#_ug_extending_programming-model_layout-metadata-reader[Layout Metadata Reader] for more information.
-
-
-
-|`isis.reflector.validator`
-|`FQCN`
-|Custom implementation of `MetaModelValidator` (in the `org.apache.isis.core.metamodel.specloader.validator` package) +
-
-See xref:ug.adoc#_ug_extending_programming-model_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.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 xref:rg.adoc#_rg_annotations_manpage-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`]).
-
-
-|`isis.services.` +
-`audit.objects`
-| `all`, `none` (`all`)
-|Whether the changed properties of objects should be automatically audited (for objects annotated with xref:rg.adoc#_rg_annotations_manpage-DomainObject_auditing[`@DomainObject(auditing=Auditing.AS_CONFIGURED)`].
-
-|`isis.services.` +
-`command.actions`
-| `all`, `ignoreSafe`, `none` (`all`)
-|Whether actions should be automatically reified into commands (for actions annotated with xref:rg.adoc#_rg_annotations_manpage-Action_command[`@Action(command=CommandReification.AS_CONFIGURED)`]. +
-
-`ignoreQueryOnly` is an alias for `ignoreSafe`.
-
-
-|`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.` +
-`container.disableAutoFlush`
-| `true`,`false` (`_false_`)
-|Whether the `DomainObjectContainer` should automatically flush pending changes prior to querying (via `allMatches()`, `firstMatch()` and so on).
-
-
-
-|`ContentNegotiation-` +
-`ServiceXRoDomainType` +
-.prettyPrint
-| `true`,`false` (depends)
-|If a domain object has been mapped to the specified JAXB `x-ro-domain-type`, then determines whether the result is pretty-printed or not. +
-+
-If no configuration property is available, then the defaults is determined by the xref:ug.adoc#_ug_runtime_deployment-types[deployment type]: production mode disables pretty printing, while prototype mode enables it.
-
-
-
-| `isis.service.` +
-`email.tls.enabled`
-| `true`,`false` (`_true_`)
-|Whether to enable TLS for the email SMTP connection (used by xref:rg.adoc#_rg_services-api_manpage-EmailService[`EmailService`]). +
-
-NB: note that the key is mis-spelt, (`isis.service.email` rather than `isis.services.email`)
-
-| `isis.service.` +
-`email.sender.hostname` +
-| host (`_smtp.gmail.com_`)
-|The hostname of the external SMTP provider (used by xref:rg.adoc#_rg_services-api_manpage-EmailService[`EmailService`]). +
-
-NB: note that the key is mis-spelt, (`isis.service.email` rather than `isis.services.email`)
-
-| `isis.service.` +
-`email.port` +
-| port number (`_587_`)
-|The port number for the SMTP service on the the external SMTP host (used by xref:rg.adoc#_rg_services-api_manpage-EmailService[`EmailService`]). +
-
-NB: note that the key is mis-spelt, (`isis.service.email` rather than `isis.services.email`)
-
-
-| `isis.service.` +
-`email.sender.address` +
-| email address
-|The email address to use for sending out email (used by xref:rg.adoc#_rg_services-api_manpage-EmailService[`EmailService`]). *Mandatory*. +
-
-NB: note that the key is mis-spelt, (`isis.service.email` rather than `isis.services.email`)
-
-| `isis.service.` +
-`email.sender.password` +
-| email password
-|The corresponding password for the email address to use for sending out email (used by xref:rg.adoc#_rg_services-api_manpage-EmailService[`EmailService`]). *Mandatory*. +
-
-NB: note that the key is mis-spelt, (`isis.service.email` rather than `isis.services.email`)
-
-
-| `isis.services.` +
-`eventbus.implementation` +
-| `guava`, `axon`, FQCN (`_guava_`)
-|which implementation to use by the xref:rg.adoc#_rg_services-api_manpage-EventBusService[`EventBusService`] as the underlying event bus.
-
-| `isis.services.` +
-`eventbus.allowLateRegistration` +
-| `true`, `false`, (`_false_`)
-|whether a domain service can register with the xref:rg.adoc#_rg_services-api_manpage-EventBusService[`EventBusService`] after any events have posted. +
-
-Since this almost certainly constitutes a bug in application code, by default this is disallowed.
-
-
-| `isis.services.` +
-`exceprecog.logRecognizedExceptions` +
-| `true`, `false`, (`_false_`)
-|whether recognized exceptions should also be logged. +
-
-Generally a recognized exception is one that is expected (for example a uniqueness constraint violated in the database) and which does not represent an error condition. This property logs the exception anyway, useful for debugging.
-
-
-| `isis.services.` +
-`ExceptionRecognizerComposite-` +
-`ForJdoObjectStore.disable` +
-| `true`, `false`, (`_false_`)
-|whether to disable the default recognizers registered by `ExceptionRecognizerCompositeForJdoObjectStore`. +
-
-This implementation provides a default set of recognizers to convert RDBMS constraints into user-friendly messages. In the (probably remote) chance that this functionality isn't required, they can be disabled through this flag.
-
-
-|`isis.services.` +
-`publish.objects`
-| `all`, `none` (`all`)
-|Whether changed objects should be automatically published (for objects annotated with xref:rg.adoc#_rg_annotations_manpage-DomainObject_publishing[`@DomainObject(publishing=Publishing.AS_CONFIGURED)`].
-
-|`isis.services.` +
-`publish.actions`
-| `all`, `ignoreSafe`, `none` (`all`)
-|Whether actions should be automatically published (for actions annotated with xref:rg.adoc#_rg_annotations_manpage-Action_publishing[`@Action(publishing=Publishing.AS_CONFIGURED)`]. +
-
-|`isis.services.` +
-`translation.po.mode`
-| `read`,`write`
-|Whether to force the `TranslationService` into either read or write mode. +
-
-See xref:ug.adoc#_ug_more-advanced_i18n[i18n support] to learn more about the translation service.
-
-|`isis.viewers.` +
-`paged.parented`
-|positive integer (12)
-|Default page size for parented collections (as owned by an object, eg `Customer#getOrders()`)
-
-|`isis.viewers.` +
-`paged.standalone`
-|positive integer (25)
-|Default page size for standalone collections (as returned from an action invocation)
-
-
-|`isis.viewers.` +
-`propertyLayout.labelPosition`
-|`TOP`, `LEFT` +
-(`LEFT`)
-|Default for label position for all properties if not explicitly specified using xref:rg.adoc#_rg_annotations_manpage-PropertyLayout_labelPosition[`@PropertyLayout#labelPosition()`]
-
-|===
-
-
-
-
-[[_ug_runtime_configuring-core_isis-objects-editing]]
-== `objects.editing`
-
-This configuration property in effect allows editing to be disabled globally for an application:
-
-[source,ini]
-----
-isis.objects.editing=false
-----
-
-We 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.
-
-
-
-[[_ug_runtime_configuring-core_isis-viewers-propertyLayout-labelPosition]]
-== `propertyLayout.labelPosition`
-
-If you want a consistent look-n-feel throughout the app, eg all property labels to the top, then it'd be rather
-frustrating to have to annotate every property.
-
-Instead, a default can be specified in `isis.properties`:
-
-[source,ini]
-----
-isis.viewers.propertyLayout.labelPosition=TOP
-----
-
-or
-
-[source,ini]
-----
-isis.viewers.propertyLayout.labelPosition=LEFT
-----
-
-If these are not present then Apache Isis will render according to internal defaults. At the time of writing, this means labels are to the left for all datatypes except multiline strings.
http://git-wip-us.apache.org/repos/asf/isis/blob/7db02393/adocs/documentation/src/main/asciidoc/guides/_ug_runtime_configuring-datanucleus.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_runtime_configuring-datanucleus.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_runtime_configuring-datanucleus.adoc
deleted file mode 100644
index f354b02..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_runtime_configuring-datanucleus.adoc
+++ /dev/null
@@ -1,18 +0,0 @@
-[[_ug_runtime_configuring-datanucleus]]
-= 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 Apache 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 Apache 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 xref:ug.adoc#_ug_more-advanced_overriding-jdo-annotations[Overriding JDO Annotatons] for further discussion.
-
-
-include::_ug_runtime_configuring-datanucleus_properties.adoc[leveloffset=+1]
-include::_ug_runtime_configuring-datanucleus_persistence-xml.adoc[leveloffset=+1]
-include::_ug_runtime_configuring-datanucleus_eagerly-registering-entities.adoc[leveloffset=+1]
-include::_ug_runtime_configuring-datanucleus_disabling-persistence-by-reachability.adoc[leveloffset=+1]
-include::_ug_runtime_configuring-datanucleus_using-jndi-data-source.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/7db02393/adocs/documentation/src/main/asciidoc/guides/_ug_runtime_configuring-datanucleus_disabling-persistence-by-reachability.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_runtime_configuring-datanucleus_disabling-persistence-by-reachability.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_runtime_configuring-datanucleus_disabling-persistence-by-reachability.adoc
deleted file mode 100644
index 9edbc79..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_runtime_configuring-datanucleus_disabling-persistence-by-reachability.adoc
+++ /dev/null
@@ -1,88 +0,0 @@
-[[_ug_runtime_configuring-datanucleus_disabling-persistence-by-reachability]]
-= 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 Apache 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 Apache Isis' xref:rg.adoc#_rg_classes_utility_manpage-ObjectContracts[`ObjectContracts`] utility class. 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 xref:ug.adoc#_ug_getting-started_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.
-
-
-
-
-
-== The issue in more detail
-
-Consider these entities (http://yuml.me/edit/b8681268[yuml.me/b8681268]):
-
-image::{_imagesdir}runtime/configuring-datanucleus/disabling-persistence-by-reachability/party-agreementrole-agreement.png[width="750px"]
-
-
-
-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/7db02393/adocs/documentation/src/main/asciidoc/guides/_ug_runtime_configuring-datanucleus_eagerly-registering-entities.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_runtime_configuring-datanucleus_eagerly-registering-entities.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_runtime_configuring-datanucleus_eagerly-registering-entities.adoc
deleted file mode 100644
index 6822d77..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_runtime_configuring-datanucleus_eagerly-registering-entities.adoc
+++ /dev/null
@@ -1,44 +0,0 @@
-[[_ug_runtime_configuring-datanucleus_eagerly-registering-entities]]
-= Eagerly Registering Entities
-: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/
-
-Both Apache Isis and DataNucleus have their own metamodels of the domain entities. Apache 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.
-
-[WARNING]
-====
-There's a chance that (from 1.6.0+) feature may be (partly?) broken; see https://issues.apache.org/jira/browse/ISIS-847[ISIS-847].
-====
-
-
-== 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 xref:ug.adoc#_ug_testing_integ-test-support[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/7db02393/adocs/documentation/src/main/asciidoc/guides/_ug_runtime_configuring-datanucleus_persistence-xml.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_runtime_configuring-datanucleus_persistence-xml.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_runtime_configuring-datanucleus_persistence-xml.adoc
deleted file mode 100644
index d50e295..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_runtime_configuring-datanucleus_persistence-xml.adoc
+++ /dev/null
@@ -1,10 +0,0 @@
-[[_ug_runtime_configuring-datanucleus_persistence-xml]]
-= `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/
-
-
-NOTE: TODO
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/7db02393/adocs/documentation/src/main/asciidoc/guides/_ug_runtime_configuring-datanucleus_properties.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_runtime_configuring-datanucleus_properties.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_runtime_configuring-datanucleus_properties.adoc
deleted file mode 100644
index 3d8700c..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_runtime_configuring-datanucleus_properties.adoc
+++ /dev/null
@@ -1,64 +0,0 @@
-[[_ug_runtime_configuring-datanucleus_properties]]
-= 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/
-
-
-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.` +
-`classMetadataLoadedListener`
-|`FQCN`
-|The default (`o.a.i.os.jdo.dn.CreateSchemaObjectFromClassMetadata`) creates a DB schema object
-
-
-|`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 xref:ug.adoc#_ug_runtime_configuring-datanucleus_eagerly-registering-entities[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 xref:ug.adoc#_ug_runtime_configuring-datanucleus_disabling-persistence-by-reachability[discussion below].
-
-|===
-
http://git-wip-us.apache.org/repos/asf/isis/blob/7db02393/adocs/documentation/src/main/asciidoc/guides/_ug_runtime_configuring-datanucleus_using-jndi-data-source.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_runtime_configuring-datanucleus_using-jndi-data-source.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_runtime_configuring-datanucleus_using-jndi-data-source.adoc
deleted file mode 100644
index e5ee392..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_runtime_configuring-datanucleus_using-jndi-data-source.adoc
+++ /dev/null
@@ -1,75 +0,0 @@
-[[_ug_runtime_configuring-datanucleus_using-jndi-data-source]]
-= 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
-
-Using a connection pool managed directly by the application (that is, by Apache 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)
-
-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/7db02393/adocs/documentation/src/main/asciidoc/guides/_ug_runtime_deployment-types.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_runtime_deployment-types.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_runtime_deployment-types.adoc
deleted file mode 100644
index 6eb6cd3..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_runtime_deployment-types.adoc
+++ /dev/null
@@ -1,17 +0,0 @@
-[[_ug_runtime_deployment-types]]
-= Deployment 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/
-
-
-
-NOTE: TODO - xref:rg.adoc#_rg_annotations_manpage-Action_restrictTo[`@Action#restrictTo()`]
-
-
-
-Can be set to:
-
-* `SERVER` - broadly corresponds to Wicket's `PRODUCTION` mode
-* `PROTOTYPING` - the default; broadly corresponds to Wicket's `DEVELOPMENT` mode
-* `OTHER`