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/04/29 02:24:59 UTC
isis git commit: ISIS-1133: converting more documentation.
Repository: isis
Updated Branches:
refs/heads/ISIS-1133 6718ebf77 -> 61b99ff02
ISIS-1133: converting more documentation.
Project: http://git-wip-us.apache.org/repos/asf/isis/repo
Commit: http://git-wip-us.apache.org/repos/asf/isis/commit/61b99ff0
Tree: http://git-wip-us.apache.org/repos/asf/isis/tree/61b99ff0
Diff: http://git-wip-us.apache.org/repos/asf/isis/diff/61b99ff0
Branch: refs/heads/ISIS-1133
Commit: 61b99ff02229adb56d2a61a9a60f53dee920344b
Parents: 6718ebf
Author: Dan Haywood <da...@haywood-associates.co.uk>
Authored: Wed Apr 29 01:24:53 2015 +0100
Committer: Dan Haywood <da...@haywood-associates.co.uk>
Committed: Wed Apr 29 01:24:53 2015 +0100
----------------------------------------------------------------------
.../user-guide/_/isisjdosupport-service.adoc | 98 ---------
.../user-guide/_user-guide_appendices.adoc | 4 +
.../_user-guide_appendices_migration-notes.adoc | 217 +++++++++++++++++++
.../_user-guide_appendices_release-notes.adoc | 126 +++++++++++
..._user-guide_extending_programming-model.adoc | 1 -
.../user-guide/_user-guide_getting-started.adoc | 2 +
...de_getting-started_datanucleus-enhancer.adoc | 87 ++++++++
.../user-guide/_user-guide_how-tos.adoc | 2 +
.../_user-guide_how-tos_class-structure.adoc | 44 +---
.../_user-guide_how-tos_using-modules.adoc | 154 +++++++++++++
.../user-guide/_user-guide_reference.adoc | 4 +-
.../_user-guide_reference_annotations.adoc | 8 +
...uide_reference_configuration-properties.adoc | 28 +++
.../_user-guide_reference_domain-services.adoc | 4 +
...erence_domain-services_auditing-service.adoc | 13 ++
...erence_domain-services_auditing_service.adoc | 13 --
...ain-services_background-command-service.adoc | 2 +-
...ference_domain-services_command-service.adoc | 2 +-
...rence_domain-services_event-bus-service.adoc | 4 +-
...ence_domain-services_publishing-service.adoc | 11 +
...erence_domain-services_settings-service.adoc | 48 ++++
...-guide_reference_recognized-annotations.adoc | 8 -
...nce_recognized-configuration-properties.adoc | 28 ---
adocs/template/document.html.erb | 18 ++
24 files changed, 731 insertions(+), 195 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/isis/blob/61b99ff0/adocs/documentation/src/main/asciidoc/user-guide/_/isisjdosupport-service.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_/isisjdosupport-service.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_/isisjdosupport-service.adoc
deleted file mode 100644
index ecdfbe7..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_/isisjdosupport-service.adoc
+++ /dev/null
@@ -1,98 +0,0 @@
-Title: Using the IsisJdoSupport service
-
-The `IsisJdoSupport` service provides a number of general purpose methods for working with DataNucleus.
-
-== Executing arbitrary SQL
-
-The `executeSql(...)` method allows arbitrary queries to be submitted:
-
-[source]
-----
-List<Map<String, Object>> executeSql(String sql);
-----
-
-while `executeUpdate(...)` allows arbitrary updates to be performed.
-
-[source]
-----
-Integer executeUpdate(String sql);
-----
-
-A common use of these is to setup fixture data for integration tests.
-
-== Fixture support
-
-The `deleteAll(...)` method is provided pretty much exclusively for tearing down fixture data:
-
-[source]
-----
-void deleteAll(Class<?>... pcClasses);
-----
-
-== Reloading entities
-
-A http://www.datanucleus.org/products/datanucleus/jdo/orm/relationships.html[known limitation] of DataNucleus' implementation of JDO is that persisting a child entity (in a 1:n bidirectional relationship) does not cause the parent's collection to be updated.
-
-The `refresh(T domainObject)` method can be used to reload the parent object (or indeed any object).
-
-For example:
-
-[source]
-----
-public Order newOrder(final Customer customer) {
- Order order = newTransientInstance(Order.class);
- order.setCustomer(customer);
- persist(customer);
- getContainer().flush(); // to database
- isisJdoSupport.refresh(customer); // reload parent from database
- return order;
-}
-----
-
-== Accessing the JDO `PersistenceManager`
-
-Isis currently only supports JDO named queries. If you require more flexibility than this, eg for dynamically constructed queries, then the `IsisJdoSupport` interface can be used to obtain access to the underlying JDO `PersistenceManager`.
-
-For example:
-
-[source]
-----
-public List<Order> findOrders(...) {
- javax.jdo.PersistenceManager pm = isisJdoSupport.getPersistenceManager();
-
- // knock yourself out...
-
- return someListOfOrders;
-}
-----
-
-== Registering the Service
-
-The implementation is `IsisJdoSupportImpl`. It is registered in `isis.properties` as per usual:
-
-[source]
-----
-isis.services = ...\
- org.apache.isis.objectstore.jdo.datanucleus.service.support.IsisJdoSupportImpl,\
- ...
-----
-
-In the domain entity or service, add:
-
-[source]
-----
-private IsisJdoSupport isisJdoSupport;
-public void injectIsisJdoSupport(IsisJdoSupport isisJdoSupport) {
- this.isisJdoSupport = isisJdoSupport;
-}
-----
-
-or simply:
-
-[source]
-----
-@javax.inject.Inject
-private IsisJdoSupport isisJdoSupport;
-----
-
-The service will then be automatically injected as normal.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/61b99ff0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_appendices.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_appendices.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_appendices.adoc
index 87eebb0..8656e00 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_appendices.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_appendices.adoc
@@ -6,3 +6,7 @@
IMPORTANT: TODO
include::_user-guide_appendices_dev-env.adoc[leveloffset=+1]
+
+include::_user-guide_appendices_release-notes.adoc[leveloffset=+1]
+
+include::_user-guide_appendices_migration-notes.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/61b99ff0/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
new file mode 100644
index 0000000..286ebb2
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_appendices_migration-notes.adoc
@@ -0,0 +1,217 @@
+= Migration Notes
+: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/
+
+
+
+== Upgrading to 1.9.0-SNAPSHOT
+
+Isis 1.9.0 updates to DataNucleus 4.0.0, which requires some changes (simplifications) to the Maven configuration.
+
+If you starting a new app then you can start from the <<SimpleApp archetype>>; its Maven configuration has been updated.
+
+If you have an existing Isis app that you want to upgrade, then you'll need to make some changes.
+
+
+
+=== In the parent `pom.xml`
+
+under the `<project>/<properties>`, remove:
+
+[source,xml]
+----
+<!-- must be consistent with the versions defined by the JDO Objectstore -->
+<datanucleus-accessplatform-jdo-rdbms.version>3.3.6</datanucleus-accessplatform-jdo-rdbms.version>
+<datanucleus-maven-plugin.version>3.3.2</datanucleus-maven-plugin.version>
+----
+
+
+== In `dom/pom.xml`,
+
+under `<build>/<plugins>`, remove:
+
+[source,xml]
+----
+<plugin>
+ <groupId>org.datanucleus</groupId>
+ <artifactId>datanucleus-maven-plugin</artifactId>
+ <version>${datanucleus-maven-plugin.version}</version>
+ <configuration>
+ <fork>false</fork>
+ <log4jConfiguration>${basedir}/log4j.properties</log4jConfiguration>
+ <verbose>true</verbose>
+ <props>${basedir}/datanucleus.properties</props>
+ </configuration>
+ <executions>
+ <execution>
+ <phase>compile</phase>
+ <goals>
+ <goal>enhance</goal>
+ </goals>
+ </execution>
+ </executions>
+</plugin>
+----
+
+and (if you have it) under `<build>/<pluginManagement>/<plugins>`, remove:
+
+[source,xml]
+----
+<!--This plugin's configuration is used to store Eclipse m2e settings only. It has no influence on the Maven build itself.-->
+<plugin>
+ <groupId>org.eclipse.m2e</groupId>
+ <artifactId>lifecycle-mapping</artifactId>
+ <version>1.0.0</version>
+ <configuration>
+ <lifecycleMappingMetadata>
+ <pluginExecutions>
+ <pluginExecution>
+ <pluginExecutionFilter>
+ <groupId>
+ org.datanucleus
+ </groupId>
+ <artifactId>
+ datanucleus-maven-plugin
+ </artifactId>
+ <versionRange>
+ [3.2.0-release,)
+ </versionRange>
+ <goals>
+ <goal>enhance</goal>
+ </goals>
+ </pluginExecutionFilter>
+ <action>
+ <ignore></ignore>
+ </action>
+ </pluginExecution>
+ </pluginExecutions>
+ </lifecycleMappingMetadata>
+ </configuration>
+</plugin>
+----
+
+
+and instead in `<profiles>` add:
+
+
+[source,xml]
+----
+<profile>
+ <id>enhance</id>
+ <activation>
+ <activeByDefault>true</activeByDefault>
+ </activation>
+ <properties>
+ <datanucleus-maven-plugin.version>4.0.0-release</datanucleus-maven-plugin.version>
+ </properties>
+ <build>
+ <pluginManagement>
+ <plugins>
+ <plugin>
+ <!--This plugin's configuration is used to store Eclipse m2e settings only. It has no influence on the Maven build itself.-->
+ <groupId>org.eclipse.m2e</groupId>
+ <artifactId>lifecycle-mapping</artifactId>
+ <version>1.0.0</version>
+ <configuration>
+ <lifecycleMappingMetadata>
+ <pluginExecutions>
+ <pluginExecution>
+ <pluginExecutionFilter>
+ <groupId>org.datanucleus</groupId>
+ <artifactId>datanucleus-maven-plugin</artifactId>
+ <versionRange>[${datanucleus-maven-plugin.version},)</versionRange>
+ <goals>
+ <goal>enhance</goal>
+ </goals>
+ </pluginExecutionFilter>
+ <action>
+ <ignore></ignore>
+ </action>
+ </pluginExecution>
+ </pluginExecutions>
+ </lifecycleMappingMetadata>
+ </configuration>
+ </plugin>
+ </plugins>
+ </pluginManagement>
+ <plugins>
+ <plugin>
+ <groupId>org.datanucleus</groupId>
+ <artifactId>datanucleus-maven-plugin</artifactId>
+ <version>${datanucleus-maven-plugin.version}</version>
+ <configuration>
+ <fork>false</fork>
+ <log4jConfiguration>${basedir}/log4j.properties</log4jConfiguration>
+ <verbose>true</verbose>
+ <props>${basedir}/datanucleus.properties</props>
+ </configuration>
+ <executions>
+ <execution>
+ <phase>process-classes</phase>
+ <goals>
+ <goal>enhance</goal>
+ </goals>
+ </execution>
+ </executions>
+ </plugin>
+ </plugins>
+ </build>
+ <dependencies>
+ <dependency>
+ <groupId>org.datanucleus</groupId>
+ <artifactId>datanucleus-core</artifactId>
+ </dependency>
+ <dependency>
+ <groupId>org.datanucleus</groupId>
+ <artifactId>datanucleus-jodatime</artifactId>
+ </dependency>
+ <dependency>
+ <groupId>org.datanucleus</groupId>
+ <artifactId>datanucleus-api-jdo</artifactId>
+ </dependency>
+ </dependencies>
+</profile>
+----
+
+If you don't use Eclipse then you can omit the `org.eclipse.m2e` plugin in `<pluginManagement>`.
+
+
+
+
+== In the webapp's `persistor_datanucleus.properties`
+
+in `src/main/webapp/WEB-INF/`,
+
+change:
+
+[source,ini]
+----
+isis.persistor.datanucleus.impl.datanucleus.autoCreateSchema=true
+isis.persistor.datanucleus.impl.datanucleus.validateTables=true
+isis.persistor.datanucleus.impl.datanucleus.validateConstraints=true
+----
+
+to:
+
+[source,ini]
+----
+isis.persistor.datanucleus.impl.datanucleus.schema.autoCreateAll=true
+isis.persistor.datanucleus.impl.datanucleus.schema.validateTables=true
+isis.persistor.datanucleus.impl.datanucleus.schema.validateConstraints=true
+----
+
+and change:
+
+[source,ini]
+----
+isis.persistor.datanucleus.impl.datanucleus.identifier.case=PreserveCase
+----
+
+to:
+
+[source,ini]
+----
+isis.persistor.datanucleus.impl.datanucleus.identifier.case=MixedCase
+----
+
http://git-wip-us.apache.org/repos/asf/isis/blob/61b99ff0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_appendices_release-notes.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_appendices_release-notes.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_appendices_release-notes.adoc
new file mode 100644
index 0000000..266879e
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_appendices_release-notes.adoc
@@ -0,0 +1,126 @@
+= Release Notes
+: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/
+
+[cols="1,1,2a,3a"]
+|===
+| Version | Date | Components | Notes
+
+| 1.8.0
+| 24-feb-2015
+| * link:https://issues.apache.org/jira/secure/ReleaseNote.jspa?projectId=12311171&version=12328845[core-1.8.0]
+* link:https://issues.apache.org/jira/secure/ReleaseNote.jspa?projectId=12311171&version=12328847[archetype-1.8.0]
+| Wicket viewer moved into core; todoapp archetype moved to http://isisaddons.org[Isis Addons] (non-ASF).
+
+| 1.7.0
+| 18-oct-2014
+| * link:https://issues.apache.org/jira/secure/ReleaseNote.jspa?projectId=12311171&version=12326453[core-1.7.0]
+* link:https://issues.apache.org/jira/secure/ReleaseNote.jspa?projectId=12311171&version=12326460[viewer-wicket-1.7.0]
+* link:https://issues.apache.org/jira/secure/ReleaseNote.jspa?projectId=12311171&version=12327441[archetype-simpleapp-1.7.0]
+* link:https://issues.apache.org/jira/secure/ReleaseNote.jspa?projectId=12311171&version=12327440[archetype-todoapp-1.7.0]
+| Module functionality previously in 1.6.0 now retired; use http://isisaddons.org[Isis Addons] (non-ASF) instead.
+
+| 1.6.0
+| 28-jul-2014
+| * link:https://issues.apache.org/jira/secure/ReleaseNote.jspa?projectId=12311171&version=12325314[core-1.6.0]
+* link:https://issues.apache.org/jira/secure/ReleaseNote.jspa?projectId=12311171&version=12325318[viewer-wicket-1.6.0]
+* link:https://issues.apache.org/jira/secure/ReleaseNote.jspa?projectId=12311171&version=12326462[archetype-simpleapp-1.6.0]
+* link:https://issues.apache.org/jira/secure/ReleaseNote.jspa?projectId=12311171&version=12326461[archetype-todoapp-1.6.0]
+| RestfulObjects viewer, JDO/Datanucleus Objectstore and Shiro Security all moved into core. Quickstart-wrj archetype renamed to todoapp; simple-wrj archetype renamed to simpleapp. Some functionality copied/refactored as http://isisaddons.org[Isis Addons] (non-ASF).
+
+| 1.5.0
+| 08-jun-2014
+| * link:https://issues.apache.org/jira/secure/ReleaseNote.jspa?projectId=12311171&version=12326524[core-1.5.0]
+* link:https://issues.apache.org/jira/secure/ReleaseNote.jspa?projectId=12311171&version=12326525[objectstore-jdo-1.5.0]
+* link:https://issues.apache.org/jira/secure/ReleaseNote.jspa?projectId=12311171&version=12326529[security-shiro-1.5.0]
+* link:https://issues.apache.org/jira/secure/ReleaseNote.jspa?projectId=12311171&version=12326947[viewer-restfulobjects-2.3.0]
+* link:https://issues.apache.org/jira/secure/ReleaseNote.jspa?projectId=12311171&version=12326526[viewer-wicket-1.5.0]
+* link:https://issues.apache.org/jira/secure/ReleaseNote.jspa?projectId=12311171&version=12326528[archetype-simple-wrj-1.5.0]
+* link:https://issues.apache.org/jira/secure/ReleaseNote.jspa?projectId=12311171&version=12326527[archetype-quickstart-wrj-1.5.0]
+| No longer releasing security-file
+
+| 1.4.1
+| 14-mar-2014
+| * objectstore-jdo-1.4.1
+* viewer-wicket-1.4.1
+* archetype-simple-wrj-1.4.1
+* archetype-quickstart-wrj-1.4.1
+| Patch release
+
+| 1.4.0
+| 11-mar-2014
+| * core-1.4.0
+* objectstore-jdo-1.4.0
+* security-file-1.4.0
+* security-shiro-1.4.0
+* viewer-restfulobjects-2.2.0
+* viewer-wicket-1.4.0
+* archetype-simple-wrj-1.4.0
+* archetype-quickstart-wrj-1.4.0
+|
+
+| 1.3.1
+| 7-nov-2013
+| * viewer-wicket-1.3.1
+* archetype-simple-wrj-1.3.1
+* archetype-quickstart-wrj-1.3.1
+| Patch release
+
+| 1.3.0
+| 25-oct-2013
+| * core-1.3.0
+* objectstore-jdo-1.3.0
+* security-file-1.0.2
+* security-shiro-1.3.0
+* viewer-restfulobjects-2.1.0
+* viewer-wicket-1.3.0
+* archetype-simple-wrj-1.3.0
+* archetype-quickstart-wrj-1.3.0
+| WRJ archetype renamed to Quickstart WRJ. Simple WRJ archetype added.
+
+| 1.2.0
+| 30-may-2013
+| * core-1.2.0
+* objectstore-jdo-1.2.0
+* security-file-1.0.1
+* security-shiro-1.1.1
+* viewer-restfulobjects-2.0.0
+* viewer-wicket-1.2.0
+* archetype-wrj-1.0.3
+|
+
+| 1.1.0
+| 31-jan-2013
+|* core-1.1.0
+* security-shiro-1.1.0
+* viewer-wicket-1.1.0
+* archetype-wrj-1.0.2
+|
+
+| 1.0.1
+| 10-jan-2013
+| * security-shiro-1.0.0
+* archetype-wrj-1.0.1
+| Combining RestfulObjects and Wicket viewers into a single webapp, along with Shiro security
+
+| 1.0.0
+| 24-dec-2012
+|* core-1.0.0
+* security-file-1.0.0
+* viewer-wicket-1.0.0
+* viewer-restfulobjects-1.0.0
+* archetype-wrj-1.0.0
+| First release having graduated
+
+| 0.2.0-incubating
+| 20-feb-2012
+| * 0.2.0-incubating
+|
+
+| 0.1.2-incubating
+| 13-jul-2011
+| * 0.1.2-incubating
+| First release in the ASF incubator
+|===
+
http://git-wip-us.apache.org/repos/asf/isis/blob/61b99ff0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_extending_programming-model.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_extending_programming-model.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_extending_programming-model.adoc
index c1d7d89..54dcc25 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_extending_programming-model.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_extending_programming-model.adoc
@@ -13,4 +13,3 @@ IMPORTANT: TODO
## Layout metadata reader
-## Listener to create DB schema objects
http://git-wip-us.apache.org/repos/asf/isis/blob/61b99ff0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_getting-started.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_getting-started.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_getting-started.adoc
index 5c05a27..c260365 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_getting-started.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_getting-started.adoc
@@ -7,3 +7,5 @@ IMPORTANT: TODO
include::_user-guide_getting-started_simpleapp-archetype.adoc[leveloffset=+1]
+include::_user-guide_getting-started_datanucleus-enhancer.adoc[leveloffset=+1]
+
http://git-wip-us.apache.org/repos/asf/isis/blob/61b99ff0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_getting-started_datanucleus-enhancer.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_getting-started_datanucleus-enhancer.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_getting-started_datanucleus-enhancer.adoc
new file mode 100644
index 0000000..c0d6c4a
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_getting-started_datanucleus-enhancer.adoc
@@ -0,0 +1,87 @@
+= Datanucleus Enhancer
+: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 leveraging the JDO/Datanucleus ORM, Isis' JDO objectstore is very powerful. However, with such power comes a little bit of complexity to the development environment: all domain objects must be enhanced through the http://db.apache.org/jdo/enhancement.html[JDO enhancer]. So the enhancer must, in one way or another, be integrated into your development environment.
+
+If working from the Maven command line, JDO enhancement is done using the `maven-datanucleus-plugin`. As of 1.9.0-SNAPSHOT, we put all the configuration into an (always active) profile:
+
+[source,xml]
+----
+<profile>
+ <id>enhance</id>
+ <activation>
+ <activeByDefault>true</activeByDefault>
+ </activation>
+ <properties>
+ <datanucleus-maven-plugin.version>4.0.0-release</datanucleus-maven-plugin.version>
+ </properties>
+ <build>
+ <plugins>
+ <plugin>
+ <groupId>org.datanucleus</groupId>
+ <artifactId>datanucleus-maven-plugin</artifactId>
+ <version>${datanucleus-maven-plugin.version}</version>
+ <configuration>
+ <fork>false</fork>
+ <log4jConfiguration>${basedir}/log4j.properties</log4jConfiguration>
+ <verbose>true</verbose>
+ <props>${basedir}/datanucleus.properties</props>
+ </configuration>
+ <executions>
+ <execution>
+ <phase>process-classes</phase>
+ <goals>
+ <goal>enhance</goal>
+ </goals>
+ </execution>
+ </executions>
+ </plugin>
+ </plugins>
+ </build>
+ <dependencies>
+ <dependency>
+ <groupId>org.datanucleus</groupId>
+ <artifactId>datanucleus-core</artifactId>
+ </dependency>
+ <dependency>
+ <groupId>org.datanucleus</groupId>
+ <artifactId>datanucleus-jodatime</artifactId>
+ </dependency>
+ <dependency>
+ <groupId>org.datanucleus</groupId>
+ <artifactId>datanucleus-api-jdo</artifactId>
+ </dependency>
+ </dependencies>
+</profile>
+----
+
+The <<SimpleApp Archetype>> sets up the plugin correctly in the `dom` (domain object model) module. (It's actually a little bit more complext to cater for users of the Eclipse IDE using Eclipse's m2e plugin).
+
+=== `META-INF/persistence.xml`
+
+It's also a good idea to ensure that the `dom` module has a JDO `META-INF/persistence.xml` file:
+
+[source,xml]
+----
+<?xml version="1.0" encoding="UTF-8" ?>
+<persistence xmlns="http://java.sun.com/xml/ns/persistence"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://java.sun.com/xml/ns/persistence http://java.sun.com/xml/ns/persistence/persistence_1_0.xsd" version="1.0">
+
+ <persistence-unit name="simple"> <!--1-->
+ </persistence-unit>
+</persistence>
+----
+<1> change as required; typically is the name of the app.
+
+Again, the <<SimpleApp Archetype>> does this.
+
+[WARNING]
+====
+If running on Windows, then there's a good chance you'll hit the http://msdn.microsoft.com/en-us/library/aa365247%28VS.85%29.aspx#maxpath[maximum path length limit]. In this case the `persistence.xml` file is mandatory rather than optional.
+
+This file is also required if you are using developing in Eclipse and relying on the DataNucleus plugin for Eclipse rather than the DataNucleus plugin for Maven. More information can be found <<Setting up Eclipse,here>>.
+====
http://git-wip-us.apache.org/repos/asf/isis/blob/61b99ff0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos.adoc
index 9f9b933..f0fb5dd 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos.adoc
@@ -23,6 +23,8 @@ include::_user-guide_how-tos_drop-downs-and-defaults.adoc[leveloffset=+1]
include::_user-guide_how-tos_triggering-events.adoc[leveloffset=+1]
+include::_user-guide_how-tos_using-modules.adoc[leveloffset=+1]
+
include::_user-guide_how-tos_tips-n-tricks.adoc[leveloffset=+1]
include::_user-guide_how-tos_error-handling.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/61b99ff0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_class-structure.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_class-structure.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_class-structure.adoc
index 7468105..d792b9c 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_class-structure.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_class-structure.adoc
@@ -20,49 +20,9 @@ We use Java packages as a way to group related domain objects together; the pack
In the same way that Java packages act as a namespace for domain objects, it's good practice to map domain entities to their own (database) schemas.
-[NOTE]
+[TIP]
====
-As of 1.9.0-SNAPSHOT, all the IsisAddons modules (not ASF) define their own (database) schemas.
-
-For example:
-
-[source,java]
-----
-@javax.jdo.annotations.PersistenceCapable( ...
- schema = "isissecurity",
- table = "ApplicationUser")
-public class ApplicationUser ... { ... }
-----
-
-and
-
-[source,java]
-----
-@javax.jdo.annotations.PersistenceCapable( ...
- schema = "isisaudit",
- table="AuditEntry")
-public class AuditEntry ... { ... }
-----
-
-This results in CREATE TABLE statements such as:
-
-[source,sql]
-----
-CREATE TABLE isissecurity."ApplicationUser" (
- ...
-)
-----
-
-and
-
-[source,sql]
-----
-CREATE TABLE isisaudit."AuditEntry" (
- ...
-)
-----
-
-If you don't want to use schemas, then note that you can override the `@PersistenceCapable` annotation by providing XML annotations (`mappings.jdo` files).
+For more on this topic, see <<Using Modules>>.
====
http://git-wip-us.apache.org/repos/asf/isis/blob/61b99ff0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_using-modules.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_using-modules.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_using-modules.adoc
new file mode 100644
index 0000000..8872a55
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_using-modules.adoc
@@ -0,0 +1,154 @@
+= Using Modules
+: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: 1.9.0-SNAPSHOT onwards.
+
+We use Java packages as a way to group related domain objects together; the package name forms a namespace. We can then
+reason about all the classes in that package/namespace as a single unit. Good examples are the various
+http://github.com/isisaddons[Isis Addons] (not ASF): security, commands, auditing and so on.
+
+In the same way that Java packages act as a namespace for domain objects, it's good practice to map domain entities to
+their own (database) schemas. As of 1.9.0-SNAPSHOT, all the IsisAddons modules do this, for example:
+
+[source,java]
+----
+@javax.jdo.annotations.PersistenceCapable( ...
+ schema = "isissecurity",
+ table = "ApplicationUser")
+public class ApplicationUser ... { ... }
+----
+
+results in a `CREATE TABLE` statement of:
+
+[source,sql]
+----
+CREATE TABLE isissecurity."ApplicationUser" (
+ ...
+)
+----
+
+
+while:
+
+[source,java]
+----
+@javax.jdo.annotations.PersistenceCapable( ...
+ schema = "isisaudit",
+ table="AuditEntry")
+public class AuditEntry ... { ... }
+----
+
+similarly results in:
+
+[source,sql]
+----
+CREATE TABLE isisaudit."AuditEntry" (
+ ...
+)
+----
+
+
+If for some reason you don't want to use schemas (though we strongly recommend that you do), then then note that you can override the `@PersistenceCapable` annotation by providing XML metadata (the `mappings.jdo` file). See <<Overriding Annotations>> for a write-up of how to do this.
+
+
+
+== Listener to create DB schema objects
+
+JDO/DataNucleus does not automatically create these schema objects, but it _does_ provide a listener callback API
+on the initialization of each class into the JDO metamodel.
+
+[TIP]
+====
+Actually, the above statement isn't quite true. In DN 3.2.x (as used by Isis up to v1.8.0) there was no support for schemas. As of Isis 1.9.0-SNAPSHOT and DN 4.0 there is now support. But we implemented this feature initially against DN 3.2.x, and it still works, so we've decided to leave it in.
+====
+
+Therefore Apache Isis attaches a listener, `CreateSchemaObjectFromClassMetadata`, that checks for the schema's existence, and creates the schema if required.
+
+The guts of its implementation is:
+
+[source,java]
+----
+package org.apache.isis.objectstore.jdo.datanucleus;
+
+public class CreateSchemaObjectFromClassMetadata
+ implements MetaDataListener,
+ PersistenceManagerFactoryAware,
+ DataNucleusPropertiesAware {
+
+ @Override
+ public void loaded(final AbstractClassMetaData cmd) { ... }
+
+ protected String buildSqlToCheck(final AbstractClassMetaData cmd) {
+ final String schemaName = schemaNameFor(cmd);
+ return String.format(
+ "SELECT count(*) FROM INFORMATION_SCHEMA.SCHEMATA where SCHEMA_NAME = '%s'", schemaName);
+ }
+
+ protected String buildSqlToExec(final AbstractClassMetaData cmd) {
+ final String schemaName = schemaNameFor(cmd);
+ return String.format("CREATE SCHEMA \"%s\"", schemaName);
+ }
+}
+----
+
+where `MetaDataListener` is the DataNucleus listener API:
+
+[source,java]
+----
+public interface MetaDataListener {
+ void loaded(AbstractClassMetaData cmd);
+}
+----
+
+Although not formal API, the default `CreateSchemaObjectFromClassMetadata` has been designed to be easily overrideable if you
+need to tweak it to support other RDBMS'. Any implementation must implement `org.datanucleus.metadata.MetaDataListener`:
+
+The implementation provided has has been tested for HSQLDB, PostgreSQL and MS SQL Server, and is used automatically unless an alternative implementation is specified (as described in the section below).
+
+
+
+== Registering an Alternative Implementation
+
+An alternative implementation can be registered and used through the following configuration property:
+
+[source,ini]
+----
+#
+# hook to perform additional initialization when JDO class metadata is loaded
+# default implementation will attempt to run 'create schema' for the specified schema.
+#
+isis.persistor.datanucleus.classMetadataLoadedListener=\
+ org.apache.isis.objectstore.jdo.datanucleus.CreateSchemaObjectFromClassMetadata
+----
+Because this pertains to the JDO Objectstore we suggest you put this configuration property in `WEB-INF/persistor_datanucleus.properties`; but putting it in `isis.properties` will also work.
+
+Any implementation must implement `org.datanucleus.metadata.MetaDataListener`. In many cases simply subclassing from `CreateSchemaObjectFromClassMetadata` and overriding `buildSqlToCheck(...)` and `buildSqlToExec(...)` should suffice.
+
+If you _do_ need more control, your implementation can also optionally implement `org.apache.isis.objectstore.jdo.datanucleus.PersistenceManagerFactoryAware`:
+
+[source,java]
+----
+public interface PersistenceManagerFactoryAware {
+ public void setPersistenceManagerFactory(final PersistenceManagerFactory persistenceManagerFactory);
+}
+----
+
+and also `org.apache.isis.objectstore.jdo.datanucleus.DataNucleusPropertiesAware`:
+
+[source,java]
+----
+public interface DataNucleusPropertiesAware {
+ public void setDataNucleusProperties(final Map<String, String> properties);
+}
+----
+
+This latter interface provides access to the properties passed through to JDO/DataNucleus.
+
+
+
+
+== Please contribute back
+
+If you do extend Isis' `CreateSchemaObjectFromClassMetadata` class for some other database, please https://issues.apache.org/jira/browse/ISIS[contribute back] your improvements.
http://git-wip-us.apache.org/repos/asf/isis/blob/61b99ff0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference.adoc
index f2f1dfc..84b2dd1 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference.adoc
@@ -7,9 +7,9 @@ IMPORTANT: TODO
include::_user-guide_reference_recognized-methods.adoc[leveloffset=+1]
-include::_user-guide_reference_recognized-annotations.adoc[leveloffset=+1]
+include::_user-guide_reference_annotations.adoc[leveloffset=+1]
-include::_user-guide_reference_recognized-configuration-properties.adoc[leveloffset=+1]
+include::_user-guide_reference_configuration-properties.adoc[leveloffset=+1]
include::_user-guide_reference_domain-services.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/61b99ff0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_annotations.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_annotations.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_annotations.adoc
new file mode 100644
index 0000000..5ad4b76
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_annotations.adoc
@@ -0,0 +1,8 @@
+= Annotations
+: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/61b99ff0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_configuration-properties.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_configuration-properties.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_configuration-properties.adoc
new file mode 100644
index 0000000..d170d45
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_configuration-properties.adoc
@@ -0,0 +1,28 @@
+= 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: TODO
+
+
+.Configuration Properties
+[cols="2,1,3", options="header"]
+|===
+|Property
+|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_`
+|Whether the `DomainObjectContainer` should automatically flush pending changes prior to querying (via `allMatches()`, `firstMatch()` and so on).
+
+|`isis.viewer.wicket.` `disableDependentChoiceAutoSelection`
+|`true`,`_false_`
+|For dependent choices (eg category/subcategory), whether the dependent choice should automatically select the first option, or instead should leave empty
+|===
+
http://git-wip-us.apache.org/repos/asf/isis/blob/61b99ff0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_domain-services.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_domain-services.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_domain-services.adoc
index 7798c1a..0c42181 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_domain-services.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_domain-services.adoc
@@ -40,10 +40,14 @@ include::_user-guide_reference_domain-services_isis-jdo-support.adoc[leveloffset
include::_user-guide_reference_domain-services_memento-service.adoc[leveloffset=+1]
+include::_user-guide_reference_domain-services_publishing-service.adoc[leveloffset=+1]
+
include::_user-guide_reference_domain-services_query-results-cache.adoc[leveloffset=+1]
include::_user-guide_reference_domain-services_scratch-pad.adoc[leveloffset=+1]
+include::_user-guide_reference_domain-services_settings-service.adoc[leveloffset=+1]
+
include::_user-guide_reference_domain-services_user-profile-service.adoc[leveloffset=+1]
include::_user-guide_reference_domain-services_user-registration-service.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/61b99ff0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_domain-services_auditing-service.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_domain-services_auditing-service.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_domain-services_auditing-service.adoc
new file mode 100644
index 0000000..c719fbe
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_domain-services_auditing-service.adoc
@@ -0,0 +1,13 @@
+= Auditing Service
+: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
+
+
+
+
+== Isis Addons Implementation
+
+For 1.7.0+, see the http://github.com/isisaddons/isis-module-audit[Isis addons' Audit module] (non-ASF).
http://git-wip-us.apache.org/repos/asf/isis/blob/61b99ff0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_domain-services_auditing_service.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_domain-services_auditing_service.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_domain-services_auditing_service.adoc
deleted file mode 100644
index f834649..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_domain-services_auditing_service.adoc
+++ /dev/null
@@ -1,13 +0,0 @@
-= Auditing Service
-: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
-
-
-
-
-== Isis Addons Implementation
-
-For 1.7.0+, see the http://github.com/isisaddons/isis-module-audit}[Isis addons' Audit module] (non-ASF).
http://git-wip-us.apache.org/repos/asf/isis/blob/61b99ff0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_domain-services_background-command-service.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_domain-services_background-command-service.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_domain-services_background-command-service.adoc
index 8eaac7f..2635e98 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_domain-services_background-command-service.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_domain-services_background-command-service.adoc
@@ -8,4 +8,4 @@ IMPORTANT: TODO
== Isis Addons Implementation
-For 1.7.0+, see the http://github.com/isisaddons/isis-module-command}[Isis addons' Command module] (non-ASF).
+For 1.7.0+, see the http://github.com/isisaddons/isis-module-command[Isis addons' Command module] (non-ASF).
http://git-wip-us.apache.org/repos/asf/isis/blob/61b99ff0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_domain-services_command-service.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_domain-services_command-service.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_domain-services_command-service.adoc
index 9ec6079..8d34b8d 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_domain-services_command-service.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_domain-services_command-service.adoc
@@ -8,4 +8,4 @@ IMPORTANT: TODO
== Isis Addons Implementation
-For 1.7.0+, see the http://github.com/isisaddons/isis-module-command}[Isis addons' Command module] (non-ASF).
+For 1.7.0+, see the http://github.com/isisaddons/isis-module-command[Isis addons' Command module] (non-ASF).
http://git-wip-us.apache.org/repos/asf/isis/blob/61b99ff0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_domain-services_event-bus-service.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_domain-services_event-bus-service.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_domain-services_event-bus-service.adoc
index 67cb279..f1e41fc 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_domain-services_event-bus-service.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_domain-services_event-bus-service.adoc
@@ -5,9 +5,11 @@
IMPORTANT: TODO
+## Implementation
+IMPORTANT: TODO
-## Implementation
+## Registration
The `EventBusServiceJdo` class provides the default implementation and (as of 1.6.0+) is automatically registered using `@DomainService`. No further configuration is necessary.
http://git-wip-us.apache.org/repos/asf/isis/blob/61b99ff0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_domain-services_publishing-service.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_domain-services_publishing-service.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_domain-services_publishing-service.adoc
new file mode 100644
index 0000000..5a42926
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_domain-services_publishing-service.adoc
@@ -0,0 +1,11 @@
+= Publishing Service
+: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
+
+
+== Isis Addons Implementation
+
+For 1.7.0+, see the http://github.com/isisaddons/isis-module-publishing[Isis addons' Publishing module] (non-ASF).
http://git-wip-us.apache.org/repos/asf/isis/blob/61b99ff0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_domain-services_settings-service.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_domain-services_settings-service.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_domain-services_settings-service.adoc
new file mode 100644
index 0000000..eaebcf0
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_domain-services_settings-service.adoc
@@ -0,0 +1,48 @@
+= Settings Service
+: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]
+====
+This service (both its API and implementation) are entirely independent of Apache Isis, being part of the http://github.com/isisaddons/isis-module-settings}[Isis addons' Settings module] (non-ASF). The service is documented here for your convenience.
+====
+
+== Application Settings
+
+=== API
+
+IMPORTANT: TODO
+
+=== Implementation
+
+In the case of `ApplicationSettingsService`, the service is implemented by `ApplicationSettingsServiceJdo`, with the `ApplicationSetting` interface implemented by a `ApplicationSettingsJdo` entity.
+
+The service also provides the ability to create list all existing settings, create new settings (of whichever datatype), update settings, and to delete settings.
+
+These actions can be hidden using security if need be.
+
+== User Settings
+
+=== API
+
+IMPORTANT: TODO
+
+=== Implementation
+
+In the case of `UserSettingsService`, the service is implemented by `UserSettingsServiceJdo`, with the `UserSetting` interface implemented by a `UserSettingsJdo` entity.
+
+As for application settings, the user settings service also provides the ability to create list all existing settings, create new settings (of whichever datatype), update settings, and to delete settings.
+
+These actions can be hidden using security if need be.
+
+
+== Registration and Configuration
+
+The `ApplicationSettingsServiceJdo` class and `UserSettingsServiceJdo` are annotated with `@DomainService` and so are automatically registered with the framework, with actions appearing on the secondary menu bar.
+
+IMPORTANT: TODO - screenshot of settings menu
+
+All actions from the services emit domain events. If you wish to hide/disable these default actions in your application, we recommend using up a subscriber on the actions' domain events to veto their visibility/usability.
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/61b99ff0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_recognized-annotations.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_recognized-annotations.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_recognized-annotations.adoc
deleted file mode 100644
index 514a56b..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_recognized-annotations.adoc
+++ /dev/null
@@ -1,8 +0,0 @@
-= Recognized Annotations
-: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/61b99ff0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_recognized-configuration-properties.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_recognized-configuration-properties.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_recognized-configuration-properties.adoc
deleted file mode 100644
index 6c2105e..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_recognized-configuration-properties.adoc
+++ /dev/null
@@ -1,28 +0,0 @@
-= Recognized 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: TODO
-
-
-.Configuration Properties
-[cols="2,1,3", options="header"]
-|===
-|Property
-|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_`
-|Whether the `DomainObjectContainer` should automatically flush pending changes prior to querying (via `allMatches()`, `firstMatch()` and so on).
-
-|`isis.viewer.wicket.` `disableDependentChoiceAutoSelection`
-|`true`,`_false_`
-|For dependent choices (eg category/subcategory), whether the dependent choice should automatically select the first option, or instead should leave empty
-|===
-
http://git-wip-us.apache.org/repos/asf/isis/blob/61b99ff0/adocs/template/document.html.erb
----------------------------------------------------------------------
diff --git a/adocs/template/document.html.erb b/adocs/template/document.html.erb
index cb8df42..436170a 100644
--- a/adocs/template/document.html.erb
+++ b/adocs/template/document.html.erb
@@ -47,6 +47,24 @@
background-color: inherit;
border-style: none;
}
+
+ .literalblock pre,
+ .listingblock pre:not(.highlight),
+ .listingblock pre[class="highlight"],
+ .listingblock pre[class^="highlight "],
+ .listingblock pre.CodeRay,
+ .listingblock pre.prettyprint {
+ background: rgb(253, 250, 246);
+ }
+ .sidebarblock .literalblock pre,
+ .sidebarblock .listingblock pre:not(.highlight),
+ .sidebarblock .listingblock pre[class="highlight"],
+ .sidebarblock .listingblock pre[class^="highlight "],
+ .sidebarblock .listingblock pre.CodeRay,
+ .sidebarblock .listingblock pre.prettyprint {
+ background: rgb(253, 250, 246);
+ }
+
<style>
<style>