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 2017/03/31 07:11:16 UTC
[40/51] [partial] isis git commit: ISIS-1521: reorganizes asciidoc
documentation, moves into subdirs (both guides and other pages)
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/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
deleted file mode 100644
index b598dc1..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject_nature.adoc
+++ /dev/null
@@ -1,66 +0,0 @@
-[[_rgant-DomainObject_nature]]
-= `nature()`
-: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 `nature()` attribute is used to characterize the domain object as either an entity (part of the domain layer) or as a view model (part of the application layer). If the domain object should be thought of as an entity, it also captures how the persistence of that entity is managed.
-
-For example:
-
-[source,java]
-----
-@DomainObject(nature=Nature.VIEW_MODEL)
-public class PieChartAnalysis {
- ...
-}
-----
-
-Specifically, the nature must be one of:
-
-* `NOT_SPECIFIED,` +
-+
-(the default); specifies no paricular semantics for the domain class.
-
-* `JDO_ENTITY` +
-+
-indicates that the domain object is an entity whose persistence is managed internally by Apache Isis, using the JDO/DataNucleus objectstore.
-
-* `EXTERNAL_ENTITY` +
-+
-indicates that the domain objecct is a wrapper/proxy/stub (choose your term) to an entity that is managed by some related external system. For example, the domain object may hold just the URI to a RESTful resource of some third party REST service, or the id of some system accessible over SOAP. +
-+
-The identity of an external 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.
-
-* `INMEMORY_ENTITY` +
-+
-indicates that the domain object is a wrapper/proxy/stub to a "synthetic" entity, for example one that is constructed from some sort of internal memory data structure. +
-+
-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.
-
-* `MIXIN` +
-+
-indicates that the domain object is part of the domain layer, and is contributing behaviour to objects of some other type as a mixin (also known as a trait).
-
-Equivalent to annotating with xref:rgant.adoc#_rgant-Mixin[`@Mixin`]. For further discussion on using mixins, see xref:ugbtb.adoc#_ugbtb_decoupling_mixins[mixins] in the user guide.
-
-
-* `VIEW_MODEL` +
-+
-indicates that the domain object is conceptually part of the application layer, and exists to surfaces behaviour and/or state that is aggregate of one or more domain entities.
-
-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:rgcms.adoc#_rgcms_classes_super_ViewModel[`ViewModel`] interface.
-
-
-[NOTE]
-====
-Under the covers Apache Isis' support for `VIEW_MODEL`, `EXTERNAL_ENTITY` and `INMEMORY_ENTITY` domain objects is identical; the state of the object is encoded into its internal OID (represented ultimately as its URL), and is recreated directly from that URL.
-
-Because this particular implementation was originally added to Apache Isis in support of view models, the term was also used for the logically different external entities and inmemory entities.
-
-The benefit of `nature()` is that it allows the developer to properly characterize the layer (domain vs application) that an entity lives, thus avoiding confusion as "view model" (the implementation technique) and "view model" (the application layer concept).
-====
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject_objectType.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject_objectType.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject_objectType.adoc
deleted file mode 100644
index 22b6c12..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject_objectType.adoc
+++ /dev/null
@@ -1,64 +0,0 @@
-[[_rgant-DomainObject_objectType]]
-= `objectType()`
-: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 `objectType()` attribute is used to provide a unique alias for the object's class name.
-
-This value is used internally to generate a string representation of an objects identity (the `Oid`).
-This can appear in several contexts, including:
-
-* as the value of `Bookmark#getObjectType()` and in the `toString()` value of `Bookmark`
- (see xref:rgsvc.adoc#_rgsvc_api_BookmarkService[`BookmarkService`])
- ** and thus in the "table-of-two-halves" pattern, as per (non-ASF) http://github.com/isisaddons/isis-module-poly[Isis addons' poly] module
-* in the serialization of `OidDto` in the xref:rgcms.adoc#_rgcms_schema-cmd[command] and xref:rgcms.adoc#_rgcms_schema-ixn[interaction] schemas
-* in the URLs of the xref:ugvro.adoc#[RestfulObjects viewer]
-* in the URLs of the xref:ugvw.adoc#[Wicket viewer] (in general and in particular if xref:ugvw.adoc#_ugvw_features_hints-and-copy-url[copying URLs])
-* in XML snapshots generated by the xref:rgsvc.adoc#_rgsvc_api_XmlSnapshotService[`XmlSnapshotService`]
-
-
-
-== Examples
-
-For example:
-
-[source,java]
-----
-@DomainObject(
- objectType="orders.Order"
-)
-public class Order {
- ...
-}
-----
-
-
-== Precedence
-
-The rules of precedence are:
-
-1. xref:rgant.adoc#_rgant_Discriminator[`@Discriminator`]
-2. `@DomainObject#objectType`, or xref:rgant.adoc#_rgant_aaa_deprecated[`@ObjectType`] (deprecated)
-3. xref:rgant.adoc#_rgant_PersistenceCapable[`@PersistenceCapable`], if at least the `schema` attribute is defined. +
-+
-If both `schema` and `table` are defined, then the value is "`schema.table`".
-If only `schema` is defined, then the value is "`schema.className`".
-
-4. Fully qualified class name of the entity.
-
-
-[TIP]
-====
-This might be obvious, but to make explicit: we recommend that you always specify an object type for your domain objects.
-
-Otherwise, if you refactor your code (change class name or move package), then any externally held references to the OID of the object will break.
-At best this will require a data migration in the database; at worst it could cause external clients accessing data through the xref:ugvro.adoc#[Restful Objects] viewer to break.
-====
-
-[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/2669a971/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject_persistedLifecycleEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject_persistedLifecycleEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject_persistedLifecycleEvent.adoc
deleted file mode 100644
index 579dc3c..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject_persistedLifecycleEvent.adoc
+++ /dev/null
@@ -1,111 +0,0 @@
-[[_rgant-DomainObject_persistedLifecycleEvent]]
-= persistedLifecycleEvent()
-: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 (just created, still transient) domain object has been saved (INSERTed in)to the database, a "persisted" lifecycle
-event is fired.
-
-Subscribers subscribe through the xref:rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] and can
-use the event to obtain a reference to the domain object. The subscriber could then, for example, maintain an
-external datastore.
-
-[WARNING]
-====
-The object should _not_ be modified during the persisted callback.
-====
-
-By default the event raised is `ObjectPersistedEvent.Default`. For example:
-
-[source,java]
-----
-@DomainObject
-public class ToDoItemDto {
- ...
-}
-----
-
-The purpose of the `persistedLifecycleEvent()` attribute is to allows a custom subclass to be emitted instead. A similar
-attribute is available for other lifecycle events.
-
-For example:
-
-[source,java]
-----
-@DomainObjectLayout(
- persistedLifecycleEvent=ToDoItem.PersistedEvent.class
-)
-public class ToDoItem {
- public static class PersistedEvent
- extends org.apache.isis.applib.services.eventbus.ObjectPersistedEvent<ToDoItem> { }
- ...
-}
-----
-
-The benefit is that subscribers can be more targeted 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:rgsvc.adoc#_rgsvc_api_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(nature=NatureOfService.DOMAIN)
-public class SomeSubscriber extends AbstractSubscriber {
- @com.google.common.eventbus.Subscribe
- public void on(ObjectPersistedEvent ev) {
- if(ev.getSource() instanceof ToDoItem) { ... }
- }
-}
-----
-
-or can be fine-grained (by subscribing to specific event subtypes):
-
-[source,java]
-----
-@DomainService(nature=NatureOfService.DOMAIN)
-public class SomeSubscriber extends AbstractSubscriber {
- @com.google.common.eventbus.Subscribe
- public void on(ToDoItem.ObjectPersistedEvent ev) {
- ...
- }
-}
-----
-
-
-[TIP]
-====
-If the AxonFramework is being used, replace `@com.google.common.eventbus.Subscribe` with `@org.axonframework.eventhandling.annotation.EventHandler`.
-====
-
-
-
-
-
-== Default, Doop and Noop events
-
-If the `persistedLifecycleEvent` attribute is not explicitly specified (is left as its default value, `ObjectPersistedEvent.Default`),
-then the framework will, by default, post an event.
-
-If this is not required, then the `isis.reflector.facet.domainObjectAnnotation.persistedLifecycleEvent.postForDefault`
-configuration property can be set to "false"; this will disable posting.
-
-On the other hand, if the `persistedLifecycleEvent` has been explicitly specified to some subclass, then an event will be posted.
-The framework provides `ObjectPersistedEvent.Doop` as such a subclass, so setting the `persistedLifecycleEvent` attribute to this class
-will ensure that the event to be posted, irrespective of the configuration property setting.
-
-And, conversely, the framework also provides `ObjectPersistedEvent.Noop`; if `persistedLifecycleEvent` attribute is set to this class,
-then no event will be posted.
-
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/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
deleted file mode 100644
index 311f299..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject_persistingLifecycleEvent.adoc
+++ /dev/null
@@ -1,114 +0,0 @@
-[[_rgant-DomainObject_persistingLifecycleEvent]]
-= persistingLifecycleEvent()
-: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 (just created, still transient) domain object is about to be saved (INSERTed in)to the database, a "persisting" lifecycle
-event is fired.
-
-Subscribers subscribe through the xref:rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] and can
-use the event to obtain a reference to the domain object. The subscriber could then, for example, update the object,
-or it could use it maintain an external datastore. One possible application is to maintain a full-text search database using
-link:https://lucene.apache.org/[Apache Lucene] or similar.
-
-[NOTE]
-====
-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:rgcms.adoc#_rgcms_classes_roles_Timestampable[`Timestampable`] role interface.
-====
-
-By default the event raised is `ObjectPersistingEvent.Default`. For example:
-
-[source,java]
-----
-@DomainObject
-public class ToDoItemDto {
- ...
-}
-----
-
-The purpose of the `persistingLifecycleEvent()` attribute is to allows a custom subclass to be emitted instead. A similar
-attribute is available for other lifecycle events.
-
-For example:
-
-[source,java]
-----
-@DomainObjectLayout(
- persistingLifecycleEvent=ToDoItem.PersistingEvent.class
-)
-public class ToDoItem {
- public static class PersistingEvent
- extends org.apache.isis.applib.services.eventbus.ObjectPersistingEvent<ToDoItem> { }
- ...
-}
-----
-
-The benefit is that subscribers can be more targeted 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:rgsvc.adoc#_rgsvc_api_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(nature=NatureOfService.DOMAIN)
-public class SomeSubscriber extends AbstractSubscriber {
- @com.google.common.eventbus.Subscribe
- public void on(ObjectPersistingEvent ev) {
- if(ev.getSource() instanceof ToDoItem) { ... }
- }
-}
-----
-
-or can be fine-grained (by subscribing to specific event subtypes):
-
-[source,java]
-----
-@DomainService(nature=NatureOfService.DOMAIN)
-public class SomeSubscriber extends AbstractSubscriber {
- @com.google.common.eventbus.Subscribe
- public void on(ToDoItem.ObjectPersistingEvent ev) {
- ...
- }
-}
-----
-
-
-[TIP]
-====
-If the AxonFramework is being used, replace `@com.google.common.eventbus.Subscribe` with `@org.axonframework.eventhandling.annotation.EventHandler`.
-====
-
-
-
-
-
-== Default, Doop and Noop events
-
-If the `persistingLifecycleEvent` attribute is not explicitly specified (is left as its default value, `ObjectPersistingEvent.Default`),
-then the framework will, by default, post an event.
-
-If this is not required, then the `isis.reflector.facet.domainObjectAnnotation.persistingLifecycleEvent.postForDefault`
-configuration property can be set to "false"; this will disable posting.
-
-On the other hand, if the `persistingLifecycleEvent` has been explicitly specified to some subclass, then an event will be posted.
-The framework provides `ObjectPersistingEvent.Doop` as such a subclass, so setting the `persistingLifecycleEvent` attribute to this class
-will ensure that the event to be posted, irrespective of the configuration property setting.
-
-And, conversely, the framework also provides `ObjectPersistingEvent.Noop`; if `persistingLifecycleEvent` attribute is set to this class,
-then no event will be posted.
-
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject_publishing.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject_publishing.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject_publishing.adoc
deleted file mode 100644
index 331f8ed..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject_publishing.adoc
+++ /dev/null
@@ -1,63 +0,0 @@
-[[_rgant-DomainObject_publishing]]
-= `publishing()`
-: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 `publishing()` attribute determines whether and how a modified object instance is published via the registered
-implementation of a xref:rgsvc.adoc#_rgsvc_spi_PublishingService[`PublishingService`]) or
-xref:rgsvc.adoc#_rgsvc_spi_PublisherService[`PublisherService`]. This attribute is also supported
-for xref:rgant.adoc#_rgant-Action_publishing[actions], where it controls whether action invocations are published as
-events, and for xref:rgant.adoc#_rgant_Property_publishing[`@Property#publishing()`], where it controls whether
-property edits are published as events.
-
-A common use case is to notify external "downstream" systems of changes in the state of the Isis application.
-
-The default value for the attribute is `AS_CONFIGURED`, meaning that the xref:rgcfg.adoc#_rgcfg_configuring-core[configuration property] `isis.services.publish.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 publishing is automatically enabled for domain objects.
-
-This default can be overridden on an object-by-object basis; if `publishing()` is set to `ENABLED` then changed instances of the domain class are published irrespective of the configured value; if set to `DISABLED` then the changed instances are _not_ published, again irrespective of the configured value.
-
-For example:
-
-[source,java]
-----
-@DomainObject(
- publishing=Publishing.ENABLED // <1>
-)
-public class InterestRate {
- ...
-}
-----
-<1> because set to enabled, will be published irrespective of the configured value.
-
-
-
-
-== `publishingPayloadFactory()`
-
-The (optional) related `publishingPayloadFactory()` specifies the class to use to create the (payload of the) event to
-be published by the publishing factory.
-
-Rather than simply broadcast that the object was changed, the payload factory allows a "fatter" payload to be
-instantiated that can eagerly push commonly-required information to all subscribers. For at least some subscribers
-this should avoid the necessity to query back for additional information.
-
-
-[WARNING]
-====
-Be aware that this attribute is only honoured by the (deprecated)
-xref:rgsvc.adoc#_rgsvc_spi_PublishingService[`PublishingService`], so should itself be considered as deprecated. It
-is ignored by the replacement xref:rgsvc.adoc#_rgsvc_spi_PublisherService[`PublisherService`],
-====
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/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
deleted file mode 100644
index 70036db..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject_removingLifecycleEvent.adoc
+++ /dev/null
@@ -1,114 +0,0 @@
-[[_rgant-DomainObject_removingLifecycleEvent]]
-= removingLifecycleEvent()
-: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 (persistent) domain object is about to be removed (DELETEd) from the database, a "removing"
-lifecycle event is fired.
-
-Subscribers subscribe through the xref:rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] and can
-use the event to obtain a reference to the domain object. The subscriber could then, for example, could use it
-maintain an external datastore. One possible application is to maintain a full-text search database
-using link:https://lucene.apache.org/[Apache Lucene] or similar.
-
-[NOTE]
-====
-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:rgcms.adoc#_rgcms_classes_roles_Timestampable[`Timestampable`] role interface.
-====
-
-By default the event raised is `ObjectRemovingEvent.Default`. For example:
-
-[source,java]
-----
-@DomainObject
-public class ToDoItemDto {
- ...
-}
-----
-
-The purpose of the `removingLifecycleEvent()` attribute is to allows a custom subclass to be emitted instead. A similar
-attribute is available for other lifecycle events.
-
-For example:
-
-[source,java]
-----
-@DomainObjectLayout(
- removingLifecycleEvent=ToDoItem.RemovingEvent.class
-)
-public class ToDoItem {
- public static class RemovingEvent
- extends org.apache.isis.applib.services.eventbus.ObjectRemovingEvent<ToDoItem> { }
- ...
-}
-----
-
-The benefit is that subscribers can be more targeted 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:rgsvc.adoc#_rgsvc_api_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(nature=NatureOfService.DOMAIN)
-public class SomeSubscriber extends AbstractSubscriber {
- @com.google.common.eventbus.Subscribe
- public void on(ObjectRemovingEvent ev) {
- if(ev.getSource() instanceof ToDoItem) { ... }
- }
-}
-----
-
-or can be fine-grained (by subscribing to specific event subtypes):
-
-[source,java]
-----
-@DomainService(nature=NatureOfService.DOMAIN)
-public class SomeSubscriber extends AbstractSubscriber {
- @com.google.common.eventbus.Subscribe
- public void on(ToDoItem.ObjectRemovingEvent ev) {
- ...
- }
-}
-----
-
-
-[TIP]
-====
-If the AxonFramework is being used, replace `@com.google.common.eventbus.Subscribe` with `@org.axonframework.eventhandling.annotation.EventHandler`.
-====
-
-
-
-
-
-== Default, Doop and Noop events
-
-If the `removingLifecycleEvent` attribute is not explicitly specified (is left as its default value, `ObjectRemovingEvent.Default`),
-then the framework will, by default, post an event.
-
-If this is not required, then the `isis.reflector.facet.domainObjectAnnotation.removingLifecycleEvent.postForDefault`
-configuration property can be set to "false"; this will disable posting.
-
-On the other hand, if the `removingLifecycleEvent` has been explicitly specified to some subclass, then an event will be posted.
-The framework provides `ObjectRemovingEvent.Doop` as such a subclass, so setting the `removingLifecycleEvent` attribute to this class
-will ensure that the event to be posted, irrespective of the configuration property setting.
-
-And, conversely, the framework also provides `ObjectRemovingEvent.Noop`; if `removingLifecycleEvent` attribute is set to this class,
-then no event will be posted.
-
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject_updatedLifecycleEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject_updatedLifecycleEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject_updatedLifecycleEvent.adoc
deleted file mode 100644
index b051ae4..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject_updatedLifecycleEvent.adoc
+++ /dev/null
@@ -1,110 +0,0 @@
-[[_rgant-DomainObject_updatedLifecycleEvent]]
-= updatedLifecycleEvent()
-: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 (persistent) domain object has been modified and has been updated in the database, an "updated" lifecycle
-event is fired.
-
-Subscribers subscribe through the xref:rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] and can
-use the event to obtain a reference to the domain object.
-
-[WARNING]
-====
-The object should _not_ be modified during the updated callback.
-====
-
-By default the event raised is `ObjectUpdatedEvent.Default`. For example:
-
-[source,java]
-----
-@DomainObject
-public class ToDoItemDto {
- ...
-}
-----
-
-The purpose of the `updatedLifecycleEvent()` attribute is to allows a custom subclass to be emitted instead. A similar
-attribute is available for other lifecycle events.
-
-For example:
-
-[source,java]
-----
-@DomainObjectLayout(
- updatedLifecycleEvent=ToDoItem.UpdatedEvent.class
-)
-public class ToDoItem {
- public static class UpdatedEvent
- extends org.apache.isis.applib.services.eventbus.ObjectUpdatedEvent<ToDoItem> { }
- ...
-}
-----
-
-The benefit is that subscribers can be more targeted 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:rgsvc.adoc#_rgsvc_api_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(nature=NatureOfService.DOMAIN)
-public class SomeSubscriber extends AbstractSubscriber {
- @com.google.common.eventbus.Subscribe
- public void on(ObjectUpdatedEvent ev) {
- if(ev.getSource() instanceof ToDoItem) { ... }
- }
-}
-----
-
-or can be fine-grained (by subscribing to specific event subtypes):
-
-[source,java]
-----
-@DomainService(nature=NatureOfService.DOMAIN)
-public class SomeSubscriber extends AbstractSubscriber {
- @com.google.common.eventbus.Subscribe
- public void on(ToDoItem.ObjectUpdatedEvent ev) {
- ...
- }
-}
-----
-
-
-[TIP]
-====
-If the AxonFramework is being used, replace `@com.google.common.eventbus.Subscribe` with `@org.axonframework.eventhandling.annotation.EventHandler`.
-====
-
-
-
-
-
-== Default, Doop and Noop events
-
-If the `updatedLifecycleEvent` attribute is not explicitly specified (is left as its default value, `ObjectUpdatedEvent.Default`),
-then the framework will, by default, post an event.
-
-If this is not required, then the `isis.reflector.facet.domainObjectAnnotation.updatedLifecycleEvent.postForDefault`
-configuration property can be set to "false"; this will disable posting.
-
-On the other hand, if the `updatedLifecycleEvent` has been explicitly specified to some subclass, then an event will be posted.
-The framework provides `ObjectUpdatedEvent.Doop` as such a subclass, so setting the `updatedLifecycleEvent` attribute to this class
-will ensure that the event to be posted, irrespective of the configuration property setting.
-
-And, conversely, the framework also provides `ObjectUpdatedEvent.Noop`; if `updatedLifecycleEvent` attribute is set to this class,
-then no event will be posted.
-
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/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
deleted file mode 100644
index 0e9968c..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject_updatingLifecycleEvent.adoc
+++ /dev/null
@@ -1,114 +0,0 @@
-[[_rgant-DomainObject_updatingLifecycleEvent]]
-= updatingLifecycleEvent()
-: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 (persistent) domain object has been modified and is about to be updated to the database, an "updating"
-lifecycle event is fired.
-
-Subscribers subscribe through the xref:rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] and can
-use the event to obtain a reference to the domain object. The subscriber could then, for example, update the object,
-or it could use it maintain an external datastore. One possible application is to maintain a full-text search database
-using link:https://lucene.apache.org/[Apache Lucene] or similar.
-
-[NOTE]
-====
-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:rgcms.adoc#_rgcms_classes_roles_Timestampable[`Timestampable`] role interface.
-====
-
-By default the event raised is `ObjectUpdatingEvent.Default`. For example:
-
-[source,java]
-----
-@DomainObject
-public class ToDoItemDto {
- ...
-}
-----
-
-The purpose of the `updatingLifecycleEvent()` attribute is to allows a custom subclass to be emitted instead. A similar
-attribute is available for other lifecycle events.
-
-For example:
-
-[source,java]
-----
-@DomainObjectLayout(
- updatingLifecycleEvent=ToDoItem.UpdatingEvent.class
-)
-public class ToDoItem {
- public static class UpdatingEvent
- extends org.apache.isis.applib.services.eventbus.ObjectUpdatingEvent<ToDoItem> { }
- ...
-}
-----
-
-The benefit is that subscribers can be more targeted 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:rgsvc.adoc#_rgsvc_api_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(nature=NatureOfService.DOMAIN)
-public class SomeSubscriber extends AbstractSubscriber {
- @com.google.common.eventbus.Subscribe
- public void on(ObjectUpdatingEvent ev) {
- if(ev.getSource() instanceof ToDoItem) { ... }
- }
-}
-----
-
-or can be fine-grained (by subscribing to specific event subtypes):
-
-[source,java]
-----
-@DomainService(nature=NatureOfService.DOMAIN)
-public class SomeSubscriber extends AbstractSubscriber {
- @com.google.common.eventbus.Subscribe
- public void on(ToDoItem.ObjectUpdatingEvent ev) {
- ...
- }
-}
-----
-
-
-[TIP]
-====
-If the AxonFramework is being used, replace `@com.google.common.eventbus.Subscribe` with `@org.axonframework.eventhandling.annotation.EventHandler`.
-====
-
-
-
-
-
-== Default, Doop and Noop events
-
-If the `updatingLifecycleEvent` attribute is not explicitly specified (is left as its default value, `ObjectUpdatingEvent.Default`),
-then the framework will, by default, post an event.
-
-If this is not required, then the `isis.reflector.facet.domainObjectAnnotation.updatingLifecycleEvent.postForDefault`
-configuration property can be set to "false"; this will disable posting.
-
-On the other hand, if the `updatingLifecycleEvent` has been explicitly specified to some subclass, then an event will be posted.
-The framework provides `ObjectUpdatingEvent.Doop` as such a subclass, so setting the `updatingLifecycleEvent` attribute to this class
-will ensure that the event to be posted, irrespective of the configuration property setting.
-
-And, conversely, the framework also provides `ObjectUpdatingEvent.Noop`; if `updatingLifecycleEvent` attribute is set to this class,
-then no event will be posted.
-
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainService.adoc
deleted file mode 100644
index b782ea4..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainService.adoc
+++ /dev/null
@@ -1,72 +0,0 @@
-[[_rgant-DomainService]]
-= `@DomainService`
-: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 `@DomainService` annotation indicates that the (concrete) class should be automatically instantiated as a domain service.
-
-Domain services with this annotation do NOT need to be registered explicitly in `isis.properties`; they will be
-discovered automatically on the CLASSPATH.
-
-The table below summarizes the annotation's attributes.
-
-.`@DomainService` attributes
-[cols="2,2,4a", options="header"]
-|===
-
-| Attribute
-| Values (default)
-| Description
-
-
-|xref:rgant.adoc#_rgant-DomainService_nature[`nature()`]
-|`VIEW`, `VIEW_MENU_ONLY`, `VIEW_CONTRIBUTIONS_ONLY`, `VIEW_REST_ONLY`, `DOMAIN` (`VIEW`)
-|the nature of this service: providing actions for menus, or as contributed actions, or for the xref:ugvro.adoc#[RestfulObjects REST API], or neither
-
-
-|xref:rgant.adoc#_rgant-DomainService_objectType[`objectType()`]
-|
-|equivalent to xref:rgant.adoc#_rgant_DomainObject_objectType[`@DomainObject#objectType()`], specifies the objectType of the service.
-
-The instanceId for services is always "1".
-
-
-|xref:rgant.adoc#_rgant-DomainService_repositoryFor[`repositoryFor()`]
-|
-|if this domain service acts as a repository for an entity type, specify that entity type. This is used to determine an icon to use for the service (eg as shown in action prompts).
-
-
-|`menuOrder()`
-|
-|Deprecated in 1.8.0; use instead xref:rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`]
-
-|===
-
-
-
-For example:
-
-[source,java]
-----
-@DomainService(
- nature=NatureOfService.DOMAIN,
- repositoryFor=Loan.class
-)
-public class LoanRepository {
- @Programmatic
- public List<Loan> findLoansFor(Borrower borrower) { ... }
-}
-----
-
-
-
-include::_rgant-DomainService_nature.adoc[leveloffset=+1]
-include::_rgant-DomainService_objectType.adoc[leveloffset=+1]
-include::_rgant-DomainService_repositoryFor.adoc[leveloffset=+1]
-
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainServiceLayout.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainServiceLayout.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainServiceLayout.adoc
deleted file mode 100644
index effc805..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainServiceLayout.adoc
+++ /dev/null
@@ -1,78 +0,0 @@
-[[_rgant-DomainServiceLayout]]
-= `@DomainServiceLayout`
-: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 `@DomainServiceLayout` annotation applies to domain services, collecting together all view layout semantics within a single annotation.
-
-[TIP]
-====
-You will also find some additional material in the xref:ugfun.adoc#_ugfun_object-layout_application-menu[object layout] chapter.
-====
-
-
-The table below summarizes the annotation's attributes.
-
-.`@DomainServiceLayout` attributes
-[cols="2,2,4a", options="header"]
-|===
-
-| Attribute
-| Values (default)
-| Description
-
-
-|xref:rgant.adoc#_rgant-DomainServiceLayout_menuBar[`menuBar()`]
-|`PRIMARY`, `SECONDARY`, `TERTIARY` (`PRIMARY`).
-|the menubar in which the menu that holds this service's actions should reside.
-
-
-|xref:rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`menuOrder()`]
-|
-|the order of the service's menu with respect to other service's.
-
-
-|xref:rgant.adoc#_rgant-DomainServiceLayout_named[`named()`]
-|string, eg "Customers"
-|name of this class (overriding the name derived from its name in code)
-
-
-
-|===
-
-
-
-For example:
-
-[source,java]
-----
-@DomainService
-@DomainServiceLayout(
- menuBar=MenuBar.PRIMARY,
- menuOrder="100",
- named="ToDos"
-)
-public class ToDoItems {
- ...
-}
-----
-
-
-
-[NOTE]
-====
-Note that there is (currently) no support for specifying UI hints for domain services through the dynamic xref:ugfun.adoc#_ugfun_object-layout_dynamic[`.layout.json`] file (only for properties, collections and actions are supported).
-====
-
-
-
-include::_rgant-DomainServiceLayout_menuBar.adoc[leveloffset=+1]
-include::_rgant-DomainServiceLayout_menuOrder.adoc[leveloffset=+1]
-include::_rgant-DomainServiceLayout_named.adoc[leveloffset=+1]
-
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainServiceLayout_menuBar.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainServiceLayout_menuBar.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainServiceLayout_menuBar.adoc
deleted file mode 100644
index c3a4cf4..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainServiceLayout_menuBar.adoc
+++ /dev/null
@@ -1,43 +0,0 @@
-[[_rgant-DomainServiceLayout_menuBar]]
-= `menuBar()`
-: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 `menuBar()` attribute is a hint to specify where on the application menu a domain service's actions should be rendered.
-
-For example:
-
-[source,java]
-----
-@DomainService
-@DomainServiceLayout(menuBar=MenuBar.PRIMARY)
-public class ToDoItems {
- ...
-}
-----
-
-In the xref:ugvw.adoc#[Wicket viewer], domain services placed on the `PRIMARY` menu bar appears to the left:
-
-image::{_imagesdir}reference-annotations/DomainServiceLayout/menuBar-primary.png[width="720px",link="{_imagesdir}reference-annotations/DomainServiceLayout/menuBar-primary.png"]
-
-Domain services placed on the `SECONDARY` menu bar appear to the right:
-
-image::{_imagesdir}reference-annotations/DomainServiceLayout/menuBar-secondary.png[width="720px",link="{_imagesdir}reference-annotations/DomainServiceLayout/menuBar-secondary.png"]
-
-
-Domain services placed on the `TERTIARY` appear in the menu bar associated with the user's name (far top-right)
-
-image::{_imagesdir}reference-annotations/DomainServiceLayout/menuBar-tertiary.png[width="720px",link="{_imagesdir}reference-annotations/DomainServiceLayout/menuBar-tertiary.png"]
-
-
-The grouping of multiple domain services actions within a single drop-down is managed by the xref:rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] attribute.
-
-
-[NOTE]
-====
-The xref:ugvro.adoc#[RestfulObjects viewer] does not support this attribute.
-====
-
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainServiceLayout_menuOrder.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainServiceLayout_menuOrder.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainServiceLayout_menuOrder.adoc
deleted file mode 100644
index 1bb00e2..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainServiceLayout_menuOrder.adoc
+++ /dev/null
@@ -1,74 +0,0 @@
-[[_rgant-DomainServiceLayout_menuOrder]]
-= `menuOrder()`
-: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 `menuOrder()` attribute determines the ordering of a domain service's actions as menu items within a specified menu bar and top-level menu.
-
-
-The algorithm works as follows:
-
-* first, the xref:rgant.adoc#_rgant-DomainServiceLayout_menuBar[`menuBar()`] determines which of the three menu bars the service's actions should be rendered
-* then, the domain service's top-level name (typically explicitly specified using xref:rgant.adoc#_rgant-DomainServiceLayout_named[`named()`]) is used to determine the top-level menu item to be rendered on the menu bar
-* finally, if there is more than domain service that has the same name, then the `menuOrder` attribute is used to order those actions on the menu item drop-down.
-
-For example, the screenshot below shows the "prototyping" menu from the (non-ASF) http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp]:
-
-image::{_imagesdir}reference-annotations/DomainServiceLayout/menuOrder.png[width="500px",link="{_imagesdir}reference-annotations/DomainServiceLayout/menuOrder.png"]
-
-
-The xref:ugvw.adoc#[Wicket viewer] automatically places separators between actions from different domain services. From this we can infer that there are actually five different domain services that are all rendered on the "prototyping" top-level menu.
-
-One of these is the todoapp's `DemoDomainEventSubscriptions` service:
-
-[source,java]
-----
-@DomainService(
- nature = NatureOfService.VIEW_MENU_ONLY
-)
-@DomainServiceLayout(
- menuBar = MenuBar.SECONDARY,
- named = "Prototyping", // <1>
- menuOrder = "500.20") // <2>
-public class DemoDomainEventSubscriptions {
- @ActionLayout(named="Set subscriber behaviour")
- @MemberOrder(sequence = "500.20.1") // <3>
- public void subscriberBehaviour(...) { ... }
- ...
-}
-----
-<1> render on the "Prototyping" menu
-<2> positioning relative to other service's on the "Prototyping" menu
-<3> by convention (nothing more) the `@MemberOrder#sequence()` attribute continues the same Dewey decimal sequence format (a simple string "1" could in fact have been used instead)
-
-
-while another comes from the (non-ASF) http://github.com/isisaddons/isis-module-devutils[Isis addons' devutils] module:
-
-[source,java]
-----
-@DomainServiceLayout(
- menuBar = MenuBar.SECONDARY,
- named = "Prototyping", // <1>
- menuOrder = "500.600" // <2>
-)
-public class DeveloperUtilitiesServiceMenu {
- @MemberOrder( sequence = "500.600.1" ) // <3>
- public Clob downloadMetaModel() { ... }
- @MemberOrder( sequence = "500.600.2" )
- public Blob downloadLayouts() { ... }
- @ActionLayout(named = "Rebuild Services Meta Model")
- @MemberOrder( sequence = "500.600.3")
- public void refreshServices() { ... }
- ...
-}
-----
-<1> render on the "Prototyping" menu
-<2> positioning relative to other service's on the "Prototyping" menu; this appears after the `DemoDomainEventSubscriptions` service shown above
-<3> by convention (nothing more) the `@MemberOrder#sequence()` attribute continues the same Dewey decimal sequence format (a simple string "1", "2", "3", ... could in fact have been used instead)
-
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainServiceLayout_named.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainServiceLayout_named.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainServiceLayout_named.adoc
deleted file mode 100644
index 7a3f08b..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainServiceLayout_named.adoc
+++ /dev/null
@@ -1,29 +0,0 @@
-[[_rgant-DomainServiceLayout_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 service's name, overriding the name that would normally be inferred from the Java source code. This attribute can also be specified for xref:rgant.adoc#_rgant-ActionLayout_named[actions], xref:rgant.adoc#_rgant-CollectionLayout_named[collections], xref:rgant.adoc#_rgant-PropertyLayout_named[properties], xref:rgant.adoc#_rgant-ParameterLayout_named[parameters], xref:rgant.adoc#_rgant-DomainObjectLayout_named[domain objects] and xref:rgant.adoc#_rgant-ViewModelLayout_named[view models].
-
-
-[TIP]
-====
-The value of this attribute also has an important role to play in the positioning of the domain service's actions relative to the actions of other domain services. See xref:rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`menuOrder()`] for a full discussion with examples.
-====
-
-For example:
-
-[source,java]
-----
-@DomainService
-@DomainServiceLayout(
- named="Customers"
-)
-public class CustomerRepository {
- ...
-}
-----
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainService_nature.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainService_nature.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainService_nature.adoc
deleted file mode 100644
index 5c8a694..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainService_nature.adoc
+++ /dev/null
@@ -1,89 +0,0 @@
-[[_rgant-DomainService_nature]]
-= `nature()`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-By default, a domain service's actions will be rendered in the application menu bar _and_ be contributed _and_ appear in the REST API _and_ (of course) be available to invoke programmatically wherever that domain service is injected. This is great for initial prototyping, but later on you may prefer to add a little more structure. This is the purpose of the `nature()` attribute: to indicates the intent of (all of) the actions defined within the domain service.
-
-The values of the enum are:
-
-* `VIEW` +
-+
-The default; the service's actions appear on menu bars, can be contributed, appear in the REST API
-
-* `VIEW_MENU_ONLY` +
-+
-The service's actions appear on menus and in the REST API, but are not contributed to domain objects or view models
-
-* `VIEW_CONTRIBUTIONS_ONLY` +
-+
-The service's actions are intended only to be used as contributed actions/associations to domain objects and view models. +
-+
-The related xref:rgant.adoc#_rgant-ActionLayout_contributedAs[`@ActionLayout#contributedAs()`] determines whether any given (1-arg) action is contributed as an association rather than an action.
-
-* `VIEW_REST_ONLY` +
-+
-The service's actions are intended only to be listed in the REST API exposed by the xref:ugvro.adoc#[RestfulObjects viewer].
-
-* `DOMAIN` +
-+
-The service and its actions are only intended to be invoked programmatically; they are a domain layer responsibility.
-
-
-The actual class name of the domain service is only rendered for the `VIEW`, `VIEW_MENU_ONLY` and `VIEW_REST_ONLY` natures. Thus, you might also want to adopt naming conventions for your domain classes so you can infer the nature from the class. For example, the naming convention adopted (by and large) by the (non-ASF) link:http://isisaddons.org[Isis Addons] is `ProgrammaticServices` or `Repository` as a suffix for `DOMAIN` services, and `Contributions` as a suffix for `VIEW_CONTRIBUTIONS_ONLY` services.
-
-For example:
-
-[source,java]
-----
-@DomainService(
- nature=NatureOfService.VIEW_CONTRIBUTIONS_ONLY
-)
-public class LoanContributions { // <1>
- @Action(semantics=SemanticsOf.SAFE) // <2>
- @ActionLayout(contributed=Contributed.AS_ASSOCIATION )
- public List<Loan> currentLoans(Borrower borrower) { ... }
- public Borrower newLoan(Borrower borrower, Book book) { ... }
-}
-----
-<1> `Contributions` as a suffix for a domain service that contributes a number of actions to ``Borrower``s. Note that `Borrower` could be a (marker) interface, so this functionality is "mixed in" merely by the class (eg `LibraryMember`) implementing this interface
-<2> actions contibuted as associations (a collection in this case) must have safe semantics
-
-
-Another example:
-
-[source,java]
-----
-@DomainService(
- nature=NatureOfService.DOMAIN
-)
-public class LoanRepository { // <1>
- @Programmatic // <2>
- public List<Loan> findLoansFor(Borrower borrower) { ... }
-}
-----
-<1> `Repository` as a suffix for a domain-layer service
-<2> methods on `DOMAIN` services are often xref:rgant.adoc#_rgant-Programmatic[`@Programmatic`]; they will never be exposed in the UI, so there's little point in including them in Apache Isis' metamodel
-
-
-
-A final example:
-
-[source,java]
-----
-@DomainService(
- nature=NatureOfService.VIEW_MENU_ONLY
-)
-public class Loans { // <1>
- @Action(semantics=SemanticsOf.SAFE)
- public List<Loan> findOverdueLoans() { ... }
- @Inject
- LoanRepository loanRepository; // <2>
-}
-----
-<1> name is intended to be rendered in the UI
-<2> it's common for domain-layer domain services to be injected into presentation layer services (such as `VIEW_MENU_ONLY` and `VIEW_CONTRIBUTIONS_ONLY`).
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainService_objectType.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainService_objectType.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainService_objectType.adoc
deleted file mode 100644
index 285d4f3..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainService_objectType.adoc
+++ /dev/null
@@ -1,58 +0,0 @@
-[[_rgant-DomainService_objectType]]
-= `objectType()`
-: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 `objectType()` attribute is used to provide a unique alias for the domain service's class name.
-
-This value is used internally to generate a string representation of an service identity (the `Oid`).
-This can appear in several contexts, including:
-
-* as the value of `Bookmark#getObjectType()` and in the `toString()` value of `Bookmark`
- (see xref:rgsvc.adoc#_rgsvc_api_BookmarkService[`BookmarkService`])
-* in the serialization of `OidDto` in the xref:rgcms.adoc#_rgcms_schema-cmd[command] and xref:rgcms.adoc#_rgcms_schema-ixn[interaction] schemas
-* in the URLs of the xref:ugvro.adoc#[RestfulObjects viewer]
-* in the URLs of the xref:ugvw.adoc#[Wicket viewer] (specifically, for bookmarked actions)
-
-
-
-== Example
-
-For example:
-
-[source,java]
-----
-@DomainService(
- objectType="orders.OrderMenu"
-)
-public class OrderMenu {
- ...
-}
-----
-
-
-
-== Precedence
-
-The rules of precedence are:
-
-1. `@DomainService#objectType`
-2. xref:rgcms.adoc#_rgcms_methods_reserved_getId[`getId()`]
-3. The fully qualified class name.
-
-
-[TIP]
-====
-This might be obvious, but to make explicit: we recommend that you always specify an object type for your domain services.
-
-Otherwise, if you refactor your code (change class name or move package), then any externally held references to the OID of the service will break.
-At best this will require a data migration in the database; at worst it could cause external clients accessing data through the xref:ugvro.adoc#[Restful Objects] viewer to break.
-====
-
-[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/2669a971/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainService_repositoryFor.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainService_repositoryFor.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainService_repositoryFor.adoc
deleted file mode 100644
index 8b62b8d..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainService_repositoryFor.adoc
+++ /dev/null
@@ -1,26 +0,0 @@
-[[_rgant-DomainService_repositoryFor]]
-= `repositoryFor()`
-: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 `repositoryFor()` attribute is intended for domain services (probably with a xref:rgant.adoc#_rgant-DomainService_nature[`nature=DOMAIN`]) that are intended to act as repositories for domain entities.
-
-For example:
-
-[source,java]
-----
-@DomainService(
- nature=NatureOfService.DOMAIN,
- repositoryFor=Loan.class
-)
-public class LoanRepository {
- @Programmatic
- public List<Loan> findLoansFor(Borrower borrower) { ... }
-}
-----
-
-
-Currently the metadata is unused; one planned use is to infer the icon for the domain service from the icon of the nominated entity.
-
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/_rgant-Facets.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-Facets.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-Facets.adoc
deleted file mode 100644
index 2e157ec..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-Facets.adoc
+++ /dev/null
@@ -1,15 +0,0 @@
-[[_rgant-Facets]]
-= `@Facets`
-: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 `@Facets` annotation allows `FacetFactory` implementations and so can be used to run install arbitrary `Facet`s for a type. Generally this is not needed, but can be useful for overriding a custom programming model where a `FacetFactory` is not typically included.
-
-
-[NOTE]
-====
-`FacetFactory` is an important internal API that is used by Apache Isis to
-====
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/_rgant-HomePage.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-HomePage.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-HomePage.adoc
deleted file mode 100644
index ade4095..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-HomePage.adoc
+++ /dev/null
@@ -1,52 +0,0 @@
-[[_rgant-HomePage]]
-= `@HomePage`
-: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 `@HomePage` annotation allows a _single_ (no-arg, query-only) action on a _single_ domain service to be nominated as the action to invoke for the default home page. This often returns a view model that acts as some sort of dashboard, presenting key information and makeing the most commonly used actions easy to invoke.
-
-For example, the (non-ASF) http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp] uses `@HomePage` to return a dashboard of todo items to complete:
-
-image::{_imagesdir}reference-annotations/HomePage/HomePage.png[width="800px",link="{_imagesdir}reference-annotations/HomePage/HomePage.png"]
-
-
-The corresponding code is:
-
-[source,java]
-----
-@DomainService(nature = NatureOfService.DOMAIN)
-public class ToDoAppDashboardService {
- @Action(
- semantics = SemanticsOf.SAFE
- )
- @HomePage
- public ToDoAppDashboard lookup() {
- return container.injectServicesInto(new ToDoAppDashboard());
- }
- @Inject
- private DomainObjectContainer container;
-}
-----
-
-where `ToDoAppDashboard` is:
-
-[source,java]
-----
-@DomainObject(nature = Nature.VIEW_MODEL)
-public class ToDoAppDashboard {
- public String title() { return "Dashboard"; }
-
- public List<ToDoItem> getNotYetComplete() { ... }
- public List<ToDoItem> getComplete() { ... }
-
- public Blob exportToWordDoc() { ... } // <1>
-}
-----
-<1> associated using xref:ugfun.adoc#_ugfun_object-layout_dynamic[dynamic layouts] with the `notYetComplete` collection.
-
-The other two actions shown in the above screenshot -- `exportAsXml` and `downloadLayout` -- are actually contributed to the `ToDoAppDashboard` through various domain services, as is the `downloadLayout` action.
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/_rgant-Inject.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-Inject.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-Inject.adoc
deleted file mode 100644
index 8c06d4b..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-Inject.adoc
+++ /dev/null
@@ -1,154 +0,0 @@
-[[_rgant-Inject]]
-= `@Inject` (`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/
-
-
-
-Apache Isis automatically injects domain services into other domain services and also into domain objects and view models. In fact, it also injects domain services into xref:ugtst.adoc#_ugtst_integ-test-support[integration tests] and xref:ugtst.adoc#_ugtst_fixture-scripts[fixture scripts].
-
-[NOTE]
-====
-One omission: Apache Isis (currently) does not inject services into `o.a.i.applib.spec.Specification` instances (as used by xref:rgant.adoc#_rgant-Property_mustSatisfy[`@Property#mustSatisfy()`] and xref:rgant.adoc#_rgant-Parameter_mustSatisfy[`@Parameter#mustSatisfy()`] annotations.
-====
-
-Isis supports several syntaxes for injecting domain services. The simplest uses the `@javax.inject.Inject` annotation on the field, as defined in link:https://jcp.org/en/jsr/detail?id=330[JSR-330].
-
-For example:
-
-[source,java]
-----
-public class Customer {
- public List<Order> findRecentOrders() { // <1>
- return orders.recentOrdersFor(this);
- }
- @javax.inject.Inject
- OrderRepository orders; // <2>
-}
-----
-<1> an alternative implementation would be to implement `findRecentOrders()` as a xref:ugfun.adoc#_ugfun_how-tos_contributed-members[contributed action].
-<2> we recommend default (rather than `private`) visibility so that unit tests can easily mock out the service
-
-
-
-== Alternative syntaxes
-
-Isis also supports setter-based injection:
-
-[source,java]
-----
-public class Customer {
- ...
- public void setOrderRepository(OrderRepository orderRepository) { ... }
-}
-----
-
-and also supports an additional syntax of using `inject...` as the prefix:
-
-[source,java]
-----
-public class Customer {
- ...
- public void injectOrderRepository(OrderRepository orderRepository) { ... }
-}
-----
-
-Generally we recommend using `@javax.inject.Inject`; it involves less code, and is more immediately familiar to most Java developers.
-
-
-
-== Injecting collection of services
-
-It can sometimes be useful to have declared multiple implementations of a particular domain service. For example,
-you may have a module that defines an SPI service, where multiple other modules might provide implementations of that SPI
- (akin to the chain of responsibility pattern). To support these scenarios, it is possible to annotate a `List` or `Collection`.
-
-For example, suppose that we provide an SPI service to veto the placing of ``Order``s for certain ``Customer``s:
-
-[source,java]
-----
-public interface CustomerOrderAdvisorService {
- @Programmatic
- String vetoPlaceOrder(Customer c);
-----
-
-We could then inject a collection of these services:
-
-[source,java]
-----
-public class Customer {
- public Order placeOrder(Product p, int quantity) { ... }
- public String disablePlaceOrder(Product p, int quantity) {
- for(CustomerOrderAdvisorService advisor: advisors) {
- String reason = advisor.vetoPlaceOrder(this);
- if(reason != null) { return reason; }
- }
- return null;
- }
- @Inject
- Collection<CustomerOrderAdvisorService> advisors; // <1>
-}
-----
-<1> inject a collection of the services.
-
-[NOTE]
-====
-An alternative and almost equivalent design would be to publish an event using the xref:rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] and implement the domain services as subscribers to
-the event. This alternative design is used in the (non-ASF) http://github.com/isisaddons/isis-module-poly[Isis addons' poly] module, for example.
-====
-
-
-
-
-
-== Manually injecting services
-
-Isis performs dependency injection when domain entities are recreated. It will also perform dependency injection if an object is created through the `DomainObjectContainer`.
-
-For example, to create a new (transient) domain object, the idiom is:
-
-[source,java]
-----
-Customer cust = container.newTransientInstance(Customer.class); <1>
-// initialize state of "cust"
-container.persist(cust);
-----
-<1> where `container` is an instance of xref:rgsvc.adoc#_rgsvc_api_DomainObjectContainer[`DomainObjectContainer`].
-
-View models are created similarly:
-
-[source,java]
-----
-ToDoAppDashboard dashboard = container.newViewModelInstance(ToDoAppDashboard.class);
-----
-
-
-If you prefer, though, you can simply instantiate domain objects using "new" and then inject domain services manually:
-
-
-[source,java]
-----
-Customer cust = new Customer();
-container.injectServicesInto(cust);
-// initialize state of "cust"
-container.persist(cust);
-----
-
-
-or if you prefer:
-
-[source,java]
-----
-Customer cust = container.injectServicesInto(new Customer());
-// initialize state of "cust"
-container.persist(cust);
-----
-
-
-[NOTE]
-====
-There is one subtle difference between using `DomainObjectContainer#newTransientInstance(...)` and `DomainObjectContainer#injectServicesInto(...)`, in that with the former Apache Isis will automatically initialize all fields to their default values.
-
-This isn't a particular useful feature (and indeed can sometimes be rather confusing) so you may well wish to standardize on using `injectServicesInto(...)` throughout.
-====
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/_rgant-MemberGroupLayout.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-MemberGroupLayout.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-MemberGroupLayout.adoc
deleted file mode 100644
index acb285a..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-MemberGroupLayout.adoc
+++ /dev/null
@@ -1,20 +0,0 @@
-[[_rgant-MemberGroupLayout]]
-= `@MemberGroupLayout`
-: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 `@MemberGroupLayout` annotation specifies how an object's properties and collections are grouped together into columns, also specifying the relative positioning of those columns. It works in conjunction with the xref:rgant.adoc#_rgant-MemberOrder[`@MemberOrder`] annotation.
-
-
-The `@MemberOrder` annotation is used to specify the relative order of domain object members, that is: properties, collections and actions. It works in conjunction with the xref:rgant.adoc#_rgant-MemberGroupLayout[`@MemberGroupLayout`] annotation.
-
-The annotation defines two attributes, `name()` and `sequence()`. Broadly speaking the `name()` attribute is used to group or associate members together, while the `sequence()` attribute orders members once they have been grouped.
-
-
-[IMPORTANT]
-====
-As this is an important topic, there is a xref:ugfun.adoc#_ugfun_object-layout[separate chapter] that discussed object layout in full.
-====
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/_rgant-MemberOrder.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-MemberOrder.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-MemberOrder.adoc
deleted file mode 100644
index f09c574..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-MemberOrder.adoc
+++ /dev/null
@@ -1,35 +0,0 @@
-[[_rgant-MemberOrder]]
-= `@MemberOrder`
-: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 `@MemberOrder` annotation is used to specify the relative order of domain object members, that is: properties, collections and actions. It works in conjunction with the xref:rgant.adoc#_rgant-MemberGroupLayout[`@MemberGroupLayout`] annotation.
-
-The annotation defines four attributes:
-
-* `columnSpans()` -- of type `int[]` -- which specifies the relative column sizes of the three columns that render properties as well as a fourth column that renders only collections
-
-* `left()` -- of type `String[]` - that specifies the order of the property groups (inferred from `@MemberOrder#name()`) as applied to properties) in the left-most column
-
-* `middle()` -- of type `String[]` - that specifies the order of the property groups (if any) as applied to properties) in the middle column
-
-* `right()` -- of type `String[]` - that specifies the order of the property groups (if any) as applied to properties) in the right-most column
-
-Collections are always rendered in the "last" column. This can appear either below the columns holding properties (if their column spans = 12), or can be rendered to the right of the property columns (if the spans of the property columns come to <12 leaving enough room for the span of the collection column).
-
-[IMPORTANT]
-====
-As this is an important topic, there is a xref:ugfun.adoc#_ugfun_object-layout[separate chapter] that discussed object layout in full.
-====
-
-
-[TIP]
-====
-The annotation is one of a handful (others including xref:rgant.adoc#_rgant-Collection[`@Collection`], xref:rgant.adoc#_rgant-CollectionLayout[`@CollectionLayout`], xref:rgant.adoc#_rgant-Property[`@Property`])
- and xref:rgant.adoc#_rgant-PropertyLayout[`@PropertyLayout`] that can also be applied to the field, rather than the getter method. This is specifically
-so that boilerplate-busting tools such as link:https://projectlombok.org/[Project Lombok] can be used.
-====
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/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
deleted file mode 100644
index c797013..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-MinLength.adoc
+++ /dev/null
@@ -1,32 +0,0 @@
-[[_rgant-MinLength]]
-= `@MinLength`
-: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 `@MinLength` annotation is used to specify the minimum number of characters in a search of an xref:rgcms.adoc#_rgcms_methods_prefixes_autoComplete[`autoComplete...()`] supporting method.
-
-
-For example:
-
-[source,java]
-----
-public ToDoItem add(
- @TypicalLength(20)
- final ToDoItem toDoItem) {
- getDependencies().add(toDoItem);
- return this;
-}
-public List<ToDoItem> autoComplete0Add(
- final @MinLength(2)
- String search) {
- final List<ToDoItem> list = toDoItems.autoComplete(search);
- list.removeAll(getDependencies());
- list.remove(this);
- return list;
-}
-----
-
-
-The `@Parameter(minLength=...)`e can also be used (even though strictly speaking the search argument is not a parameter of the action).
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/_rgant-Mixin.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-Mixin.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-Mixin.adoc
deleted file mode 100644
index 765ab7e..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-Mixin.adoc
+++ /dev/null
@@ -1,40 +0,0 @@
-[[_rgant-Mixin]]
-= `@Mixin`
-: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 `@Mixin` annotation indicates that the class acts as a mixin, contributing behaviour - actions, (derived) properties and (derived) collections - to another domain object.
-
-Mixins were originally introduced as a means of allowing contributions from one module to the types of another module; in such cases the mixin type is often an interface type (eg `DocumentHolder`) that might be implemented by numerous different concrete types.
-However, mixins are also a convenient mechanism for grouping functionality even for a concrete type.
-
-For further discussion on using mixins, see xref:ugbtb.adoc#_ugbtb_decoupling_mixins[mixins] in the user guide.
-
-The table below summarizes the annotation's attributes.
-
-.`@Mixin` attributes
-[cols="2,2,4a", options="header"]
-|===
-
-
-| Attribute
-| Values (default)
-| Description
-
-
-|xref:rgant.adoc#_rgant-Mixin_method[`method()`]
-|Method name within the mixin
-|How to recognize the "reserved" method name, meaning that the mixin's own name will be inferred from the mixin type.
-Typical examples are "exec", "execute", "invoke", "apply" and so on.
-The default "reserved" method name is `$$`.
-
-|===
-
-An alternative and equivalent approach is to use the
-xref:rgant.adoc#_rgant-DomainObject_nature[`@DomainObject#nature()`] annotation with a nature of `MIXIN`.
-
-
-include::_rgant-Mixin_method.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/_rgant-Mixin_method.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-Mixin_method.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-Mixin_method.adoc
deleted file mode 100644
index 21bb51b..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-Mixin_method.adoc
+++ /dev/null
@@ -1,41 +0,0 @@
-[[_rgant-Mixin_method]]
-= `method()`
-: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 `method()` attribute specifies the name of the method to be treated as a "reserved" method name, meaning that the mixin's name should instead be inferred from the mixin's type.
-
-For example:
-
-[source,java]
-----
-@DomainObject
-public class Customer {
-
- @Mixin(method="execute")
- public static class placeOrder {
-
- Customer customer;
- public placeOrder(Customer customer) { this.customer = customer; }
-
- public Customer execute(Product p, int quantity) { ... }
- public String disableExecute() { ... }
- public String validate0Execute() { ... }
- }
- ...
-)
-----
-
-This allows all mixins to follow a similar convention, with the name of the mixin inferred entirely from its type ("placeOrder").
-
-When invoked programmatically, the code reads:
-
-[source,java]
-----
-mixin(Customer.placeOrder.class, someCustomer).execute(someProduct, 3);
-----
-
-