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/06/16 07:42:30 UTC
[42/45] isis git commit: ISIS-1133: breaking out reference guide and
devenv guide;
moving appendices' release notes and migration notes to other docs;
improving the documentation page.
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-CollectionLayout_cssClass.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-CollectionLayout_cssClass.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-CollectionLayout_cssClass.adoc
new file mode 100644
index 0000000..fdef77e
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-CollectionLayout_cssClass.adoc
@@ -0,0 +1,36 @@
+[[_rg_annotations_manpage-CollectionLayout_cssClass]]
+= `cssClass()`
+: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 `cssClass()` attribute can be used to render additional CSS classes in the HTML (a wrapping `<div>`) that represents the collection. xref:ug.adoc#_ug_runtime_application-specific_application-css[Application-specific CSS] can then be used to target and adjust the UI representation of that particular element.
+
+This attribute can also be applied to xref:rg.adoc#_rg_annotations_manpage-DomainObjectLayout_cssClass[domain objects], xref:rg.adoc#_rg_annotations_manpage-ViewModelLayout_cssClass[view models], xref:rg.adoc#_rg_annotations_manpage-ActionLayout_cssClass[actions], xref:rg.adoc#_rg_annotations_manpage-PropertyLayout_cssClass[properties] and xref:rg.adoc#_rg_annotations_manpage-ParameterLayout_cssClass[parameters].
+
+
+For example:
+
+[source,java]
+----
+public class ToDoItem {
+ @CollectionLayout(
+ cssClass="x-important"
+ )
+ public SortedSet<ToDoItem> getDependencies() { ... }
+ ...
+}
+----
+
+
+As an alternative to using the annotation, the dynamic xref:rg.adoc#_rg_object-layout_dynamic[`.layout.json`]
+can be used instead, eg:
+
+[source,javascript]
+----
+"dependencies": {
+ "collectionLayout": { "cssClass": "x-important" }
+}
+----
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-CollectionLayout_describedAs.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-CollectionLayout_describedAs.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-CollectionLayout_describedAs.adoc
new file mode 100644
index 0000000..68cafeb
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-CollectionLayout_describedAs.adoc
@@ -0,0 +1,37 @@
+[[_rg_annotations_manpage-CollectionLayout_describedAs]]
+= `describedAs()`
+: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 `describedAs()` attribute is used to provide a short description of the collection to the user. In the xref:ug.adoc#_ug_wicket-viewer[Wicket viewer] it is displayed as a 'tool tip'.
+
+The `describedAs()` attribute can also be specified for xref:rg.adoc#_rg_annotations_manpage-PropertyLayout_describedAs[properties], xref:rg.adoc#_rg_annotations_manpage-ActionLayout_describedAs[actions], xref:rg.adoc#_rg_annotations_manpage-ParameterLayout_describedAs[parameters], xref:rg.adoc#_rg_annotations_manpage-DomainObjectLayout_describedAs[domain objects] and xref:rg.adoc#_rg_annotations_manpage-ViewModelLayout_describedAs[view models].
+
+
+For example:
+
+[source,java]
+----
+public class ToDoItem {
+ @CollectionLayout(
+ describedAs="Other todo items that must be completed before this one")
+ public SortedSet<ToDoItem getDependencies() { ... }
+ ...
+}
+----
+
+
+As an alternative to using the annotation, the dynamic xref:rg.adoc#_rg_object-layout_dynamic[`.layout.json`]
+can be used instead, eg:
+
+[source,javascript]
+----
+"dependencies": {
+ "collectionLayout": {
+ "describedAs": "Other todo items that must be completed before this one"
+ }
+}
+----
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-CollectionLayout_hidden.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-CollectionLayout_hidden.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-CollectionLayout_hidden.adoc
new file mode 100644
index 0000000..654f6d7
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-CollectionLayout_hidden.adoc
@@ -0,0 +1,58 @@
+[[_rg_annotations_manpage-CollectionLayout_hidden]]
+= `hidden()`
+: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 `hidden()` attribute indicates where (in the UI) the collection should be hidden from the user. This attribute can also be applied to xref:rg.adoc#_rg_annotations_manpage-ActionLayout_hidden[actions] and xref:rg.adoc#_rg_annotations_manpage-PropertyLayout_hidden[properties].
+
+
+[TIP]
+====
+It is also possible to use xref:rg.adoc#_rg_annotations_manpage-Collection_hidden[`@Collection#hidden()`] to hide an action at the domain layer. Both options are provided with a view that in the future the view-layer semantics may be under the control of (expert) users, whereas domain-layer semantics should never be overridden or modified by the user.
+====
+
+For example:
+
+[source,java]
+----
+public class ToDoItem {
+ @CollectionLayout(
+ hidden=Where.EVERYWHERE
+ public SortedSet<ToDoItem> getDependencies() { ... }
+ ...
+}
+----
+
+
+The acceptable values for the `where` parameter are:
+
+* `Where.EVERYWHERE` or `Where.ANYWHERE` +
++
+The collection should be hidden everywhere.
+
+* `Where.ANYWHERE` +
++
+Synonym for everywhere.
+
+* `Where.OBJECT_FORMS` +
++
+The collection should be hidden when displayed within an object form.
+
+* `Where.NOWHERE` +
++
+The collection should not be hidden.
+
+The other values of the `Where` enum have no meaning for a collection.
+
+
+As an alternative to using the annotation, the dynamic xref:rg.adoc#_rg_object-layout_dynamic[`.layout.json`]
+can be used instead, eg:
+
+[source,javascript]
+----
+"dependencies": {
+ "collectionLayout": { "hidden": "EVERYWHERE" }
+}
+----
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-CollectionLayout_named.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-CollectionLayout_named.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-CollectionLayout_named.adoc
new file mode 100644
index 0000000..53be3e7
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-CollectionLayout_named.adoc
@@ -0,0 +1,53 @@
+[[_rg_annotations_manpage-CollectionLayout_named]]
+= `named()`
+: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 `named()` attribute explicitly specifies the collection's name, overriding the name that would normally be inferred from the Java source code. This attribute can also be specified for xref:rg.adoc#_rg_annotations_manpage-ActionLayout_named[actions], xref:rg.adoc#_rg_annotations_manpage-PropertyLayout_named[properties], xref:rg.adoc#_rg_annotations_manpage-ParameterLayout_named[parameters], xref:rg.adoc#_rg_annotations_manpage-DomainObjectLayout_named[domain objects], xref:rg.adoc#_rg_annotations_manpage-ViewModelLayout_named[view models] and xref:rg.adoc#_rg_annotations_manpage-DomainServiceLayout_named[domain services].
+
+[TIP]
+====
+Following the link:http://en.wikipedia.org/wiki/Don%27t_repeat_yourself[don't repeat yourself] principle, we recommend that you only use this attribute when the desired name cannot be used in Java source code. Examples of that include a name that would be a reserved Java keyword (eg "package"), or a name that has punctuation, eg apostrophes.
+====
+
+
+By default the name is HTML escaped. To allow HTML markup, set the related `namedEscaped()` attribute to `false`.
+
+
+For example:
+
+[source,java]
+----
+public class ToDoItem {
+ @CollectionLayout(
+ named="Todo items that are <i>dependencies</i> of this item",
+ namedEscaped=false
+ )
+ public SortedSet<ToDoItem getDependencies() { ... }
+ ...
+}
+----
+
+
+
+As an alternative to using the annotation, the dynamic xref:rg.adoc#_rg_object-layout_dynamic[`.layout.json`]
+can be used instead, eg:
+
+[source,javascript]
+----
+"dependencies": {
+ "collectionLayout": {
+ "named": "Todo items that are <i>dependencies</i> of this item",
+ "namedEscaped": false,
+ }
+}
+----
+
+
+[TIP]
+====
+The framework also provides a separate, powerful mechanism for xref:ug.adoc#_ug_more-advanced_i18n[internationalization].
+====
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-CollectionLayout_paged.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-CollectionLayout_paged.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-CollectionLayout_paged.adoc
new file mode 100644
index 0000000..0b71332
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-CollectionLayout_paged.adoc
@@ -0,0 +1,45 @@
+[[_rg_annotations_manpage-CollectionLayout_paged]]
+= `paged()`
+: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 `paged()` attribute specifies the number of rows to display in a (parented) collection. This attribute can also be applied to xref:rg.adoc#_rg_annotations_manpage-DomainObjectLayout_paged[domain objects] and xref:rg.adoc#_rg_annotations_manpage-ViewModelLayout_paged[view models].
+
+
+[WARNING]
+====
+The xref:ug.adoc#_ug_restfulobjects-viewer[RestfulObjects viewer] currently does not support paging. The xref:ug.adoc#_ug_wicket-viewer[Wicket viewer] _does_ support paging, but note that the paging is performed client-side rather than server-side.
+
+We therefore recommend that large collections should instead be modelled as actions (to allow filtering to be applied to limit the number of rows).
+====
+
+
+For example:
+
+[source,java]
+----
+public class Order {
+ @CollectionLayout(paged=15)
+ public SortedSet<OrderLine> getDetails() {...}
+}
+----
+
+
+It is also possible to specify a global default for the page size of standalone collections, using the xref:ug.adoc#_ug_runtime_configuring-core[configuration property] `isis.viewer.paged.parented`.
+
+
+
+As an alternative to using the annotation, the dynamic xref:rg.adoc#_rg_object-layout_dynamic[`.layout.json`]
+can be used instead, eg:
+
+[source,javascript]
+----
+"details": {
+ "collectionLayout": {
+ "paged": 15
+ }
+}
+----
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-CollectionLayout_render.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-CollectionLayout_render.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-CollectionLayout_render.adoc
new file mode 100644
index 0000000..6d85f2c
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-CollectionLayout_render.adoc
@@ -0,0 +1,40 @@
+[[_rg_annotations_manpage-CollectionLayout_render]]
+= `render()`
+: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 `render()` attribute specifies that the collection be rendered either "eagerly" (shown open, displaying its contents) or "lazily" (shown closed, hiding its contents). The terminology here is based on the similar concept of lazy loading of collections in the domain/persistence layer boundary (except that the rendering relates to the presentation/domain layer boundary).
+
+
+For example:
+
+[source,java]
+----
+public class Order {
+ @CollectionLayout(render=RenderType.EAGERLY)
+ public SortedSet<LineItem> getDetails() { ... }
+ ...
+}
+----
+
+
+As an alternative to using the annotation, the dynamic xref:rg.adoc#_rg_object-layout_dynamic[`.layout.json`]
+can be used instead, eg:
+
+[source,javascript]
+----
+"details": {
+ "collectionLayout": {
+ "render": "EAGERLY"
+ }
+}
+----
+
+
+[NOTE]
+====
+Note that xref:ug.adoc#_ug_how-tos_contributed-members[contributed collections] (which, under the covers are just action invocations against a domain service) are always rendered eagerly.
+====
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-CollectionLayout_sortedBy.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-CollectionLayout_sortedBy.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-CollectionLayout_sortedBy.adoc
new file mode 100644
index 0000000..d498c5f
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-CollectionLayout_sortedBy.adoc
@@ -0,0 +1,59 @@
+[[_rg_annotations_manpage-CollectionLayout_sortedBy]]
+= `sortedBy()`
+: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 `sortedBy()` attribute specifies that the collection be ordered using the specified comparator, rather than the natural ordering of the entity (as would usually be the case).
+
+For example:
+
+[source,java]
+----
+public class ToDoItem implements Comparable<ToDoItem> { // <1>
+ public static class DependenciesComparator // <2>
+ implements Comparator<ToDoItem> {
+ @Override
+ public int compare(ToDoItem p, ToDoItem q) {
+ return ORDERING_BY_DESCRIPTION // <3>
+ .compound(Ordering.<ToDoItem>natural())
+ .compare(p, q);
+ }
+ }
+ @CollectionLayout(sortedBy=DependenciesComparator.class) // <4>
+ public SortedSet<ToDoItem> getDependencies() { ... }
+ ...
+}
+----
+<1> the class has a natural ordering (implementation not shown)
+<2> declaration of the comparator class
+<3> ordering defined as being by the object's `description` property (not shown), and then by the natural ordering of the class
+<4> specify the comparator to use
+
+When the `dependencies` collection is rendered, the elements are sorted by the `description` property first:
+
+image::{_imagesdir}reference-annotations/CollectionLayout/sortedby-dependencies.png[width="720px",link="{_imagesdir}reference-annotations/CollectionLayout/sortedby-dependencies.png"]
+
+[NOTE]
+====
+Note that this screenshot shows an earlier version of the xref:ug.adoc#_ug_wicket-viewer[Wicket viewer] UI (specifically, pre 1.8.0).
+====
+
+
+Without this annotation, the order would have been inverted (because the natural ordering places items not completed before those items that have been completed.
+
+
+
+
+As an alternative to using the annotation, the dynamic xref:rg.adoc#_rg_object-layout_dynamic[`.layout.json`]
+can be used instead, eg:
+
+[source,javascript]
+----
+"dependencies": {
+ "collectionLayout": {
+ "sortedBy": "com.mycompany.myapp.dom.ToDoItem.DependenciesComparator"
+ }
+}
+----
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Collection_domainEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Collection_domainEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Collection_domainEvent.adoc
new file mode 100644
index 0000000..76ceafa
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Collection_domainEvent.adoc
@@ -0,0 +1,158 @@
+[[_rg_annotations_manpage-Collection_domainEvent]]
+= `domainEvent()`
+: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/
+
+
+Whenever a domain object (or list of domain objects) is to be rendered, the framework fires off multiple domain events for every property, collection and action of the domain object. In the cases of the domain object's collections, the events that are fired are:
+
+* hide phase: to check that the collection is visible (has not been hidden)
+* disable phase: to check that the collection is usable (has not been disabled)
+* validate phase: to check that the collection's arguments are valid (to add or remove an element)
+* pre-execute phase: before the modification of the collection
+* post-execute: after the modification of the collection
+
+Subscribers subscribe through the xref:rg.adoc#_rg_services-api_manpage-EventBusService[`EventBusService`] using either link:https://github.com/google/guava[Guava] or link:http://www.axonframework.org/[Axon Framework] annotations and can influence each of these phases.
+
+
+[WARNING]
+====
+The xref:ug.adoc#_ug_wicket-viewer[Wicket viewer] does _not_ currently support the modification of collections; they are rendered read-only. However, domain events are still relevant to determine if such collections should be hidden.
+
+The workaround is to create add/remove actions and use xref:rg.adoc#_rg_annotations_manpage-MemberOrder[UI hints] to render them close to the collection.
+====
+
+By default the event raised is `CollectionDomainEvent.Default`. For example:
+
+[source,java]
+----
+public class ToDoItem {
+ @Collection()
+ public SortedSet<ToDoItem> getDependencies() { ... }
+ ...
+}
+----
+
+The purpose of the `domainEvent()` attribute is to allows a custom subclass to be emitted instead. This attribute is also supported for xref:rg.adoc#_rg_annotations_manpage-Action_domainEvent[actions] and xref:rg.adoc#_rg_annotations_manpage-Property_domainEvent[properties].
+
+
+For example:
+
+[source,java]
+----
+public class ToDoItem {
+ public static class DependenciesChangedEvent
+ extends CollectionDomainEvent<ToDoItem, ToDoItem> { // <1>
+ private static final long serialVersionUID = 1L;
+ public DependenciesChangedEvent( // <2>
+ ToDoItem source, // <3>
+ Identifier identifier, // <4>
+ Of of, // <5>
+ ToDoItem value) { // <6>
+ super(source, identifier, of, value);
+ }
+ }
+ @Collection(
+ domainEvent=DependenciesChangedEvent.class
+ )
+ public SortedSet<ToDoItem> getDependencies() { ... }
+ ...
+}
+----
+<1> inherit from `CollectionDomainEvent<T,E>` where `T` is the type of the domain object being interacted with, and `E` is the type of the element in the collection (both `ToDoItem` in this example)
+<2> constructor called reflectively by the framework
+<3> populated with the object being interacted with (the source of the event)
+<4> identifier of the collection
+<5> indicates if the collection is being accessed, added to or removed from.
+<6> the element being added or removed from the collection
+
+
+The benefit is that subscribers can be more targetted as to the events that they subscribe to.
+
+
+
+== Subscribers
+
+Subscribers (which must be domain services) subscribe using either the link:https://github.com/google/guava[Guava] API or (if the xref:rg.adoc#_rg_services-api_manpage-EventBusService[`EventBusService`] has been appropriately configured) using the link:http://www.axonframework.org/[Axon Framework] API. The examples below use the Guava API.
+
+Subscribers can be either coarse-grained (if they subscribe to the top-level event type):
+
+[source,java]
+----
+@DomainService
+public class SomeSubscriber {
+ @Programmatic
+ @com.google.common.eventbus.Subscribe
+ public void on(CollectionInteractionEvent ev) {
+ ...
+ }
+}
+----
+
+or can be fine-grained (by subscribing to specific event subtypes):
+
+[source,java]
+----
+@DomainService
+public class SomeSubscriber {
+ @Programmatic
+ @com.google.common.eventbus.Subscribe
+ public void on(ToDoItem.DependenciesChangedEvent ev) {
+ ...
+ }
+}
+----
+
+[TIP]
+====
+If the AxonFramework is being used, replace `@com.google.common.eventbus.Subscribe` with `@org.axonframework.eventhandling.annotation.EventHandler`.
+====
+
+The subscriber's method is called (up to) 5 times:
+
+* whether to veto visibility (hide)
+* whether to veto usability (disable)
+* whether to veto execution (validate) the element being added to/removed from the collection
+* steps to perform prior to the collection being added to/removed from
+* steps to perform after the collection has been added to/removed from.
+
+The subscriber can distinguish these by calling `ev.getPhase()`. Thus the general form is:
+
+[source,java]
+----
+@Programmatic
+@com.google.common.eventbus.Subscribe
+public void on(CollectionDomainEvent ev) {
+ switch(ev.getPhase()) {
+ case HIDE:
+ // call ev.hide() or ev.veto("") to hide the collection
+ break;
+ case DISABLE:
+ // call ev.disable("...") or ev.veto("...") to disable the collection
+ break;
+ case VALIDATE:
+ // call ev.invalidate("...") or ev.veto("...")
+ // if object being added/removed to collection is invalid
+ break;
+ case EXECUTING:
+ break;
+ case EXECUTED:
+ break;
+ }
+}
+----
+
+It is also possible to abort the transaction during the executing or executed phases by throwing an exception. If the exception is a subtype of `RecoverableException` then the exception will be rendered as a user-friendly warning (eg Growl/toast) rather than an error.
+
+
+
+
+== Raising events programmatically
+
+Normally events are only raised for interactions through the UI. However, events can be raised programmatically either by calling the xref:rg.adoc#_rg_services-api_manpage-EventBusService[`EventBusService`] API directly, or by emulating the UI by
+wrapping the target object using the xref:rg.adoc#_rg_services-api_manpage-WrapperFactory[`WrapperFactory`] domain service.
+
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Collection_editing.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Collection_editing.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Collection_editing.adoc
new file mode 100644
index 0000000..b7cbb42
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Collection_editing.adoc
@@ -0,0 +1,48 @@
+[[_rg_annotations_manpage-Collection_editing]]
+= `editing()`
+: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 `editing()` annotation indicates whether a collection can be added to or removed from within the UI. This attribute can also be specified for xref:rg.adoc#_rg_annotations_manpage-Property_editing[properties], and can also be specified for the xref:rg.adoc#_rg_annotations_manpage-DomainObject_editing[domain object]
+
+The related `editingDisabledReason()` attribute specifies the a hard-coded reason why the collection cannot be modified directly.
+
+[WARNING]
+====
+The xref:ug.adoc#_ug_wicket-viewer[Wicket viewer] does _not_ currently support the modification of collections; they are rendered read-only.
+
+The workaround is to create add/remove actions and use xref:rg.adoc#_rg_annotations_manpage-MemberOrder[UI hints] to render them close to the collection.
+====
+
+Whether a collection is enabled or disabled depends upon these factors:
+
+* whether the domain object has been configured as immutable through the xref:rg.adoc#_rg_annotations_manpage-DomainObject_editing[`@DomainObject#editing()`] attribute
+
+* else (that is, if the domain object's editability is specified as being `AS_CONFIGURED`), then the value of the xref:ug.adoc#_ug_runtime_configuring-core[configuration property] `isis.objects.editing`. If set to `false`, then the object's collections (and properties) are _not_ editable
+
+* 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
+
+
+Thus, to make a collection read-only even if the object would otherwise be editable, use:
+
+
+[source,java]
+----
+public class ToDoItem {
+ @Collection(
+ editing=Editing.DISABLED,
+ editingDisabledReason="Use the add and remove actions to modify"
+ )
+ public SortedSet<ToDoItem> getDependencies() { ... }
+}
+----
+
+[NOTE]
+====
+To reiterate, it is _not_ possible to enable editing for a collection if editing has been disabled at the object-level.
+====
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Collection_hidden.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Collection_hidden.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Collection_hidden.adoc
new file mode 100644
index 0000000..9dd2b27
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Collection_hidden.adoc
@@ -0,0 +1,54 @@
+[[_rg_annotations_manpage-Collection_hidden]]
+= `hidden()`
+: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/
+
+
+Collections can be hidden at the domain-level, indicating that they are not visible to the end-user. This attribute can also be applied to xref:rg.adoc#_rg_annotations_manpage-Action_hidden[actions] and xref:rg.adoc#_rg_annotations_manpage-Property_hidden[properties].
+
+[TIP]
+====
+It is also possible to use xref:rg.adoc#_rg_annotations_manpage-CollectionLayout_hidden[`@CollectionLayout#hidden()`] or xref:rg.adoc#_rg_object-layout_dynamic[dynamic layouts] such that the collection can be hidden at the view layer. Both options are provided with a view that in the future the view-layer semantics may be under the control of (expert) users, whereas domain-layer semantics should never be overridden or modified by the user.
+====
+
+For example:
+
+[source,java]
+----
+public class Customer {
+ @Collection(where=Where.EVERYWHERE)
+ public SortedSet<Address> getAddresses() { ... }
+}
+----
+
+
+The acceptable values for the `where` parameter are:
+
+* `Where.EVERYWHERE` or `Where.ANYWHERE` +
++
+The collection should be hidden everywhere.
+
+* `Where.ANYWHERE` +
++
+Synonym for everywhere.
+
+* `Where.OBJECT_FORMS` +
++
+The collection should be hidden when displayed within an object form.
+
+* `Where.NOWHERE` +
++
+The collection should not be hidden.
+
+The other values of the `Where` enum have no meaning for a collection.
+
+
+
+
+[NOTE]
+====
+The xref:ug.adoc#_ug_wicket-viewer[Wicket viewer] suppresses collections when displaying lists of objects.
+
+The xref:ug.adoc#_ug_restfulobjects-viewer[RestfulObjects viewer] by default suppress collections when rendering a domain object.
+====
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Collection_notPersisted.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Collection_notPersisted.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Collection_notPersisted.adoc
new file mode 100644
index 0000000..c2fa983
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Collection_notPersisted.adoc
@@ -0,0 +1,57 @@
+[[_rg_annotations_manpage-Collection_notPersisted]]
+= `notPersisted()`
+: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 (somewhat misnamed) `notPersisted()` attribute indicates that the collection should be excluded from any snapshots generated by the xref:rg.adoc#_rg_services-api_manpage-XmlSnapshotService[`XmlSnapshotService`]. This attribute is also supported for xref:rg.adoc#_rg_annotations_manpage-Property_notPersisted[properties].
+
+
+[WARNING]
+====
+This annotation does _not_ specify that a collection is not persisted in the JDO/DataNucleus objectstore. See below for details as to how to additionally annotate the collection for this.
+====
+
+
+For example:
+
+[source,java]
+----
+public class Customer {
+ @Collection(notPersisted=true)
+ public SortedSet<Order> getPreviousOrders() {...}
+ public void setPreviousOrder(SortedSet<Order> previousOrders) {...}
+ ...
+}
+----
+
+Historically this annotation also hinted as to whether the collection's contents should be persisted in the object store. However, the JDO/DataNucleus objectstore does not recognize this annotation. Thus, to ensure that a collection is actually not persisted, it should *also* be annotated with `@javax.jdo.annotations.NotPersistent`.
+
+For example:
+
+[source,java]
+----
+public class Customer {
+ @Collection(notPersisted=true) // <1>
+ @javax.jdo.annotations.NotPersistent // <2>
+ public SortedSet<Order> getPreviousOrders() {...}
+ public void setPreviousOrder(SortedSet<Order> previousOrders) {...}
+ ...
+}
+----
+<1> ignored by Isis
+<2> ignored by JDO/DataNucleus
+
+
+
+Alternatively, if the collection is derived, then providing only a "getter" will also work:
+
+[source,java]
+----
+public class Customer {
+ public SortedSet<Order> getPreviousOrders() {...}
+ ...
+}
+----
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Collection_typeOf.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Collection_typeOf.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Collection_typeOf.adoc
new file mode 100644
index 0000000..6a50f5c
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Collection_typeOf.adoc
@@ -0,0 +1,26 @@
+[[_rg_annotations_manpage-Collection_typeOf]]
+= `typeOf()`
+: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 `typeOf()` attribute specifies the expected type of an element contained within a collection when for whatever reason the type cannot be inferred from the generic type, or to provide a hint about the actual run-time (as opposed to compile-time) type. This attribute can also be specified for xref:rg.adoc#_rg_annotations_manpage-Action_typeOf[actions].
+
+For example:
+
+[source,java]
+----
+public void Customer {
+ @TypeOf(Order.class)
+ public SortedSet getOutstandingOrders() { ... }
+ ...
+}
+----
+
+[TIP]
+====
+In general we recommend that you use generics instead, eg `SortedSet<Order>`.
+====
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Column.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Column.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Column.adoc
new file mode 100644
index 0000000..66984e1
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Column.adoc
@@ -0,0 +1,154 @@
+[[_rg_annotations_manpage-Column]]
+= `@Column` (`javax.jdo`)
+: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 JDO `@javax.jdo.annotation.Column` provides metadata describing how JDO/DataNucleus should persist the property to a database RDBMS table column (or equivalent concept for other persistence stores).
+
+Apache Isis also parses and interprets this annotation in order to build up aspects of its metamodel.
+
+[NOTE]
+====
+Isis parses the `@Column` annotation from the Java source code; it does not query the JDO metamodel. This means that it the `@Column` annotation must be used rather than the equivalent `<column>` link:http://www.datanucleus.org/products/accessplatform_4_0/jdo/orm/schema_mapping.html[XML metadata].
+
+Moreover, while JDO/DataNucleus will recognize annotations on either the field or the getter method, Isis (currently) only inspects the getter method. Therefore ensure that the annotation is placed there.
+====
+
+This section identifies which attributes of `@Column` are recognized and used by Isis.
+
+
+
+== Nullability
+
+The `allowsNull()` attribute is used to specify if a property is mandatory or is optional.
+
+For example:
+
+[source,java]
+----
+public class Customer {
+ @javax.jdo.annotations.Column(allowNulls="true")
+ public String getMiddleInitial() { ... }
+ public void setMiddleInitial(String middleInitial) { ... }
+----
+
+Isis also provides xref:rg.adoc#_rg_annotations_manpage-Property_optionality[`@Property#optionality()`] attribute. If both are specified, Isis will check when it initializes for any contradictions, and will fail-fast with an appropriate error message in the log if there are.
+
+You should also be aware that in the lack of either the `@Column#allowsNull()` or the `@Property#optionality()` attributes, that the JDO and Isis defaults differ. Isis rule is straight-forward: properties are assumed to be required. JDO on the other hand specifies that only primitive types are mandatory; everything else is assumed to be optional. Therefore a lack of either annotation can also trigger the fail-fast validation check.
+
+In the vast majority of cases you should be fine just to add the `@Column#allowsNull()` attribute to the getter. But see the documentation for xref:rg.adoc#_rg_annotations_manpage-Property_optionality[`@Property#optionality()`] attribute for discussion on one or two minor edge cases.
+
+
+
+== Length for ``String``s
+
+The `length()` attribute is used to specify the length of `java.lang.String` property types as they map to `varchar(n)` columns.
+
+For example:
+
+[source,java]
+----
+public class Customer {
+ @javax.jdo.annotations.Column(length=20)
+ public String getFirstName() { ... }
+ public void setFirstName(String firstName) { ... }
+ @javax.jdo.annotations.Column(allowNulls="true", length=1)
+ public String getMiddleInitial() { ... }
+ public void setMiddleInitial(String middleInitial) { ... }
+ @javax.jdo.annotations.Column(length=30)
+ public String getLastName() { ... }
+ public void setLastName(String lastName) { ... }
+----
+
+Isis also provides xref:rg.adoc#_rg_annotations_manpage-Property_maxLength[`@Property#maxLength()`] attribute. If both are specified, Isis will check when it initializes for any contradictions, and will fail-fast with an appropriate error message in the log if there are.
+
+
+
+== Length/scale for ``BigDecimal``s
+
+
+The `length()` and `scale()` attributes are used to infer the precision/scale of `java.math.BigDecimal` property types as they map to `decimal(n,p)` columns.
+
+For example:
+
+[source,java]
+----
+public class Customer {
+ @javax.jdo.annotations.Column(length=10, scale=2)
+ public BigDecimal getTotalOrdersToDate() { ... }
+ public void setTotalOrdersToDate(BigDecimal totalOrdersToDate) { ... }
+----
+
+For ``BigDecimal``s it is also possible to specify the xref:rg.adoc#_rg_annotations_manpage-Digits[`@Digits`] annotation, whose form is `@Digits(integer, fraction)`. There is a subtle difference here: while `@Column#scale()` corresponds to `@Digits#fraction()`, the value of `@Column#length()` (ie the precision) is actually the _sum_ of the `@Digits`' `integer()` and `fraction()` parts.
+
+If both are specified, Isis will check when it initializes for any contradictions, and will fail-fast with an appropriate error message in the log if there are.
+
+
+
+
+== Hints and Tips
+
+This seems to be a good place to describe some additional common mappings that use `@Column`. Unlike the sections above, the attributes specified in these hints and tips aren't actually part of Isis metamodel.
+
+
+=== Mapping foreign keys
+
+The `name()` attribute can be used to override the name of the column. References to other objects are generally mapped as foreign key columns. If there are multiple references to a given type, then you will want to override the name that JDO/DataNucleus would otherwise default.
+
+For example (taken from link:http://github.com/estatio/estatio[estatio] app):
+
+[source,java]
+----
+public class PartyRelationship {
+ @Column(name = "fromPartyId", allowsNull = "false")
+ public Party getFrom() { ... }
+ public void setFrom(Party from) { ... }
+ @Column(name = "toPartyId", allowsNull = "false")
+ public Party getTo() { ... }
+ public void setTo(Party to) { ... }
+ ...
+}
+----
+
+
+
+== 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.
+
+For example, here's how to map a `Blob` (taken from (non-ASF) http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp]):
+
+[source,java]
+----
+private Blob attachment;
+@javax.jdo.annotations.Persistent(defaultFetchGroup="false", columns = {
+ @javax.jdo.annotations.Column(name = "attachment_name"),
+ @javax.jdo.annotations.Column(name = "attachment_mimetype"),
+ @javax.jdo.annotations.Column(name = "attachment_bytes", jdbcType = "BLOB", sqlType = "BLOB")
+})
+@Property(
+ domainEvent = AttachmentDomainEvent.class,
+ optionality = Optionality.OPTIONAL
+)
+public Blob getAttachment() { ... }
+public void setAttachment(Blob attachment) { ... }
+----
+
+And here's how to map a `Clob` (also taken from the todoapp):
+
+[source,java]
+----
+private Clob doc;
+@javax.jdo.annotations.Persistent(defaultFetchGroup="false", columns = {
+ @javax.jdo.annotations.Column(name = "doc_name"),
+ @javax.jdo.annotations.Column(name = "doc_mimetype"),
+ @javax.jdo.annotations.Column(name = "doc_chars", jdbcType = "CLOB", sqlType = "CLOB")
+})
+@Property(
+ optionality = Optionality.OPTIONAL
+)
+public Clob getDoc() { ... }
+public void setDoc(final Clob doc) { ... }
+----
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Digits.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Digits.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Digits.adoc
new file mode 100644
index 0000000..a31516c
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Digits.adoc
@@ -0,0 +1,35 @@
+[[_rg_annotations_manpage-Digits]]
+= `@Digits` (`javax`)
+: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 `@javax.validation.constraints.Digits` annotation is recognized by Apache Isis as a means to specify the precision for properties and action parameters of type `java.math.BigDecimal`.
+
+For example (taken from the (non-ASF) http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp]):
+
+[source,java]
+----
+@javax.jdo.annotations.Column(
+ scale=2 // <1>
+)
+@javax.validation.constraints.Digits(
+ integer=10,
+ fraction=2 // <2>
+)
+public BigDecimal getCost() {
+ return cost;
+}
+public void setCost(final BigDecimal cost) {
+ this.cost = cost!=null
+ ? cost.setScale(2, BigDecimal.ROUND_HALF_EVEN) // <3>
+ :null;
+}
+----
+<1> the xref:rg.adoc#_rg_annotations_manpage-Column[`@Column#scale()`] attribute must be ...
+<2> ... consistent with `@Digits#fraction()`
+<3> the correct idiom when setting a new value is to normalized to the correct scale
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Discriminator.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Discriminator.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Discriminator.adoc
new file mode 100644
index 0000000..93a1c4b
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Discriminator.adoc
@@ -0,0 +1,59 @@
+[[_rg_annotations_manpage-Discriminator]]
+= `@Discriminator` (`javax.jdo`)
+: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 `@javax.jdo.annotation.Discriminator` is used by JDO/DataNucleus to specify how to discriminate between subclasses of an inheritance hierarchy.
+
+It is valid to add a `@Discriminator` for any class, even those not part of an explicitly mapped inheritance hierarchy. Apache Isis also checks for this annotation, and if present will use the `@Discriminator#value()` as the object type, a unique alias for the object's class name.
+
+[NOTE]
+====
+Isis parses the `@Discriminator` annotation from the Java source code; it does not query the JDO metamodel. This means that it the `@Discriminator` annotation must be used rather than the equivalent `<discriminator>` link:http://www.datanucleus.org/products/accessplatform_4_0/jdo/orm/inheritance.html[XML metadata].
+
+Moreover, while JDO/DataNucleus will recognize annotations on either the field or the getter method, Isis (currently) only inspects the getter method. Therefore ensure that the annotation is placed there.
+====
+
+The object type is used internally by Isis to generate a string representation of an objects identity (the `Oid`). This can appear in several contexts, including:
+
+* as the value of `o.a.i.applib.services.bookmark.Bookmark#getObjectType()`
+* in the `toString()` value of `Bookmark`
+* in the URLs of the xref:ug.adoc#_ug_restfulobjects-viewer[RestfulObjects viewer]
+* in the URLs of the xref:ug.adoc#_ug_wicket-viewer[Wicket viewer] (in general and in particular if xref:ug.adoc#_ug_wicket-viewer_features_hints-and-copy-url[copying URLs])
+* in XML snapshots generated by the xref:rg.adoc#_rg_services-api_manpage-XmlSnapshotService[`XmlSnapshotService`]
+
+
+For example:
+
+[source,java]
+----
+@javax.jdo.annotations.Discriminator(value="custmgmt.Customer")
+public class Customer {
+ ...
+}
+----
+
+has an object type of `custmgmt.Customer`.
+
+If the object type has not been specified, then Isis will use the fully qualified class name of the entity.
+
+
+
+[TIP]
+====
+This might be obvious, but to make explicit: we recommend that you use namespaces of some form or other.
+
+If the object type has not been specified (by either this annotation, or by xref:rg.adoc#_rg_annotations_manpage-PersistenceCapable[`@PersistenceCapable`], or by Isis' own xref:rg.adoc#_rg_annotations_manpage-DomainObject_objectType[`@DomainObject#objectType()`] annotation/attribute), then (as noted above) Isis will use the fully qualified class name of the entity.
+
+However, chances are that the fully qualified class name is liable to change over time, for example if the code is refactored or (more fundamentally) if your company/organization reorganizes/renames itself/is acquired.
+
+We therefore strongly recommend that you specify an object type for all entities, one way or another. Specifying `@Discriminator` will override `@PersistenceCapable`, which overrides `@DomainObject#objectType()`. Using `@PersistenceCapable#schema()` is probably the best choice in most cases.
+====
+
+[NOTE]
+====
+If the object type is not unique across all domain classes then the framework will fail-fast and fail to boot. An error message will be printed in the log to help you determine which classes have duplicate object tyoes.
+====
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainObject.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainObject.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainObject.adoc
new file mode 100644
index 0000000..3731056
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainObject.adoc
@@ -0,0 +1,105 @@
+[[_rg_annotations_manpage-DomainObject]]
+= `@DomainObject`
+: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 `@DomainObject` annotation applies to domain objects, collecting together all domain semantics within a single annotation.
+
+The table below summarizes the annotation's attributes.
+
+.`@DomainObject` attributes
+[cols="2,2,4a", options="header"]
+|===
+
+| Attribute
+| Values (default)
+| Description
+
+
+|xref:rg.adoc#_rg_annotations_manpage-DomainObject_auditing[`auditing()`]
+|`AS_CONFIGURED`, `ENABLED`, `DISABLED` +
+(`AS_CONFIGURED`)
+|indicates whether each of the changed properties of an object should be submitted to the registered xref:rg.adoc#_rg_services-spi_manpage-AuditingService[`AuditingService`].
+
+
+|xref:rg.adoc#_rg_annotations_manpage-DomainObject_autoCompleteRepository[`autoCompleteRepository()`]
+|Domain service class
+|nominate a method on a domain service to be used for looking up instances of the domain object
+
+
+|`autoCompleteAction()`
+|Method name +
+(`autoComplete()`)
+|override the method name to use on the auto-complete repository
+
+
+|xref:rg.adoc#_rg_annotations_manpage-DomainObject_bounded[`bounded()`]
+|`true`, `false` +
+(`false`)
+|Whether the number of instances of this domain class is relatively small (a "bounded" set), such that instances could be selected from a drop-down list box or similar.
+
+
+|xref:rg.adoc#_rg_annotations_manpage-DomainObject_editing[`editing()`]
+|`AS_CONFIGURED`, `ENABLED`, `DISABLED` +
+(`AS_CONFIGURED`)
+|whether the object's properties and collections can be edited or not (ie whether the instance should be considered to be immutable)
+
+
+|xref:rg.adoc#_rg_annotations_manpage-DomainObject_nature[`nature()`]
+|`NOT_SPECIFIED`, `JDO_ENTITY`, `EXTERNAL_ENTITY`, `INMEMORY_ENTITY`, `VIEW_MODEL` (`NOT_SPECIFIED`)
+|whether the domain object logically is an entity (part of the domain layer) or is a view model (part of the application layer); and if an entity, how is its persistence managed
+
+
+|xref:rg.adoc#_rg_annotations_manpage-DomainObject_objectType[`objectType()`]
+|(none, which implies fully qualified class name)
+|specify an alias for the domain class used to uniquely identify the object both within the Isis runtime and externally
+
+
+|xref:rg.adoc#_rg_annotations_manpage-DomainObject_publishing[`publishing()`]
+|`AS_CONFIGURED`, `ENABLED`, `DISABLED` +
+(`AS_CONFIGURED`)
+|whether changes to the object should be published to the registered xref:rg.adoc#_rg_services-spi_manpage-PublishingService[`PublishingService`].
+
+
+|`publishing-` +
+`PayloadFactory()`
+|subtype of `PublishingPayloadFactory-` `ForObject` (none)
+|specifies that a custom implementation of `PublishingPayloadFactoryForObject` be used to create the (payload of the) published event representing the change to the object
+
+|===
+
+
+
+For example:
+
+[source,java]
+----
+@DomainObject(
+ auditing=Auditing.ENABLED,
+ autoCompleteRepository=CustomerRepository.class
+ editing=Editing.ENABLED, // <1>
+ publishing=Publishing.ENABLED
+)
+public class Customer {
+ ...
+}
+----
+<1> default value, so could be omitted
+
+
+
+include::_rg_annotations_manpage-DomainObject_auditing.adoc[leveloffset=+1]
+include::_rg_annotations_manpage-DomainObject_autoCompleteRepository.adoc[leveloffset=+1]
+include::_rg_annotations_manpage-DomainObject_bounded.adoc[leveloffset=+1]
+include::_rg_annotations_manpage-DomainObject_editing.adoc[leveloffset=+1]
+include::_rg_annotations_manpage-DomainObject_nature.adoc[leveloffset=+1]
+include::_rg_annotations_manpage-DomainObject_objectType.adoc[leveloffset=+1]
+include::_rg_annotations_manpage-DomainObject_publishing.adoc[leveloffset=+1]
+
+
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainObjectLayout.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainObjectLayout.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainObjectLayout.adoc
new file mode 100644
index 0000000..cf27ca8
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainObjectLayout.adoc
@@ -0,0 +1,115 @@
+[[_rg_annotations_manpage-DomainObjectLayout]]
+= `@DomainObjectLayout`
+: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 `@DomainObjectLayout` annotation applies to domain classes, collecting together all UI hints within a single annotation.
+
+
+[NOTE]
+====
+For view models that have been annotated with `@ViewModel` the equivalent xref:rg.adoc#_rg_annotations_manpage-ViewModelLayout[`@ViewModelLayout`] can be used.
+====
+
+
+The table below summarizes the annotation's attributes.
+
+.`@DomainObjectLayout` attributes
+[cols="2,2,4a", options="header"]
+|===
+
+| Attribute
+| Values (default)
+| Description
+
+
+|xref:rg.adoc#_rg_annotations_manpage-DomainObjectLayout_bookmarking[`bookmarking()`]
+|`AS_ROOT`, `AS_CHILD`, `NEVER` +
+(`NEVER`)
+|whether (and how) this domain object should be automatically bookmarked
+
+
+|xref:rg.adoc#_rg_annotations_manpage-DomainObjectLayout_cssclass[`cssClass()`]
+|Any string valid as a CSS class
+|the css class that a domain class (type) should have, to allow more targetted styling in xref:ug.adoc#_ug_runtime_application-specific_application-css[`application.css`]
+
+
+|xref:rg.adoc#_rg_annotations_manpage-DomainObjectLayout_cssClassFa[`cssClassFa()`]
+|Any valid link:http://fortawesome.github.io/Font-Awesome/[Font awesome] icon name
+|specify a font awesome icon for the action's menu link or icon. +
+
+
+|`cssClassFaPosition()`
+|`LEFT`, `RIGHT` +
+(`LEFT`)
+|Currently unused.
+
+
+|xref:rg.adoc#_rg_annotations_manpage-DomainObjectLayout_describedAs[`describedAs()`]
+|String.
+|description of this class, eg to be rendered in a tooltip.
+
+
+
+|xref:rg.adoc#_rg_annotations_manpage-DomainObjectLayout_named[`named()`]
+|String.
+|to override the name inferred from the action's name in code. +
+
+A typical use case is if the desired name is a reserved Java keyword, such as `default` or `package`.
+
+
+|xref:rg.adoc#_rg_annotations_manpage-DomainObjectLayout_paged[`paged()`]
+|Positive integer
+|the page size for instances of this class when rendered within a table (as returned from an action invocation)
+
+
+|xref:rg.adoc#_rg_annotations_manpage-DomainObjectLayout_plural[`plural()`]
+|String.
+|the plural name of the class
+
+|===
+
+
+
+For example:
+
+[source,java]
+----
+@DomainObjectLayout(
+ cssClass="x-key",
+ cssClassFa="fa-checklist",
+ describedAs="Capture a task that you need to do",
+ named="ToDo",
+ paged=30,
+ plural="ToDo List")
+)
+public class ToDoItem {
+ ...
+}
+----
+
+
+
+[NOTE]
+====
+Note that there is (currently) no support for specifying UI hints for domain objects through the dynamic xref:rg.adoc#_rg_object-layout_dynamic[`.layout.json`] file (only for properties, collections and actions are supported).
+====
+
+
+
+
+
+
+
+include::_rg_annotations_manpage-DomainObjectLayout_bookmarking.adoc[leveloffset=+1]
+include::_rg_annotations_manpage-DomainObjectLayout_cssClass.adoc[leveloffset=+1]
+include::_rg_annotations_manpage-DomainObjectLayout_cssClassFa.adoc[leveloffset=+1]
+include::_rg_annotations_manpage-DomainObjectLayout_describedAs.adoc[leveloffset=+1]
+include::_rg_annotations_manpage-DomainObjectLayout_named.adoc[leveloffset=+1]
+include::_rg_annotations_manpage-DomainObjectLayout_paged.adoc[leveloffset=+1]
+include::_rg_annotations_manpage-DomainObjectLayout_plural.adoc[leveloffset=+1]
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainObjectLayout_bookmarking.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainObjectLayout_bookmarking.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainObjectLayout_bookmarking.adoc
new file mode 100644
index 0000000..32e52b5
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainObjectLayout_bookmarking.adoc
@@ -0,0 +1,66 @@
+[[_rg_annotations_manpage-DomainObjectLayout_bookmarking]]
+= `bookmarking()`
+: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 `bookmarking()` attribute indicates that an entity is automatically bookmarked. This attribute is also supported for xref:rg.adoc#_rg_annotations_manpage-Action_bookmarking[domain objects].
+
+(In the Wicket viewer), a link to a bookmarked object is shown in the bookmarks panel:
+
+image::{_imagesdir}reference-annotations/DomainObjectLayout/bookmarking.png[width="720px",link="{_imagesdir}reference-annotations/DomainObjectLayout/bookmarking.png"]
+
+[NOTE]
+====
+Note that this screenshot shows an earlier version of the xref:ug.adoc#_ug_wicket-viewer[Wicket viewer] UI (specifically, pre 1.8.0).
+====
+
+For example:
+
+[source,java]
+----
+@DomainObject(bookmarking=BookmarkPolicy.AS_ROOT)
+public class ToDoItem ... {
+ ...
+}
+----
+
+indicates that the `ToDoItem` class is bookmarkable:
+
+
+It is also possible to nest bookmarkable entities. For example, this screenshot is taken from http://github.com/estatio/estatio[Estatio]:
+
+image::{_imagesdir}reference-annotations/DomainObjectLayout/bookmarking-nested.png[width="720px",link="{_imagesdir}reference-annotations/DomainObjectLayout/bookmarking-nested.png"]
+
+
+[NOTE]
+====
+Note that this screenshot shows an earlier version of the xref:ug.adoc#_ug_wicket-viewer[Wicket viewer] UI (specifically, pre 1.8.0).
+====
+
+
+For example, the `Property` entity "[OXF] Oxford Super Mall" is a root bookmark, but the `Unit` child entity "[OXF-001] Unit 1" only appears as a bookmark _but only if_ its parent `Property` has already been bookmarked.
+
+This is accomplished with the following annotations:
+
+[source,java]
+----
+@DomainObject(bookmarking=BookmarkPolicy.AS_ROOT)
+public class Property { ... }
+----
+
+and
+
+[source,java]
+----
+@DomainObject(bookmarking=BookmarkPolicy.AS_CHILD)
+public abstract class Unit { ... }
+----
+
+The nesting can be done to any level; the Estatio screenshot also shows a bookmark nesting `Lease` > `LeaseItem` > `LeaseTerm` (3 levels deep).
+
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainObjectLayout_cssClass.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainObjectLayout_cssClass.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainObjectLayout_cssClass.adoc
new file mode 100644
index 0000000..ddd84c9
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainObjectLayout_cssClass.adoc
@@ -0,0 +1,34 @@
+[[_rg_annotations_manpage-DomainObjectLayout_cssClass]]
+= `cssClass()`
+: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 `cssClass()` attribute can be used to render additional CSS classes in the HTML (a wrapping `<div>`) that represents the domain object. xref:ug.adoc#_ug_runtime_application-specific_application-css[Application-specific CSS] can then be used to target and adjust the UI representation of that particular element.
+
+This attribute can also be applied to xref:rg.adoc#_rg_annotations_manpage-DomainObjectLayout_cssClass[domain objects], xref:rg.adoc#_rg_annotations_manpage-ViewModelLayout_cssClass[view models], xref:rg.adoc#_rg_annotations_manpage-ActionLayout_cssClass[actions] xref:rg.adoc#_rg_annotations_manpage-PropertyLayout_cssClass[properties], xref:rg.adoc#_rg_annotations_manpage-CollectionLayout_cssClass[collections] and xref:rg.adoc#_rg_annotations_manpage-ParameterLayout_cssClass[parameters].
+
+
+For example:
+
+[source,java]
+----
+@DomainObject(
+ cssClass="x-core-entity"
+)
+public class ToDoItem { ... }
+----
+
+
+
+
+[NOTE]
+====
+The similar xref:rg.adoc#_rg_annotations_manpage-DomainObjectLayout_cssClassFa[`@DomainObjectLayout#cssClassFa()`] annotation attribute is also used as a hint to apply CSS, but in particular to allow http://fortawesome.github.io/Font-Awesome/icons/[Font Awesome icons]
+to be rendered as the icon for classes.
+====
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainObjectLayout_cssClassFa.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainObjectLayout_cssClassFa.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainObjectLayout_cssClassFa.adoc
new file mode 100644
index 0000000..9dfcd7a
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainObjectLayout_cssClassFa.adoc
@@ -0,0 +1,40 @@
+[[_rg_annotations_manpage-DomainObjectLayout_cssClassFa]]
+= `cssClassFa()`
+: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 `cssClassFa()` attribute is used to specify the name of a link:http://fortawesome.github.io/Font-Awesome/icons/[Font Awesome icon] name, to be rendered as the domain object's icon.
+
+These attributes can also be applied to xref:rg.adoc#_rg_annotations_manpage-ViewModelLayout_cssClassFa[view models] to specify the object's icon, and to xref:rg.adoc#_rg_annotations_manpage-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.
+
+
+
+For example:
+
+[source,java]
+----
+@DomainObjectLayout(
+ cssClassFa="fa-check-circle"
+)
+public class ToDoItem { ... }
+----
+
+There can be multiple "fa-" classes, eg to mirror or rotate the icon. There is no need to include the mandatory `fa` "marker" CSS class; it will be automatically added to the list. The `fa-` prefix can also be omitted from the class names; it will be prepended to each if required.
+
+
+The related `cssClassFaPosition()` attribute is currently unused for domain objects; the icon is always rendered to the left.
+
+
+[TIP]
+====
+The similar xref:rg.adoc#_rg_annotations_manpage-DomainObjectLayout_cssClass[`@DomainObjectLayout#cssClass()`] annotation attribute is also used as a hint
+to apply CSS, but for wrapping the representation of an object or object
+member so that it can be styled in an application-specific way.
+====
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainObjectLayout_describedAs.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainObjectLayout_describedAs.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainObjectLayout_describedAs.adoc
new file mode 100644
index 0000000..562f081
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainObjectLayout_describedAs.adoc
@@ -0,0 +1,22 @@
+[[_rg_annotations_manpage-DomainObjectLayout_describedAs]]
+= `describedAs()`
+: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 `describedAs()` attribute is used to provide a short description of the domain object to the user. In the xref:ug.adoc#_ug_wicket-viewer[Wicket viewer] it is displayed as a 'tool tip'. The attribute can also be specified for xref:rg.adoc#_rg_annotations_manpage-CollectionLayout_describedAs[collections], xref:rg.adoc#_rg_annotations_manpage-PropertyLayout_describedAs[properties], xref:rg.adoc#_rg_annotations_manpage-ActionLayout_describedAs[actions], xref:rg.adoc#_rg_annotations_manpage-ParameterLayout_describedAs[parameters] and xref:rg.adoc#_rg_annotations_manpage-ViewModelLayout_describedAs[view models].
+
+For example:
+
+[source,java]
+----
+@DescribedAs("A customer who may have originally become known to us via " +
+ "the marketing system or who may have contacted us directly.")
+public class ProspectiveSale {
+ ...
+}
+----
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainObjectLayout_named.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainObjectLayout_named.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainObjectLayout_named.adoc
new file mode 100644
index 0000000..c2cbea4
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainObjectLayout_named.adoc
@@ -0,0 +1,37 @@
+[[_rg_annotations_manpage-DomainObjectLayout_named]]
+= `named()`
+: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 `named()` attribute explicitly specifies the domain object's name, overriding the name that would normally be inferred from the Java source code. The attribute can also be specified for xref:rg.adoc#_rg_annotations_manpage-ActionLayout_named[actions], xref:rg.adoc#_rg_annotations_manpage-CollectionLayout_named[collections], xref:rg.adoc#_rg_annotations_manpage-PropertyLayout_named[properties], xref:rg.adoc#_rg_annotations_manpage-ParameterLayout_named[parameters], xref:rg.adoc#_rg_annotations_manpage-ViewModelLayout_named[view models] and xref:rg.adoc#_rg_annotations_manpage-DomainServiceLayout_named[domain services].
+
+
+[TIP]
+====
+Following the link:http://en.wikipedia.org/wiki/Don%27t_repeat_yourself[don't repeat yourself] principle, we recommend that you only use this attribute when the desired name cannot be used in Java source code. Examples of that include a name that would be a reserved Java keyword (eg "package"), or a name that has punctuation, eg apostrophes.
+====
+
+
+For example:
+
+[source,java]
+----
+@DomainObjectLayout(
+ named="Customer"
+)
+public class CustomerImpl implements Customer{
+ ...
+}
+----
+
+It's also possible to specify a xref:rg.adoc#_rg_annotations_manpage-DomainObjectLayout_plural[plural form] of the name, used by the framework when rendering a standalone collection of the domain object.
+
+
+[TIP]
+====
+The framework also provides a separate, powerful mechanism for xref:ug.adoc#_ug_more-advanced_i18n[internationalization].
+====
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainObjectLayout_paged.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainObjectLayout_paged.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainObjectLayout_paged.adoc
new file mode 100644
index 0000000..6963603
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainObjectLayout_paged.adoc
@@ -0,0 +1,33 @@
+[[_rg_annotations_manpage-DomainObjectLayout_paged]]
+= `paged()`
+: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 `paged()` attribute specifies the number of rows to display in a standalone collection, as returned from an action invocation. This attribute can also be applied to xref:rg.adoc#_rg_annotations_manpage-CollectionLayout_paged[collections] and xref:rg.adoc#_rg_annotations_manpage-ViewModelLayout_paged[view models].
+
+
+[WARNING]
+====
+The xref:ug.adoc#_ug_restfulobjects-viewer[RestfulObjects viewer] currently does not support paging. The xref:ug.adoc#_ug_wicket-viewer[Wicket viewer] _does_ support paging, but note that the paging is performed client-side rather than server-side.
+
+We therefore recommend that large collections should instead be modelled as actions (to allow filtering to be applied to limit the number of rows).
+====
+
+
+For example:
+
+[source,java]
+----
+@DomainObjectLayout(paged=15)
+public class Order {
+ ...
+}
+----
+
+
+It is also possible to specify a global default for the page size of standalone collections, using the xref:ug.adoc#_ug_runtime_configuring-core[configuration property] `isis.viewer.paged.standalone`.
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainObjectLayout_plural.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainObjectLayout_plural.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainObjectLayout_plural.adoc
new file mode 100644
index 0000000..838d182
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainObjectLayout_plural.adoc
@@ -0,0 +1,28 @@
+[[_rg_annotations_manpage-DomainObjectLayout_plural]]
+= `plural()`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+
+When Apache Isis displays a standalone collection of several objects, it will label the collection using the plural form of the object type.
+
+By default the plural name will be derived from the end of the singular name, with support for some basic English language defaults (eg using "ies" for names ending with a "y").
+
+The `plural()` attribute allows the plural form of the class name to be specified explicitly. This attribute is also supported for xref:rg.adoc#_rg_annotations_manpage-ViewModelLayout_plural[view models].
+
+For example:
+
+[source,java]
+----
+@DomainObjectLayout(plural="Children")
+public class Child {
+ ...
+}
+----
+
+
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainObject_auditing.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainObject_auditing.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainObject_auditing.adoc
new file mode 100644
index 0000000..29adddc
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainObject_auditing.adoc
@@ -0,0 +1,38 @@
+[[_rg_annotations_manpage-DomainObject_auditing]]
+= `auditing()`
+: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 `auditing()` attribute indicates that if the object is modified, then each of its changed properties should be submitted to the xref:rg.adoc#_rg_services-spi_manpage-AuditingService[`AuditingService`], if one has been configured.
+
+The default value for the attribute is `AS_CONFIGURED`, meaning that the xref:ug.adoc#_ug_runtime_configuring-core[configuration property] `isis.services.audit.objects` is used to determine the whether the action is published:
+
+* `all` +
++
+all changed objects are published
+
+* `none` +
++
+no changed objects are published
+
+If there is no configuration property in `isis.properties` then auditing is automatically enabled for domain objects.
+
+This default can be overridden on an object-by-object basis; if `auditing()` is set to `ENABLED` then changed properties of instances of the domain class are audited irrespective of the configured value; if set to `DISABLED` then the changed properties of instances are _not_ audited, again irrespective of the configured value.
+
+For example:
+
+[source,java]
+----
+@DomainObject(
+ auditing=Auditing.ENABLED // <1>
+)
+public class Customer {
+ ...
+}
+----
+<1> because set to enabled, will be audited irrespective of the configured value.
+
+
+