You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@isis.apache.org by mg...@apache.org on 2015/12/13 15:31:15 UTC
[08/52] [abbrv] isis git commit: ISIS-1243: renamed rg.adoc to
rgcms.adoc
http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rg_methods_reserved_manpage-iconName.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_methods_reserved_manpage-iconName.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_methods_reserved_manpage-iconName.adoc
deleted file mode 100644
index 86c836b..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_methods_reserved_manpage-iconName.adoc
+++ /dev/null
@@ -1,36 +0,0 @@
-[[_rg_methods_reserved_manpage-iconName]]
-= `iconName()`
-: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/
-
-
-Every object is represented by an icon; this is based on the domain object's simple name. The xref:ugvw.adoc#[Wicket viewer] searches for the image in the same package as the `.class` file for the domain object.
-
-The `iconName()` allows the icon that to be used to change for individual object instances. These are usually quite subtle, for example to reflect the particular status of an object. The value returned by the `iconName()` method is added as a suffix to the base icon name.
-
-For example, the (non-ASF) http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp] uses this technique to add an overlay for todo items that have been completed:
-
-image::{_imagesdir}reference-methods/reserved/iconName/differing.png[width="200px",link="{_imagesdir}reference-methods/reserved/iconName/differing.png"]
-
-
-
-The screenshot below shows the location of these png icon files:
-
-image::{_imagesdir}reference-methods/reserved/iconName/png-files.png[width="200px",link="{_imagesdir}reference-methods/reserved/iconName/png-files.png"]
-
-
-
-The code to accomplish this is straightforward:
-
-[source,java]
-----
-public class ToDoItem ... {
- public String iconName() {
- return !isComplete() ? "todo" : "done";
- }
- ...
-}
-----
-
-See also xref:rg.adoc#_rg_methods_reserved_manpage-title[`title()`] and xref:rg.adoc#_rg_methods_reserved_manpage-cssClass[`cssClass()`]
http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rg_methods_reserved_manpage-title.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_methods_reserved_manpage-title.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_methods_reserved_manpage-title.adoc
deleted file mode 100644
index 0de6535..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_methods_reserved_manpage-title.adoc
+++ /dev/null
@@ -1,65 +0,0 @@
-[[_rg_methods_reserved_manpage-title]]
-= `title()`
-: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/
-
-
-
-Every object is represented by a title. This appears both as a main header for the object when viewed as well as being used as a hyperlink within properties and collections. It therefore must contain enough information for the end-user to distinguish the object from any others.
-
-This is most commonly done by including some unique key within the title, for example a customer's SSN, or an order number, and so forth. However note that Apache Isis itself does _not_ require the title to be unique; it is merely recommended in most cases.
-
-An object's title can be constructed in various ways, but the most flexible is to use the `title()` method. The signature of this method is usually:
-
-[source,java]
-----
-public String title() { ... }
-----
-
-Note that Apache Isis' xref:ugbtb.adoc#_ugbtb_more-advanced_i18n[i18n support] extends this so that titles can also be internationalized.
-
-For example, the (non-ASF) http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp] uses this technique to add an overlay for todo items that have been completed:
-
-[source,java]
-----
-public String title() {
- final TitleBuffer buf = new TitleBuffer(); // <1>
- buf.append(getDescription());
- if (isComplete()) { // <2>
- buf.append("- Completed!");
- } else {
- try {
- final LocalDate dueBy = wrapperFactory.wrap(this).getDueBy(); // <3>
- if (dueBy != null) {
- buf.append(" due by", dueBy);
- }
- } catch(final HiddenException ignored) { // <4>
- }
- }
- return buf.toString();
-}
-----
-<1> simple xref:rg.adoc#_rg_classes_utility_manpage-TitleBuffer[tility class] to help construct the title string
-<2> imperative conditional logic
-<3> using the xref:rgsvc.adoc#_rgsvc-api_WrapperFactory[`WrapperFactory`] to determine if the `dueBy` field is visible for this user ...
-<4> ... but ignore if not
-
-As the example above shows, the implementation can be as complex as you like.
-
-In many cases, though, you may be able to use the xref:rgant.adoc#_rgant-Title[`@Title`] annotation.
-
-
-See also xref:rg.adoc#_rg_methods_reserved_manpage-iconName[`iconName()`] and xref:rg.adoc#_rg_methods_reserved_manpage-cssClass[`cssClass()`]
-
-
-
-
-
-
-
-
-
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rg_methods_reserved_manpage-validate.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_methods_reserved_manpage-validate.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_methods_reserved_manpage-validate.adoc
deleted file mode 100644
index 257cbf6..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_methods_reserved_manpage-validate.adoc
+++ /dev/null
@@ -1,27 +0,0 @@
-[[_rg_methods_reserved_manpage-validate]]
-= `validate()`
-: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 `validate()` method is used to specify that invariants pertaining to an object's state are enforced.
-
-
-[WARNING]
-====
-(As of 1.8.0) there are known limitations with this functionality. Invariants are enforced when an object is initially created and when it is edited, however invariants are currently _not_ enforced if an action is invoked.
-====
-
-
-The signature of the method is:
-
-[source,java]
-----
-public String validate() { ... }
-----
-
-where the returned string is the reason that the invocation is vetoed.
-
-Note that Apache Isis' xref:ugbtb.adoc#_ugbtb_more-advanced_i18n[i18n support] extends this so that the returned reason can also be internationalized.
http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rg_schema-aim.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_schema-aim.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_schema-aim.adoc
deleted file mode 100644
index 67dff77..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_schema-aim.adoc
+++ /dev/null
@@ -1,97 +0,0 @@
-[[_rg_schema-aim]]
-= Action Invocation Memento
-: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 "aim" schema defines the serialized form (or memento) of an action invocation.
-
-Action invocations are captured (in memory rather than in serialized form) when the end-user invokes the action
-"through" the UI, by way of the xref:rgsvc.adoc#_rgsvc-api_CommandContext[CommandContext] service. Using the
-`ActionInvocationMementoDtoUtils` utility class, a service can instantiate `ActionInvocationMementoDto` which can then
-be serialized to/from using the same `ActionInvocationMementoDtoUtils` class.
-
-[source,xml]
-----
-<?xml version="1.0" encoding="UTF-8"?>
-<xs:schema targetNamespace="http://isis.apache.org/schema/aim" <!--1-->
- elementFormDefault="qualified"
- xmlns:xs="http://www.w3.org/2001/XMLSchema"
- xmlns="http://isis.apache.org/schema/aim"
- xmlns:common="http://isis.apache.org/schema/common">
-
- <xs:import namespace="http://isis.apache.org/schema/common" <!--2-->
- schemaLocation="http://isis.apache.org/schema/common/common-1.0.xsd"/>
-
- <xs:element name="actionInvocationMementoDto"> <!--3-->
- <xs:complexType>
- <xs:sequence>
- <xs:element name="metadata">
- <xs:complexType>
- <xs:sequence>
- <xs:element name="transactionId" type="xs:string"/> <!--4-->
- <xs:element name="sequence" type="xs:int"/> <!--5-->
- <xs:element name="timestamp" type="xs:dateTime"/> <!--6-->
- <xs:element name="target" type="common:oidDto"/> <!--7-->
- <xs:element name="targetClass" type="xs:string"/> <!--8-->
- <xs:element name="targetAction" type="xs:string"/> <!--9-->
- <xs:element name="actionIdentifier" type="xs:string"/> <!--10-->
- <xs:element name="user" type="xs:string"/> <!--11-->
- <xs:element name="title" type="xs:string"/> <!--12-->
- </xs:sequence>
- </xs:complexType>
- </xs:element>
- <xs:element name="payload">
- <xs:complexType>
- <xs:sequence>
- <xs:element name="parameters"> <!--13-->
- <xs:complexType>
- <xs:sequence maxOccurs="unbounded">
- <xs:element name="param" type="paramDto"/>
- </xs:sequence>
- <xs:attribute name="num" use="required" type="xs:int"/>
- </xs:complexType>
- </xs:element>
- <xs:element name="return" type="common:valueDto" <!--14-->
- minOccurs="0" maxOccurs="1"/>
- </xs:sequence>
- </xs:complexType>
- </xs:element>
- </xs:sequence>
- </xs:complexType>
- </xs:element>
-
- <xs:complexType name="paramDto"> <!--15-->
- <xs:sequence>
- <xs:element name="value" type="common:valueDto"/> <!--16-->
- </xs:sequence>
- <xs:attribute name="parameterName" use="required" type="xs:string"/> <!--17-->
- <xs:attribute name="parameterType" use="required" type="common:valueType"/>
- <xs:attribute name="null" use="optional" type="xs:boolean"/>
- </xs:complexType>
-</xs:schema>
-----
-<1> the aim schema has a namespace URI of "http://isis.apache.org/schema/aim". Although URIs are not the same as URLs, you will find that the schemas are also downloadable from this location.
-<2> reuses the xref:rg.adoc#_rg_schema-common[common] schema
-<3> definition of the `actionInvocationMementoDto` complex type. This consists of metadata (the transaction identifier, the target object, the initiating user) and the payload (the action parameter/arguments, the return value if known).
-<4> the unique transaction Id (a guid) allocated by the framework for each and every transaction
-<5> a sequence number within the transaction. It is possible for there to be more than one action invocation to be
-<6> when the action was invoked
-<7> target object, as an OID (using `oidDto` from the xref:rg.adoc#_rg_schema-common[common] schema)
-<8> fully qualified class name of the target object, for information only
-<9> name of the action, for information only
-<10> Javadoc style unique identifier for the action.
-<11> User that invoked the action
-<12> title of the target object, for information only
-<13> Collection of parameter/arguments, defined in terms of the `paramDto` complex type (discussed just below)
-<14> The return value of the action, if known (and not void)
-<15> The `paramDto` defines both an action parameter and its corresponding argument values
-<16> The value of the parameter, in other words an argument value
-<17> Metadata about the parameter itself: its name, type, optionality.
-
-[NOTE]
-====
-As of `1.11.0` this schema is not used directly by the framework; in particular `Command#setMemento(...)` sets a similar
-but less formal XML structure. This may change in the future.
-====
http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rg_schema-common.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_schema-common.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_schema-common.adoc
deleted file mode 100644
index b9a5629..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_schema-common.adoc
+++ /dev/null
@@ -1,103 +0,0 @@
-[[_rg_schema-common]]
-= Common Schema
-: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 main purpose of the common schema is to define the `oidDto` complex type: the object's type and its identifier.
-This is basically a formal XML equivalent to the `Bookmark` object obtained from the
-xref:rgsvc.adoc#_rgsvc-api_BookmarkService[`BookmarkService`].
-
-Although simple, this is an enormously powerful concept, in that it represents a URI to any domain object managed by
-a given Apache Isis application. With it, we have the ability to lookup any arbitrary object. Further discussion and
-examples can be found xref:ug.adoc#_ug_core-concepts_building-blocks_oid[here].
-
-
-[source,xml]
-----
-<xs:schema targetNamespace="http://isis.apache.org/schema/common" <!--1-->
- elementFormDefault="qualified"
- xmlns="http://isis.apache.org/schema/common"
- xmlns:xs="http://www.w3.org/2001/XMLSchema">
-
- <xs:complexType name="oidDto"> <!--2-->
- <xs:sequence>
- <xs:element name="objectType" type="xs:string"/> <!--3-->
- <xs:element name="objectIdentifier" type="xs:string"/> <!--4-->
- </xs:sequence>
- <xs:attribute name="objectState" type="bookmarkObjectState" default="persistent"/>
- </xs:complexType>
-
- <xs:simpleType name="bookmarkObjectState"> <!--5-->
- <xs:restriction base="xs:string">
- <xs:enumeration value="persistent"/>
- <xs:enumeration value="transient"/>
- <xs:enumeration value="viewModel"/>
- </xs:restriction>
- </xs:simpleType>
- ...
-</xs:schema>
-----
-<1> the common schema has a namespace URI of "http://isis.apache.org/schema/common". Although URIs are not the same as URLs, you will find that the schemas are also downloadable from this location.
-<2> the `oidDto` complex type defines the unique identifier for any domain object: its type, and an identifier. The `objectState` attribute is of type `bookmarkObjectState` and will typically be "transient" or "viewModel"
-<3> the object type, corresponding to either the
-xref:rgant.adoc#_rgant-DomainObject_objectType[`@DomainObject#objectType()`] attribute, or to the (JDO)
-xref:rgant.adoc#_rgant-PersistenceCapable[`@PersistenceCapable`] annotation (`schema` and/or `table`
-attributes), or to the (JDO) xref:rgant.adoc#_rgant-Discriminator[`@Discriminator`] annotation. If none
-is specified, then the fully
-qualified class name will be used.
-<4> the object identifier (aka primary key), converted to string form.
-<5> the `bookmarkObjectState` enumerates the possible persistence states of the referenced object. Although "transient" is shown,
-in practice the only types of objects will be "persistent" (entities) or "viewModel".
-
-The `oidDto` complex type is used in two specific places by the framework:
-
-* first, as a means of serializing JAXB view model/DTOs (annotated with
-xref:rgant.adoc#_rgant-XmlRootElement[`@XmlRootElement`]), that reference domain entities. +
-+
-These references are serialized instead into OIDs
-
-* second, as references to the target of action invocations, as described by the
-xref:rg.adoc#_rg_schema-aim[action invocation memento] schema. +
-+
-They are also used to represent references to any action arguments that take domain object entities.
-
-The common schema also defines two further types: the `valueDto` complex type and the `valueType` simple type:
-
-[source,xml]
-----
-<xs:schema targetNamespace="http://isis.apache.org/schema/common"
- elementFormDefault="qualified"
- xmlns="http://isis.apache.org/schema/common"
- xmlns:xs="http://www.w3.org/2001/XMLSchema">
- ...
- <xs:complexType name="valueDto"> <!--1-->
- <xs:choice minOccurs="0" maxOccurs="1">
- <xs:element name="string" type="xs:string"/>
- <xs:element name="byte" type="xs:byte"/>
- <xs:element name="short" type="xs:short"/>
- ...
- <xs:element name="localTime" type="xs:time"/>
- <xs:element name="reference" type="oidDto"/>
- </xs:choice>
- </xs:complexType>
-
- <xs:simpleType name="valueType"> <!--2-->
- <xs:restriction base="xs:string">
- <xs:enumeration value="string"/>
- <xs:enumeration value="byte"/>
- <xs:enumeration value="short"/>
- ...
- <xs:enumeration value="isisApplibClob"/>
- <xs:enumeration value="reference"/>
- </xs:restriction>
- </xs:simpleType>
-</xs:schema>
-----
-
-These two type definitions are just building blocks, also used within the
-xref:rg.adoc#_rg_schema-aim[action iInvocation memento] schema. The first, `valueDto` is intended to hold any valid
-value, eg of an argument to an action. The second, `valueType`, enumerates the different types of vales, eg of a
-formal parameter to an action.
http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rg_schema.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_schema.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_schema.adoc
deleted file mode 100644
index b7e97ee..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_schema.adoc
+++ /dev/null
@@ -1,24 +0,0 @@
-[[_rg_schema]]
-= Schema
-: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/
-
-
-Most applications need to integrate with other apps in the enterprise. To facilitate such integration scenarios,
-Apache Isis defines two standard XSD schemas:
-
-* the xref:rg.adoc#_rg_schema-common[common schema], which defines the `oidDto` complex type: the object's type and its identifier. +
-+
-It also defines some two further XSD types, which are building blocks used in...
-
-* the xref:rg.adoc#_rg_schema-aim[action memento invocation] schema, which allows action invocations to be captured
-and reified. +
-+
-The (non-ASF) http://github.com/isisaddons/isis-module-publishmq[Isis addons' publishmq] module uses this XML format
-to publish messages onto an link:http://activemq.apache.org[Apache ActiveMQ] message queue.
-
-The sections below discuss these schemas in more detail.
-
-include::_rg_schema-common.adoc[leveloffset=+1]
-include::_rg_schema-aim.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgant-Collection_editing.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-Collection_editing.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-Collection_editing.adoc
index ed198ea..7b148d2 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-Collection_editing.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-Collection_editing.adoc
@@ -25,7 +25,7 @@ Whether a collection is enabled or disabled depends upon these factors:
* else, then the value of the `@Collection(editing=...)` attribute itself.
-* else, the result of invoking any supporting xref:rg.adoc#_rg_methods_prefixes_manpage-disable[`disable...()`] supporting methods
+* else, the result of invoking any supporting xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-disable[`disable...()`] supporting methods
Thus, to make a collection read-only even if the object would otherwise be editable, use:
http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgant-Column.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-Column.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-Column.adoc
index 9cca7cc..2069ee1 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-Column.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-Column.adoc
@@ -116,7 +116,7 @@ public class PartyRelationship {
== Mapping ``Blob``s and ``Clob``s
-Isis provides custom value types for xref:rg.adoc#_rg_classes_value-types_manpage-Blob[`Blob`]s and xref:rg.adoc#_rg_classes_value-types_manpage-Clob[`Clob`]s. These value types have multiple internal fields, meaning that they corresponding to multiple columns in the database. Mapping this correctly requires using `@Column` within JDO's `@Persistent` annotation.
+Isis provides custom value types for xref:rgcms.adoc#_rgcms_classes_value-types_manpage-Blob[`Blob`]s and xref:rgcms.adoc#_rgcms_classes_value-types_manpage-Clob[`Clob`]s. These value types have multiple internal fields, meaning that they corresponding to multiple columns in the database. Mapping this correctly requires using `@Column` within JDO's `@Persistent` annotation.
For example, here's how to map a `Blob` (taken from (non-ASF) http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp]):
http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObjectLayout_cssClassFa.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObjectLayout_cssClassFa.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObjectLayout_cssClassFa.adoc
index cd3cc5e..0ed1955 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObjectLayout_cssClassFa.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObjectLayout_cssClassFa.adoc
@@ -10,7 +10,7 @@ The `cssClassFa()` attribute is used to specify the name of a link:http://fortaw
These attributes can also be applied to xref:rgant.adoc#_rgant-ViewModelLayout_cssClassFa[view models] to specify the object's icon, and to xref:rgant.adoc#_rgant-ActionLayout_cssClassFa[actions] to specify an icon for the action's representation as a button or menu item.
-If necessary the icon specified can be overridden by a particular object instance using the xref:rg.adoc#_rg_methods_reserved_manpage-iconName[`iconName()`] method.
+If necessary the icon specified can be overridden by a particular object instance using the xref:rgcms.adoc#_rgcms_methods_reserved_manpage-iconName[`iconName()`] method.
http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObjectLayout_cssClassUiEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObjectLayout_cssClassUiEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObjectLayout_cssClassUiEvent.adoc
index 32890ed..31d1a56 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObjectLayout_cssClassUiEvent.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObjectLayout_cssClassUiEvent.adoc
@@ -7,7 +7,7 @@
Whenever a domain object is to be rendered, the framework fires off an CSS class UI event to obtain a CSS class to use
in any wrapping ``<div>``s and ``<span>``s that render the domain object. This is as an alternative to implementing
-xref:rg.adoc#_rg_methods_reserved_manpage-cssClass[`cssClass()`] reserved method. (If `cssClass()` is present, then
+xref:rgcms.adoc#_rgcms_methods_reserved_manpage-cssClass[`cssClass()`] reserved method. (If `cssClass()` is present, then
it will take precedence).
Subscribers subscribe through the xref:rgsvc.adoc#_rgsvc-api_EventBusService[`EventBusService`] and can
http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObjectLayout_iconUiEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObjectLayout_iconUiEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObjectLayout_iconUiEvent.adoc
index 2b0c525..2d20e91 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObjectLayout_iconUiEvent.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObjectLayout_iconUiEvent.adoc
@@ -7,7 +7,7 @@
Whenever a domain object is to be rendered, the framework fires off an icon UI event to obtain an icon (name) for the
object (if possible). This is as an alternative to implementing
-xref:rg.adoc#_rg_methods_reserved_manpage-iconName[`iconName()`] reserved method. (If `iconName()` is present, then
+xref:rgcms.adoc#_rgcms_methods_reserved_manpage-iconName[`iconName()`] reserved method. (If `iconName()` is present, then
it will take precedence).
Subscribers subscribe through the xref:rgsvc.adoc#_rgsvc-api_EventBusService[`EventBusService`] and can
http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObjectLayout_titleUiEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObjectLayout_titleUiEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObjectLayout_titleUiEvent.adoc
index 3e5a4cd..5cf0051 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObjectLayout_titleUiEvent.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObjectLayout_titleUiEvent.adoc
@@ -6,7 +6,7 @@
Whenever a domain object is to be rendered, the framework fires off a title UI event to obtain a title for the object.
-This is as an alternative to implementing xref:rg.adoc#_rg_methods_reserved_manpage-title[`title()`] reserved method, or
+This is as an alternative to implementing xref:rgcms.adoc#_rgcms_methods_reserved_manpage-title[`title()`] reserved method, or
using the xref:rgant.adoc#_rgant-Title[`@Title`] annotation, within the class itself. (If either
`title()` or `@Title` are present, then they will take precedence).
http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject_autoCompleteRepository.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject_autoCompleteRepository.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject_autoCompleteRepository.adoc
index f8fbaa1..95f7899 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject_autoCompleteRepository.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject_autoCompleteRepository.adoc
@@ -13,7 +13,7 @@ For example, this might search for a customer by their name or number. Or it co
[TIP]
====
-If you require additional control - for example restricting the returned results based on the object being interacted with - then use the xref:rg.adoc#_rg_methods_prefixes_manpage-autoComplete[`autoComplete...()`] supporting method instead.
+If you require additional control - for example restricting the returned results based on the object being interacted with - then use the xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-autoComplete[`autoComplete...()`] supporting method instead.
====
http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject_bounded.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject_bounded.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject_bounded.adoc
index 6ae3cec..6ee3f4b 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject_bounded.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject_bounded.adoc
@@ -28,7 +28,7 @@ public class Currency {
[TIP]
====
-There is nothing to prevent you from using this attribute for regular mutable entities, and indeed this is sometimes worth doing during early prototyping. However, if there is no realistic upper bound to the number of instances of an entity that might be created, generally you should use xref:rg.adoc#_rg_methods_prefixes_manpage-autoComplete[`autoComplete...()`] supporting method or the xref:rgant.adoc#_rgant-DomainObject_autoCompleteRepository[`@DomainObject#autoCompleteRepository()`] attribute instead.
+There is nothing to prevent you from using this attribute for regular mutable entities, and indeed this is sometimes worth doing during early prototyping. However, if there is no realistic upper bound to the number of instances of an entity that might be created, generally you should use xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-autoComplete[`autoComplete...()`] supporting method or the xref:rgant.adoc#_rgant-DomainObject_autoCompleteRepository[`@DomainObject#autoCompleteRepository()`] attribute instead.
====
http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject_nature.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject_nature.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject_nature.adoc
index fa39886..7ba07cd 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject_nature.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject_nature.adoc
@@ -53,7 +53,7 @@ indicates that the domain object is conceptually part of the application layer,
The identity of an inmemory entity is determined solely by the state of entity's properties. The framework will automatically recreate the domain object each time it is interacted with.
-Those natures that indicate the domain object is an entity (of some sort or another) mean then that the domain object is considered to be part of the domain model layer. As such the domain object's class cannot be annotated with xref:rgant.adoc#_rgant-ViewModel[`@ViewModel`] or implement the xref:rg.adoc#_rg_classes_super_manpage-ViewModel[`ViewModel`] interface.
+Those natures that indicate the domain object is an entity (of some sort or another) mean then that the domain object is considered to be part of the domain model layer. As such the domain object's class cannot be annotated with xref:rgant.adoc#_rgant-ViewModel[`@ViewModel`] or implement the xref:rgcms.adoc#_rgcms_classes_super_manpage-ViewModel[`ViewModel`] interface.
[NOTE]
http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject_persistingLifecycleEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject_persistingLifecycleEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject_persistingLifecycleEvent.adoc
index de891eb..76a25ba 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject_persistingLifecycleEvent.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject_persistingLifecycleEvent.adoc
@@ -17,7 +17,7 @@ link:https://lucene.apache.org/[Apache Lucene] or similar.
====
Another use case is to maintain "last updated by"/"last updated at" properties. While you can roll your own, note that
the framework provides built-in support for this use case through the
-xref:rg.adoc#_rg_classes_roles_manpage-Timestampable[`Timestampable`] role interface.
+xref:rgcms.adoc#_rgcms_classes_roles_manpage-Timestampable[`Timestampable`] role interface.
====
By default the event raised is `ObjectPersistingEvent.Default`. For example:
http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject_removingLifecycleEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject_removingLifecycleEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject_removingLifecycleEvent.adoc
index 567b56c..9390c3a 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject_removingLifecycleEvent.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject_removingLifecycleEvent.adoc
@@ -17,7 +17,7 @@ using link:https://lucene.apache.org/[Apache Lucene] or similar.
====
Another use case is to maintain "last updated by"/"last updated at" properties. While you can roll your own, note that
the framework provides built-in support for this use case through the
-xref:rg.adoc#_rg_classes_roles_manpage-Timestampable[`Timestampable`] role interface.
+xref:rgcms.adoc#_rgcms_classes_roles_manpage-Timestampable[`Timestampable`] role interface.
====
By default the event raised is `ObjectRemovingEvent.Default`. For example:
http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject_updatingLifecycleEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject_updatingLifecycleEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject_updatingLifecycleEvent.adoc
index 38f579b..ef1c456 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject_updatingLifecycleEvent.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject_updatingLifecycleEvent.adoc
@@ -17,7 +17,7 @@ using link:https://lucene.apache.org/[Apache Lucene] or similar.
====
Another use case is to maintain "last updated by"/"last updated at" properties. While you can roll your own, note that
the framework provides built-in support for this use case through the
-xref:rg.adoc#_rg_classes_roles_manpage-Timestampable[`Timestampable`] role interface.
+xref:rgcms.adoc#_rgcms_classes_roles_manpage-Timestampable[`Timestampable`] role interface.
====
By default the event raised is `ObjectUpdatingEvent.Default`. For example:
http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgant-MinLength.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-MinLength.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-MinLength.adoc
index 3109f01..d896a6c 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-MinLength.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-MinLength.adoc
@@ -5,7 +5,7 @@
:_imagesdir: images/
-The `@MinLength` annotation is used to specify the minimum number of characters in a search of an xref:rg.adoc#_rg_methods_prefixes_manpage-autoComplete[`autoComplete...()`] supporting method.
+The `@MinLength` annotation is used to specify the minimum number of characters in a search of an xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-autoComplete[`autoComplete...()`] supporting method.
For example:
http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgant-Parameter.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-Parameter.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-Parameter.adoc
index 79f3150..a191b90 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-Parameter.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-Parameter.adoc
@@ -27,7 +27,7 @@ The table below summarizes the annotation's attributes.
|Positive integer
|Deprecated; use xref:rgant.adoc#_rgant-MinLength[`@MinLength`] instead. +
-Can be used to specify the minimum length for xref:rg.adoc#_rg_methods_prefixes_manpage-autoComplete[`autoComplete...()`] supporting method; but because this _is a_ supporting method rather than the action method itself, we now feel it is misleading to use the `@Parameter` annotation in this situation.
+Can be used to specify the minimum length for xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-autoComplete[`autoComplete...()`] supporting method; but because this _is a_ supporting method rather than the action method itself, we now feel it is misleading to use the `@Parameter` annotation in this situation.
|xref:rgant.adoc#_rgant-Parameter_mustSatisfy[`mustSatisfy()`]
http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgant-PostConstruct.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-PostConstruct.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-PostConstruct.adoc
index 46e2fde..78e4cf7 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-PostConstruct.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-PostConstruct.adoc
@@ -58,7 +58,7 @@ public class MySubscribingService {
[TIP]
====
-In this particular use case, it is generally simpler to just subclass from xref:rg.adoc#_rg_classes_super_manpage-AbstractSubscriber[`AbstractSubscriber`].
+In this particular use case, it is generally simpler to just subclass from xref:rgcms.adoc#_rgcms_classes_super_manpage-AbstractSubscriber[`AbstractSubscriber`].
====
http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgant-PreDestroy.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-PreDestroy.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-PreDestroy.adoc
index a394c01..268846a 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-PreDestroy.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-PreDestroy.adoc
@@ -43,7 +43,7 @@ public class MySubscribingService {
[TIP]
====
-In this particular use case, it is generally simpler to just subclass from xref:rg.adoc#_rg_classes_super_manpage-AbstractSubscriber[`AbstractSubscriber`].
+In this particular use case, it is generally simpler to just subclass from xref:rgcms.adoc#_rgcms_classes_super_manpage-AbstractSubscriber[`AbstractSubscriber`].
====
Other use cases include obtaining connections to external datasources, eg subscribing to an ActiveMQ router, say, or initializing/cleaning up a background scheduler such as Quartz.
http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgant-Property_editing.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-Property_editing.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-Property_editing.adoc
index d4b47ca..f28a5d2 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-Property_editing.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-Property_editing.adoc
@@ -17,7 +17,7 @@ Whether a property is enabled or disabled depends upon these factors:
* else, then the value of the `@Property(editing=...)` attribute itself
-* else, the result of invoking any supporting xref:rg.adoc#_rg_methods_prefixes_manpage-disable[`disable...()`] supporting methods
+* else, the result of invoking any supporting xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-disable[`disable...()`] supporting methods
Thus, to make a property read-only even if the object would otherwise be editable, use:
http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgant-ViewModelLayout_cssClassFa.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-ViewModelLayout_cssClassFa.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-ViewModelLayout_cssClassFa.adoc
index 8a49579..e653485 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-ViewModelLayout_cssClassFa.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-ViewModelLayout_cssClassFa.adoc
@@ -12,7 +12,7 @@ The `cssClassFa()` attribute is used to specify the name of a link:http://fortaw
These attribute can also be applied to xref:rgant.adoc#_rgant-DomainObjectLayout_cssClassFa[domain objects] to specify the object's icon, and to xref:rgant.adoc#_rgant-ActionLayout_cssClassFa[actions] to specify an icon for the action's representation as a button or menu item.
-If necessary the icon specified can be overridden by a particular object instance using the xref:rg.adoc#_rg_methods_reserved_manpage-iconName[`iconName()`] method.
+If necessary the icon specified can be overridden by a particular object instance using the xref:rgcms.adoc#_rgcms_methods_reserved_manpage-iconName[`iconName()`] method.
http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgant-XmlRootElement.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-XmlRootElement.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-XmlRootElement.adoc
index 058d1b2..0e36b15 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-XmlRootElement.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-XmlRootElement.adoc
@@ -13,7 +13,7 @@ A view model is a non-persisted domain object whose state is converted to/from a
JAXB-annotated object this memento is its XML representation. JAXB generally requires that the root element of the
XML representation is annotated with `@XmlRootElement`. Apache Isis makes this a mandatory requirement.
-In comparison to using either the xref:rg.adoc#_rg_classes_super_manpage-ViewModel[`ViewModel`] interface or the
+In comparison to using either the xref:rgcms.adoc#_rgcms_classes_super_manpage-ViewModel[`ViewModel`] interface or the
xref:rgant.adoc#_rgant-ViewModel[`@ViewModel`] annotation, using `@XmlRootElement` has a couple of
significant advantages:
@@ -33,7 +33,7 @@ all the code by hand
The main disadvantages of using JAXB-annotated view models is that any referenced persistent entity must be annotated
with the xref:rgant.adoc#_rgant-XmlJavaTypeAdapter[`@XmlJavaTypeAdapter`], using the
framework-provided `PersistentEntityAdapter`. This adapter converts any references to such domain entities using the
-`oidDto` complex type (as defined by the Apache Isis xref:rg.adoc#_rg_schema-common[common schema]):
+`oidDto` complex type (as defined by the Apache Isis xref:rgcms.adoc#_rgcms_schema-common[common schema]):
the object's type and its identifier.
[TIP]
@@ -75,7 +75,7 @@ Although (like any other viewmodel) a JAXB-annotated can have behaviour (actions
the DTO "clean", just focused on specifying the data contract.
Behaviour can therefore be provided using xref:ugbtb.adoc#_ugbtb_more-advanced_decoupling_mixins[mixins] (annotated with
-xref:rgant.adoc#_rgant-Mixin[`@Mixin`]), while xref:rg.adoc#_rg_classes_uievent[UI events] can be used
+xref:rgant.adoc#_rgant-Mixin[`@Mixin`]), while xref:rgcms.adoc#_rgcms_classes_uievent[UI events] can be used
to obtain title, icons and so on.
For a more complete discussion of writing JAXB view models/DTOs, see xref:ugbtb.adoc#_ugbtb_more-advanced_view-models[this topic]
http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgcfg_configuring-core.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcfg_configuring-core.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcfg_configuring-core.adoc
index 03fbc56..925f032 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgcfg_configuring-core.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcfg_configuring-core.adoc
@@ -214,7 +214,7 @@ See xref:ugbtb.adoc#_ugbtb_programming-model_custom-validator[Custom Validator]
Each entry can be optionally prefixed by "n:" specifying the relative order on the menu (corresponds to xref:rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`]).
-This property is IGNORED if the xref:rgcfg.adoc#_rgcfg_configuring-components[`isis.appManifest`] configuration property is specified, or if an xref:rg.adoc#_rg_classes_super_manpage-AppManifest[`AppManifest`] is provided programmatically.
+This property is IGNORED if the xref:rgcfg.adoc#_rgcfg_configuring-components[`isis.appManifest`] configuration property is specified, or if an xref:rgcms.adoc#_rgcms_classes_super_manpage-AppManifest[`AppManifest`] is provided programmatically.
|`isis.services.` +
@@ -347,7 +347,7 @@ This implementation provides a default set of recognizers to convert RDBMS const
|fully qualified package names (CSV)
|to search for domain services (including all subpackages).
-This property is IGNORED if the xref:rgcfg.adoc#_rgcfg_configuring-components[`isis.appManifest`] configuration property is specified, or if an xref:rg.adoc#_rg_classes_super_manpage-AppManifest[`AppManifest`] is provided programmatically.
+This property is IGNORED if the xref:rgcfg.adoc#_rgcfg_configuring-components[`isis.appManifest`] configuration property is specified, or if an xref:rgcms.adoc#_rgcms_classes_super_manpage-AppManifest[`AppManifest`] is provided programmatically.
|`isis.services.` +
http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgcfg_configuring-datanucleus_disabling-persistence-by-reachability.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcfg_configuring-datanucleus_disabling-persistence-by-reachability.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcfg_configuring-datanucleus_disabling-persistence-by-reachability.adoc
index 4bd6b69..d4ea0df 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgcfg_configuring-datanucleus_disabling-persistence-by-reachability.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcfg_configuring-datanucleus_disabling-persistence-by-reachability.adoc
@@ -14,7 +14,7 @@ However, convenient though this feature is, you may find that it causes performa
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).
+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:rgcms.adoc#_rgcms_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`:
http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgcfg_configuring-datanucleus_eagerly-registering-entities.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcfg_configuring-datanucleus_eagerly-registering-entities.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcfg_configuring-datanucleus_eagerly-registering-entities.adoc
index cbe0c44..232f17d 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgcfg_configuring-datanucleus_eagerly-registering-entities.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcfg_configuring-datanucleus_eagerly-registering-entities.adoc
@@ -14,7 +14,7 @@ Apache Isis is quite happy for the metamodel to be lazily created, and - to be f
The framework thus provide mechanisms to search for all `@PersistenceCapable` entities under specified package(s), and registers them all eagerly. In fact there are two:
-* as of 1.9.0 the recommended (and simpler) approach is to specify an xref:rg.adoc#_rg_classes_super_manpage-AppManifest[`AppManifest`], either as a xref:rgcfg.adoc#_rgcfg_configuring-components[`isis.appManifest`] configuration property or programmatically.
+* as of 1.9.0 the recommended (and simpler) approach is to specify an xref:rgcms.adoc#_rgcms_classes_super_manpage-AppManifest[`AppManifest`], either as a xref:rgcfg.adoc#_rgcfg_configuring-components[`isis.appManifest`] configuration property or programmatically.
* for earlier versions the `isis.persistor.datanucleus.RegisterEntities.packagePrefix` configuration property can be specified. To bootstrap as a webapp this is usually specified in `persistor_datanucleus.properties`. (This is also supported in 1.9.0 if no `AppManifest` is specified. For integration testing this can be specified programatically.
http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgcfg_configuring-datanucleus_properties.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcfg_configuring-datanucleus_properties.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcfg_configuring-datanucleus_properties.adoc
index d784d71..c53b489 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgcfg_configuring-datanucleus_properties.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcfg_configuring-datanucleus_properties.adoc
@@ -30,7 +30,7 @@ These configuration properties are typically stored in `WEB-INF/persistor_datanu
|fully qualified package names (CSV)
|that specifies the entities early rather than allow DataNucleus to find the entities lazily. Further xref:rgcfg.adoc#_rgcfg_configuring-datanucleus_eagerly-registering-entities[discussion below].
-This property is IGNORED if the xref:rgcfg.adoc#_rgcfg_configuring-components[`isis.appManifest`] configuration property is specified, or if an xref:rg.adoc#_rg_classes_super_manpage-AppManifest[`AppManifest`] is provided programmatically.
+This property is IGNORED if the xref:rgcfg.adoc#_rgcfg_configuring-components[`isis.appManifest`] configuration property is specified, or if an xref:rgcms.adoc#_rgcms_classes_super_manpage-AppManifest[`AppManifest`] is provided programmatically.
|`isis.persistor.datanucleus.` +
http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgcfg_specifying-components.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcfg_specifying-components.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcfg_specifying-components.adoc
index f51b24f..d1a7176 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgcfg_specifying-components.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcfg_specifying-components.adoc
@@ -11,7 +11,7 @@ Bootstrapping an Apache Isis application involves identifying both:
* the major components (authentication, persistence mechanisms, viewers) of Apache Isis, and also
* specifying the domain services and persistent entities that make up the application itself.
-As of 1.9.0 there are two different ways to perform this bootstrapping. The recommended (newer) approach is to use an xref:rg.adoc#_rg_classes_super_manpage-AppManifest[`AppManifest`], specified either programmatically or through the configuration properties. This allows the components, services and entities to be specified from a single class. The alternative (and older, pre 1.9.0) approach is to specify this information individually, through configuration properties.
+As of 1.9.0 there are two different ways to perform this bootstrapping. The recommended (newer) approach is to use an xref:rgcms.adoc#_rgcms_classes_super_manpage-AppManifest[`AppManifest`], specified either programmatically or through the configuration properties. This allows the components, services and entities to be specified from a single class. The alternative (and older, pre 1.9.0) approach is to specify this information individually, through configuration properties.
To specify the `AppManifest` as a configuration property, use:
@@ -49,7 +49,7 @@ If the `AppManifest` approach is _not_ being used, then the following configurat
(`_shiro_`)
|`o.a.i.core.runtime.authentication.` `AuthenticationManagerInstaller` +
-This property is IGNORED if the `isis.appManifest` configuration property is specified, or if an xref:rg.adoc#_rg_classes_super_manpage-AppManifest[`AppManifest`] is provided programmatically.
+This property is IGNORED if the `isis.appManifest` configuration property is specified, or if an xref:rgcms.adoc#_rgcms_classes_super_manpage-AppManifest[`AppManifest`] is provided programmatically.
|`isis.authorization`
@@ -57,7 +57,7 @@ This property is IGNORED if the `isis.appManifest` configuration property is spe
(`_shiro_`)
|`o.a.i.core.runtime.authorization.` `AuthorizationManagerInstaller` +
-This property is IGNORED if the `isis.appManifest` configuration property is specified, or if an xref:rg.adoc#_rg_classes_super_manpage-AppManifest[`AppManifest`] is provided programmatically.
+This property is IGNORED if the `isis.appManifest` configuration property is specified, or if an xref:rgcms.adoc#_rgcms_classes_super_manpage-AppManifest[`AppManifest`] is provided programmatically.
|`isis.persistor`
|`datanucleus`
@@ -80,7 +80,7 @@ The mechanism to discover and load domain services:
* Otherwise an alternative implementation of the `o.a.i.core.runtime.services.ServicesInstaller` internal API can be provided. +
-This property is IGNORED if the `isis.appManifest` configuration property is specified, or if an xref:rg.adoc#_rg_classes_super_manpage-AppManifest[`AppManifest`] is provided programmatically.
+This property is IGNORED if the `isis.appManifest` configuration property is specified, or if an xref:rgcms.adoc#_rgcms_classes_super_manpage-AppManifest[`AppManifest`] is provided programmatically.
|===
http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes.adoc
new file mode 100644
index 0000000..72964eb
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes.adoc
@@ -0,0 +1,23 @@
+[[_rgcms_classes]]
+= Classes and Interfaces
+: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 chapter describes the usage of various classes and interfaces that are not otherwise associated with xref:rgsvc.adoc#_rgsvc-api[domain] xref:rgsvc.adoc#_rgsvc-spi[services], xref:ug.adoc#_ug_object-layout[object layout] or xref:rgcfg.adoc#_rgcfg[configuration].
+
+
+include::_rgcms_classes_AppManifest-bootstrapping.adoc[leveloffset=+1]
+include::_rgcms_classes_super.adoc[leveloffset=+1]
+include::_rgcms_classes_domainevent.adoc[leveloffset=+1]
+include::_rgcms_classes_uievent.adoc[leveloffset=+1]
+include::_rgcms_classes_lifecycleevent.adoc[leveloffset=+1]
+include::_rgcms_classes_value-types.adoc[leveloffset=+1]
+include::_rgcms_classes_utility.adoc[leveloffset=+1]
+include::_rgcms_classes_spec.adoc[leveloffset=+1]
+include::_rgcms_classes_i18n.adoc[leveloffset=+1]
+include::_rgcms_classes_contributee.adoc[leveloffset=+1]
+include::_rgcms_classes_roles.adoc[leveloffset=+1]
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_AppManifest-bootstrapping.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_AppManifest-bootstrapping.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_AppManifest-bootstrapping.adoc
new file mode 100644
index 0000000..25fd561
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_AppManifest-bootstrapping.adoc
@@ -0,0 +1,282 @@
+[[_rgcms_classes_AppManifest-bootstrapping]]
+= `AppManifest` (bootstrapping)
+: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 describes how to implement the `AppManifest` interface to bootstrap both an Apache Isis web application, and also its integration tests.
+
+
+
+== API
+
+
+The `AppManifest` interface allows the constituent parts of an application to be defined programmatically, most specifically the packages that contain domain services and/or persistent entities. Its API is defined as:
+
+[source,java]
+----
+public interface AppManifest {
+ public List<Class<?>> getModules(); // <1>
+ public List<Class<?>> getAdditionalServices(); // <2>
+ public String getAuthenticationMechanism(); // <3>
+ public String getAuthorizationMechanism(); // <4>
+ public List<Class<? extends FixtureScript>> getFixtures(); // <5>
+ public Map<String,String> getConfigurationProperties(); // <6>
+}
+----
+<1> Must return a non-null list of classes, each of which representing the root of one of the modules containing services and possibly entities, which together makes up the running application.
+<2> If non-`null`, overrides the value of `isis.services` configuration property to specify a list of additional classes to be instantiated as domain services (over and above the domain services defined via `getModules()` method.
+<3> If non-`null`, overrides the value of `isis.authentication` configuration property to specify the authentication mechanism.
+<4> If non-`null`, overrides the value of `isis.authorization` configuration property to specify the authorization mechanism.
+<5> If non-`null`, overrides the value of `isis.fixtures` configuration property to specify a fixture script to be installed.
+<6> Overrides for any other configuration properties.
+
+The following sections describe each of these methods in a little more detail.
+
+
+
+
+=== `getModules()`
+
+The most significant method (the only one which must return a non-`null` value) is the `getModules()` method. Each module is identified by a class; the framework simply uses that class' package as the root to search for domain services (annotated with xref:rgant.adoc#_rgant-DomainService[`@DomainService`]) and entities (annotated with xref:rgant.adoc#_rgant-PersistenceCapable[`@PersistenceCapable`]). Generally there is one such module class per Maven module.
+
+A module class for a domain module might for example be defined as:
+
+[source,java]
+----
+package com.mycompany.myapp.dom;
+public final class MyAppDomainModule {
+ private MyAppDomainModule() {}
+}
+----
+
+This tells the framework that the package and subpackages under `com.mycompany.myapp.dom` should be searched for domain services and entities.
+
+As is perhaps apparent, the `getModules()` method replaces and overrides both the `isis.services.ServicesInstallerFromAnnotation.packagePrefix` key (usually found in the `isis.properties` file) and also the`isis.persistor.datanucleus.RegisterEntities.packagePrefix` key (usually found in the `persistor_datanucleus.properties` file). The value of the `isis.services-installer` configuration property is also ignored.
+
+For example, the (non-ASF) http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp] defines the following:
+
+[source,java]
+----
+@Override
+public List<Class<?>> getModules() {
+ return Arrays.asList(
+ ToDoAppDomainModule.class,
+ ToDoAppFixtureModule.class,
+ ToDoAppAppModule.class,
+ org.isisaddons.module.audit.AuditModule.class,
+ org.isisaddons.module.command.CommandModule.class,
+ org.isisaddons.module.devutils.DevUtilsModule.class,
+ org.isisaddons.module.docx.DocxModule.class,
+ org.isisaddons.module.publishing.PublishingModule.class,
+ org.isisaddons.module.sessionlogger.SessionLoggerModule.class,
+ org.isisaddons.module.settings.SettingsModule.class,
+ org.isisaddons.wicket.gmap3.cpt.service.Gmap3ServiceModule.class
+ );
+}
+----
+
+As can be seen, the various (non-ASF) link:http://isisaddons.org[Isis Addons] modules also each provide a module class that can be easily referenced.
+
+
+=== `getAdditionalServices()`
+
+We normally we recommend that services are defined exclusively through `getModules()`, and that this method should therefore return an empty list. However, there are certain use cases where the a service must be explicitly specified either because the service required does not (for whatever reason) have a xref:rgant.adoc#_rgant-DomainService[`@DomainService`] annotation.
+
+For example, the (non-ASF) http://github.com/isisaddons/isis-module-security[Isis addons' security] module (v1.9.0) allows the policy to evaluate conflicting permissions to be specified by explicitly registering either the `PermissionsEvaluationServiceAllowBeatsVeto` domain service or the `PermissionsEvaluationServiceVetoBeatsAllow` domain service:
+
+[source,java]
+----
+@Override
+public List<Class<?>> getAdditionalServices() {
+ return Arrays.asList(
+ org.isisaddons.module.security.dom.permission.PermissionsEvaluationServiceVetoBeatsAllow.class
+ );
+}
+----
+
+If this method returns a non-`null` value, then it overrides the value of `isis.services` configuration property.
+
+
+
+
+=== `getAuthenticationMechanism()`
+
+If non-`null`, this method specifies the authentication mechanism to use. The valid values are currently `"shiro"` or `"bypass"`. If null is returned then the value of the `isis.authentication` configuration property (in `isis.properties` file) is used instead.
+
+See the xref:ugsec.adoc#[security guide] for further details on configuring shiro or bypass security.
+
+[NOTE]
+====
+This property is ignored for integration tests (which always uses the `"bypass"` mechanism).
+====
+
+
+
+=== `getAuthorizationMechanism()`
+
+If non-`null`, this method specifies the authorization mechanism to use. The valid values are currently `"shiro"` or `"bypass"`. If null is returned then the value of the `isis.authorization` configuration property (in `isis.properties` file) is used instead.
+
+See the xref:ugsec.adoc#[security guide] for further details on configuring shiro or bypass security.
+
+[NOTE]
+====
+This property is ignored for integration tests (which always uses the `"bypass"` mechanism).
+====
+
+
+
+
+=== `getFixtures()`
+
+If non-`null`, this method specifies the fixture script(s) to be run on startup. This is particularly useful when developing or demoing while using an in-memory database.
+
+For example:
+
+[source,java]
+----
+@Override
+public List<Class<? extends FixtureScript>> getFixtures() {
+ return Lists.newArrayList(todoapp.fixture.demo.DemoFixture.class);
+}
+----
+
+
+
+Note that in order for fixtures to be installed it is also necessary to set the `isis.persistor.datanucleus.install-fixtures` key to `true`. This can most easily be done using the `getConfigurationProperties()` method, discussed below.
+
+
+
+=== `getConfigurationProperties()`
+
+This method allow arbitrary other configuration properties to be overridden. One common use case is in conjunction with the `getFixtures()` method, discussed above:
+
+[source,java]
+----
+@Override
+public Map<String, String> getConfigurationProperties() {
+ Map<String, String> props = Maps.newHashMap();
+ props.put("isis.persistor.datanucleus.install-fixtures", "true");
+ return props;
+}
+----
+
+
+
+
+
+
+
+== Bootstrapping
+
+One of the primary goals of the `AppManifest` is to unify the bootstrapping of both integration tests and the webapp. This requires that the integration tests and webapp can both reference the implementation.
+
+We strongly recommend using a `myapp-app` Maven module to hold the implementation of the `AppManifest`. This Maven module can then also hold dependencies which are common to both integration tests and the webapp, specifically the `org.apache.isis.core:isis-core-runtime` and the `org.apache.isis.core:isis-core-wrapper` modules.
+
+We also strongly recommend that any application-layer domain services and view models (code that references persistent domain entities but that is not referenced back) is moved to this `myapp-app` module. This will allow the architectural layering of the overall application to be enforced by Maven.
+
+What then remains is to update the bootstrapping code itself.
+
+
+=== Integration Tests
+
+Bootstrapping integration tests is still performed using the `IsisSystemForTest.Builder`, but very often the bootstrapping code can be substantially simplified (compared to not using an `AppManifest`, that is).
+
+For example, this is the bootstrapping code for the xref:ug.adoc#_ug_getting-started_simpleapp-archetype[SimpleApp archetype] looks something like:
+
+[source,java]
+----
+public class DomainAppSystemInitializer {
+ public static void initIsft() {
+ IsisSystemForTest isft = IsisSystemForTest.getElseNull();
+ if(isft == null) {
+ isft = new IsisSystemForTest.Builder()
+ .withLoggingAt(org.apache.log4j.Level.INFO)
+ .with(new MyAppAppManifest())
+ .with(new IsisConfigurationForJdoIntegTests())
+ .build()
+ .setUpSystem();
+ IsisSystemForTest.set(isft);
+ }
+ }
+}
+----
+
+
+
+
+=== Webapps
+
+To bootstrap an Apache Isis webapp (using the xref:ugvw.adoc#[Wicket viewer]), there are two choices:
+
+* either specify the `AppManifest` by overriding the `IsisWicketApplication#newWicketModule()`, eg: +
++
+[source,java]
+----
+@Override
+protected Module newIsisWicketModule() {
+ final Module isisDefaults = super.newIsisWicketModule();
+ ...
+ final Module overrides = new AbstractModule() {
+ @Override
+ protected void configure() {
+ ...
+ bind(AppManifest.class).toInstance(new MyAppAppManifest());
+ }
+ };
+ return Modules.override(isisDefaults).with(overrides);
+}
+----
+
+* alternatively update `isis.properties`, using the `isis.appManifest` key to specify the `AppManifest` implementation, eg: +
++
+[source,ini]
+----
+isis.appManifest=domainapp.app.MyAppAppManifest
+----
+
+The first (programmatic) approach takes precedence over the second approach (configuration properties).
+
+[TIP]
+====
+If you use the `org.apache.isis.WebServer` class to launch your application from the xref:ugbtb.adoc#_ugbtb_deployment_cmd-line[command line], then note that you can specify the `AppManifest` using the `-m` (or `--manifest`) flag:
+
+[source,ini]
+----
+java org.apache.isis.WebServer -m com.mycompany.myapp.MyAppAppManifestWithFixtures
+----
+
+====
+
+
+
+
+
+
+
+
+
+
+== Subsidiary Goals
+
+There are a number of subsidiary goals of the `AppManifest` class (though as of v1.9.0 these have not yet implemented):
+
+* Allow different integration tests to run with different manifests.
+
+** Normally the running application is shared (on a thread-local) between integration tests. What the framework could do is to be intelligent enough to keep track of the manifest in use for each integration test and tear down the shared state if the "next" test uses a different manifest
+
+* Speed up bootstrapping by only scanning for classes annotated by `@DomainService` and `@PersistenceCapable` once.
+
+* Provide a programmatic way to contribute elements of `web.xml`.
+
+* Provide a programmatic way to configure Shiro security.
+
+* Anticipate the module changes forthcoming in Java 9.
+
+** Eventually we see that the `AppManifest` class acting as an "aggregator", with the list of modules will become Java 9 modules each advertising the types that they export.
+** It might even be possible for ``AppManifest``s to be switched on and off dynamically (eg if Java9 is compatible with OSGi, being one of the design goals).
+
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_contributee.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_contributee.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_contributee.adoc
new file mode 100644
index 0000000..6c39e33
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_contributee.adoc
@@ -0,0 +1,13 @@
+[[_rgcms_classes_contributee]]
+= Contributee
+: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 interfaces listed in this chapter act as contributees; they allow domain services to contribute actions/properties/collections to any domain objects that implement these interfaces.
+
+
+include::_rgcms_classes_contributee_manpage-HasTransactionId.adoc[leveloffset=+1]
+include::_rgcms_classes_contributee_manpage-HasUserName.adoc[leveloffset=+1]
+
http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_contributee_manpage-HasTransactionId.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_contributee_manpage-HasTransactionId.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_contributee_manpage-HasTransactionId.adoc
new file mode 100644
index 0000000..f0c2a76
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_contributee_manpage-HasTransactionId.adoc
@@ -0,0 +1,31 @@
+[[_rgcms_classes_mixins_manpage-HasTransactionId]]
+= `HasTransactionId`
+: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 `HasTransactionId` interface is a mix-in for any domain objects that reference a transaction id, such as
+auditing entries or commands.
+
+The interface is defined is:
+
+[source,java]
+----
+public interface HasTransactionId {
+
+ public UUID getTransactionId(); // <1>
+ public void setTransactionId(final UUID transactionId);
+}
+----
+<1> unique identifier (a GUID) of the transaction in which this interaction occurred.
+
+
+
+Modules that either have domain entity that implement and/or services that contribute this interface are:
+
+* (non-ASF) http://github.com/isisaddons/isis-module-audit[Isis addons' audit] module (`AuditEntry` entity, `AuditingServiceContributions` service)
+* (non-ASF) http://github.com/isisaddons/isis-module-command[Isis addons' command] module (`CommandJdo` entity, `CommandServiceJdoContributions` service)
+* (non-ASF) http://github.com/isisaddons/isis-module-publishing[Isis addons' publishing] module (`PublishedEvent` entity, `PublishingServiceContributions`)
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_contributee_manpage-HasUserName.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_contributee_manpage-HasUserName.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_contributee_manpage-HasUserName.adoc
new file mode 100644
index 0000000..2fb0d4b
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_contributee_manpage-HasUserName.adoc
@@ -0,0 +1,27 @@
+[[_rgcms_classes_mixins_manpage-HasUserName]]
+= `HasUsername`
+: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 `HasUsername` interface is a mix-in for domain objects to be associated with a username. Other services and modules can then contribute actions/collections to render such additional information relating to the activities of the user.
+
+The interface is defined is:
+
+[source,java]
+----
+public interface HasUsername {
+ public String getUsername();
+}
+----
+
+Modules that either have domain entity that implement and/or services that contribute this interface are:
+
+* (non-ASF) http://github.com/isisaddons/isis-module-security[Isis addons' security] module ( `ApplicationUser` entity, `HasUsernameContributions` service)
+* (non-ASF) http://github.com/isisaddons/isis-module-audit[Isis addons' audit] module (`AuditEntry` entity,
+* (non-ASF) http://github.com/isisaddons/isis-module-command[Isis addons' command] module's `CommandJdo` entity, `HasUsernameContributions` service)
+* (non-ASF) http://github.com/isisaddons/isis-module-publishing[Isis addons' publishing] module (`PublishedEvent` entity)
+* (non-ASF) http://github.com/isisaddons/isis-module-sessionlogger[Isis addons' sessionlogger] module (`SessionLogEntry` entity, `HasUsernameContributions` service)
+* (non-ASF) http://github.com/isisaddons/isis-module-settings[Isis addons' settings] module (`UserSettingJdo` entity)
+
http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_domainevent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_domainevent.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_domainevent.adoc
new file mode 100644
index 0000000..6cbfabd
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_domainevent.adoc
@@ -0,0 +1,76 @@
+[[_rgcms_classes_domainevent]]
+= Domain Event Classes
+: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 catalogues the various domain event classes defined by Apache Isis.
+
+These events are broadcast on the xref:rgsvc.adoc#_rgsvc-api_EventBusService[`EventBusService`]. The domain
+events are broadcast as a result of being specified in the xref:rgant.adoc#_rgant-Action_domainEvent[`@Action#domainEvent()`], xref:rgant.adoc#_rgant-Property_domainEvent[`@Property#domainEvent()`] or xref:rgant.adoc#_rgant-Collection_domainEvent[`@Collection#domainEvent()`] attributes.
+
+They are listed in the table below.
+
+.Domain Event Classes
+[cols="2,4a,1,1", options="header"]
+|===
+
+|API
+|Maven Module +
+Impl'n (g: a:)
+|Implementation
+|Notes
+
+
+|xref:rgcms.adoc#_rgcms_classes_domainevent_manpage-AbstractDomainEvent[`o.a.i.applib.` +
+`AbstractDomainEvent`]
+|``o.a.i.core`` +
+``services.eventbus`` +
+``isis-core-applib``
+|(abstract class)
+|Superclass of the other domain events, listed below in this table.
+
+
+|xref:rgcms.adoc#_rgcms_classes_domainevent_manpage-ActionDomainEvent[`o.a.i.applib.` +
+`ActionDomainEvent`]
+|``o.a.i.core`` +
+``services.eventbus`` +
+``isis-core-applib``
+|(abstract class). +
+`ActionDomainEvent.Default` is the concrete implementation used if no `@Action#domainEvent` attribute is specified
+|Broadcast whenever there is an interaction (hide/disable/validate/pre-execute/post-execute) with an object's action.
+
+
+|xref:rgcms.adoc#_rgcms_classes_domainevent_manpage-CollectionDomainEvent[`o.a.i.applib.` +
+`CollectionDomainEvent`]
+|``o.a.i.core`` +
+``services.eventbus`` +
+``isis-core-applib``
+|(abstract class). +
+`CollectionDomainEvent.Default` is the concrete implementation used if no `@Collection#domainEvent` attribute
+is specified.
+|Broadcast whenever there is an interaction (hide/disable/validate/access) with an object's collection.
+
+
+|xref:rgcms.adoc#_rgcms_classes_domainevent_manpage-PropertyDomainEvent[`o.a.i.applib.` +
+`PropertyDomainEvent`]
+|``o.a.i.core`` +
+``services.eventbus`` +
+``isis-core-applib``
+|(abstract class). +
+`PropertyDomainEvent.Default` is the concrete implementation used if no `@Propert#domainEvent` attribute is specified
+|Broadcast whenever there is an interaction (hide/disable/validate/access) with an object's property.
+
+
+
+|===
+
+
+
+
+include::_rgcms_classes_domainevent_manpage-AbstractDomainEvent.adoc[leveloffset=+1]
+include::_rgcms_classes_domainevent_manpage-ActionDomainEvent.adoc[leveloffset=+1]
+include::_rgcms_classes_domainevent_manpage-CollectionDomainEvent.adoc[leveloffset=+1]
+include::_rgcms_classes_domainevent_manpage-PropertyDomainEvent.adoc[leveloffset=+1]
+
http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_domainevent_manpage-AbstractDomainEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_domainevent_manpage-AbstractDomainEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_domainevent_manpage-AbstractDomainEvent.adoc
new file mode 100644
index 0000000..80ed308
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_domainevent_manpage-AbstractDomainEvent.adoc
@@ -0,0 +1,20 @@
+[[_rgcms_classes_domainevent_manpage-AbstractDomainEvent]]
+= `AbstractDomainEvent`
+: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 class is the superclass for all domain events that are raised by the framework when interacting with actions, properties or collections.
+
+Its immediate subclasses are:
+
+* xref:rgcms.adoc#_rgcms_classes_domainevent_manpage-ActionDomainEvent[`ActionDomainEvent`]
+
+* xref:rgcms.adoc#_rgcms_classes_domainevent_manpage-PropertyDomainEvent[`PropertyDomainEvent`]
+
+* xref:rgcms.adoc#_rgcms_classes_domainevent_manpage-CollectionDomainEvent[`CollectionDomainEvent`]
+
+This class defines the `Phase` enum that is common to all domain events (hide/disable/validate/pre-execute/post-execute), and provides methods such as `veto(...)` by which subscribers can influence the interaction (eg hide a collection, disable a property, validate action arguments).
+
+It class also provides `get(...)` and `put(...)` methods that allow adhoc sharing of user data between different phases. One event instance is used for both the hide and disable phases, and a different event instance is shared between validate/pre-execute/post-execute.