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/05/12 10:25:59 UTC
[10/18] isis git commit: ISIS-1594: updates domain service .adoc
names and ids,
so that the edit buttons are added correctly to subdocuments. Also some
further minor improvements on scrolling.
http://git-wip-us.apache.org/repos/asf/isis/blob/20b83ae7/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_application-layer-spi_BackgroundCommandService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_application-layer-spi_BackgroundCommandService.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_application-layer-spi_BackgroundCommandService.adoc
new file mode 100644
index 0000000..16102d3
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_application-layer-spi_BackgroundCommandService.adoc
@@ -0,0 +1,132 @@
+[[_rgsvc_application-layer-spi_BackgroundCommandService]]
+= `BackgroundCommandService`
+: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 `BackgroundCommandService` (SPI) service supports the xref:../rgsvc/rgsvc.adoc#_rgsvc_application-layer-api_BackgroundService[`BackgroundService`] (API) service, persisting action invocations as commands such that they can subsequently be invoked in the background.
+
+The `BackgroundService` is responsible for capturing a memento representing the action invocation, and then hands off to the xref:../rgsvc/rgsvc.adoc#_rgsvc_application-layer-spi_BackgroundCommandService[`BackgroundCommandService`] `BackgroundCommandService` to actually persist it.
+
+The persisting of commands is only half the story; there needs to be a separate process to read the commands and execute them. The abstract xref:../rgsvc/rgsvc.adoc#_rgsvc_application-layer-api_BackgroundService_BackgroundCommandExecution[`BackgroundCommandExecution`] provides a mechanism to execute such commands. This can be considered an API, albeit "internal" because the implementation relies on internals of the framework.
+
+
+
+
+== SPI
+
+The SPI of the `BackgroundCommandService` is:
+
+[source,java]
+----
+public interface BackgroundCommandService {
+ void schedule(
+ ActionInvocationMemento aim, // <1>
+ Command parentCommand, // <2>
+ String targetClassName,
+ String targetActionName,
+ String targetArgs);
+
+}
+----
+<1> is a wrapper around a xref:../rgsvc/rgsvc.adoc#_rgsvc_integration-api_MementoService[`MementoService`]'s `Memento`, capturing the details of the action invocation to be retained (eg persisted to a database) so that it can be executed at a later time
+<2> reference to the parent `Command` requesting the action be performed as a background command. This allows information such as the initiating user to be obtained.
+
+The API of `ActionInvocationMemento` in turn is:
+
+[source,java]
+----
+public class ActionInvocationMemento {
+ public String getActionId() { ... }
+ public String getTargetClassName() { ... }
+ public String getTargetActionName() { ... }
+ public Bookmark getTarget() { ... }
+ public int getNumArgs() { ... }
+ public Class<?> getArgType(int num) throws ClassNotFoundException { ... }
+ public <T> T getArg(int num, Class<T> type) { ... }
+
+ public String asMementoString() { ... } // <1>
+}
+----
+<1> lets the `BackgroundCommandService` implementation convert the action invocation into a simple string.
+
+
+
+== "Internal" SPI
+
+The `BackgroundCommandExecution` (in isis-core) is an abstract template class for xref:../ugbtb/ugbtb.adoc#_ugbtb_headless-access_AbstractIsisSessionTemplate[headless access], that defines an abstract hook method to obtain background `Command`s to be executed:
+
+[source,java]
+----
+public abstract class BackgroundCommandExecution
+ extends AbstractIsisSessionTemplate {
+ ...
+ protected abstract List<? extends Command> findBackgroundCommandsToExecute();
+ ...
+}
+----
+
+The developer is required to implement this hook method in a subclass.
+
+
+
+
+== Implementation
+
+The (non-ASF) http://github.com/isisaddons/isis-module-command[Isis addons' command] module provides an implementation (`org.isisaddons.module.command.dom.BackgroundCommandServiceJdo`) that persists ``Command``s using the JDO/DataNucleus object store. It further provides a number of supporting services:
+
+* `org.isisaddons.module.command.dom.BackgroundCommandServiceJdoRepository` is a repository to search for persisted background ``Command``s
+
+* `org.isisaddons.module.command.dom.BackgroundCommandServiceJdoContributions` contributes actions for searching for persisted child and sibling ``Command``s.
+
+The module also provides a concrete subclass of `BackgroundCommandExecution` that knows how to query for persisted (background) `Command`s such that they can be executed by a scheduler.
+
+[TIP]
+====
+Details of setting up the Quartz scheduler to actually execute these persisted commands can be found on the xref:../rgsvc/rgsvc.adoc#_rgsvc_application-layer-api_BackgroundService[`BackgroundService`] page.
+====
+
+
+
+
+== Usage
+
+Background commands can be created either declaratively or imperatively.
+
+The declarative approach involves annotating an action using xref:../rgant/rgant.adoc#_rgant-Action_command[`@Action#command()`] with `@Action#commandExecuteIn=CommandExecuteIn.BACKGROUND`.
+
+The imperative approach involves explicitly calling the xref:../rgsvc/rgsvc.adoc#_rgsvc_application-layer-api_BackgroundService[`BackgroundService`] from within domain object's action.
+
+
+
+
+== Registering the Services
+
+The (non-ASF) http://github.com/isisaddons/isis-module-command[Isis addons' command] module provides an implementation
+of this service (`BackgroundCommandService`), and also provides a number of related domain services
+(`BackgroundCommandServiceJdo`, `BackgroundCommandJdoRepository` and `BackgroundCommandServiceJdoContributions`). This
+module also provides service implementations of the
+xref:../rgsvc/rgsvc.adoc#_rgsvc_application-layer-spi_CommandService[`CommandService`].
+
+Assuming that an `AppManifest` is being used to xref:../rgcms/rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app])
+then this can be activated by updating the `pom.xml` and updating the `AppManifest#getModules()` method.
+
+If contributions are not required in the UI, these can be suppressed either using security or by implementing a
+xref:../ugbtb/ugbtb.adoc#_ugbtb_hints-and-tips_vetoing-visibility[vetoing subscriber].
+
+
+
+
+
+== Related Services
+
+As discussed above, this service supports the xref:../rgsvc/rgsvc.adoc#_rgsvc_application-layer-api_BackgroundService[`BackgroundService`] , persisting `Command`s such that they can be executed in the background.
+
+There is also a tie-up with the xref:../rgsvc/rgsvc.adoc#_rgsvc_application-layer-api_CommandContext[`CommandContext`] and its supporting xref:../rgsvc/rgsvc.adoc#_rgsvc_application-layer-spi_CommandService[`CommandService`] domain service. The `CommandContext` service is responsible for providing a parent `Command` with which the background `Command`s can then be associated as children, while the `CommandService` is responsible for persisting those parent `Command`s (analogous to the way in which the `BackgroundCommandService` persists the child background `Command`s). The `BackgroundCommandService` ensures that these background `Command`s are associated with the parent "foreground" `Command`.
+
+What that means is that the implementations of `CommandService` and `BackgroundCommandService` go together, hence both implemented in the (non-ASF) http://github.com/isisaddons/isis-module-command[Isis addons' command] module.).
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/20b83ae7/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_application-layer-spi_CommandService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_application-layer-spi_CommandService.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_application-layer-spi_CommandService.adoc
new file mode 100644
index 0000000..a822fa3
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_application-layer-spi_CommandService.adoc
@@ -0,0 +1,121 @@
+[[_rgsvc_application-layer-spi_CommandService]]
+= `CommandService`
+: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 `CommandService` service supports the xref:../rgsvc/rgsvc.adoc#_rgsvc_application-layer-api_CommandContext[`CommandContext`] service such
+that `Command` objects (that reify the invocation of an action/edit of a property on a domain object) can be persisted.
+
+As of `1.13.0`, the primary use case for persistent ``Command``s is in support of background commands; they
+act as a parent to any background commands that can be persisted either explicitly using the
+xref:../rgsvc/rgsvc.adoc#_rgsvc_application-layer-api_BackgroundService[`BackgroundService`], or implicitly by way of the
+xref:../rgant/rgant.adoc#_rgant-Action_command[`@Action#command()`] annotation.
+
+In previous versions of the framework, persistent ``Command``s also supported a number of other use cases:
+
+* they enable profiling of the running application (which actions are invoked then most often, what is their response time)
+* if xref:../rgsvc/rgsvc.adoc#_rgsvc_persistence-layer-spi_PublisherService[`PublisherService`] or
+xref:../rgsvc/rgsvc.adoc#_rgsvc_persistence-layer-spi_PublishingService[`PublishingService`] (latter deprecated) is configured, they provide
+better traceability as the `Command` is also correlated with any published events, again through the unique
+`transactionId` GUID
+* if xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_AuderService[`AuditerService`] or
+xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_AuditService[`AuditingService`] (latter deprecated) is configured, they provide better audit
+information, since the `Command` (the 'cause' of an action) can be correlated to the audit records (the "effect" of
+the action) through the `transactionId` GUID
+
+As of `1.13.0`, these other uses cases are now more fully supported through the
+xref:../rgsvc/rgsvc.adoc#_rgsvc_application-layer-api_InteractionContext[`InteractionContext`] service and persistent implementations of the
+``Interaction`` object, eg as provided by the (non-ASF)
+http://github.com/isisaddons/isis-module-publishmq[Isis addons' publishmq] module.
+
+
+
+== Screencast
+
+The link:https://www.youtube.com/watch?v=tqXUZkPB3EI[screencast] below provides a run-through of the command (profiling) service, auditing service, publishing service. It also shows how commands can be run in the background either explicitly by scheduling through the background service or implicitly by way of a framework annotation.
+
+
+[NOTE]
+====
+Note that this screencast shows an earlier version of the xref:../ugvw/ugvw.adoc#[Wicket viewer] UI (specifically, pre 1.8.0).
+====
+
+
+
+== SPI
+
+The `CommandService` service defines the following very simple API:
+
+[source,java]
+----
+public interface CommandService {
+ Command create(); // <1>
+ @Deprecated
+ void startTransaction(Command command, UUID transactionId); // <2>
+ boolean persistIfPossible(Command command); // <3>
+ void complete(Command command); // <4>
+}
+----
+<1> Instantiate the appropriate instance of the `Command` (as defined by the
+xref:../rgsvc/rgsvc.adoc#_rgsvc_application-layer-api_CommandContext[`CommandContext`] service). Its members will be populated automatically by
+the framework.
+<2> this method (as of `1.13.0`) is *NO LONGER CALLED* and is deprecated: the framework automatically populates the ``Command``'s `timestamp`,
+`user` and `transactionId` fields, so there is no need for the service implementation to initialize any of these. In
+particular, the ``Command`` will already have been initialized with the provided `transactionId` argument.
+<3> Set the hint that the `Command` should be persisted if possible (when completed, see below).
+<4> "Complete" the command, typically meaning that the command should be persisted it if its `Command#getPersistence()`
+flag and persistence hint (`Command#isPersistHint()`) indicate that it should be. +
++
+The framework will automatically have set the `completedAt` property of the `Command`.
+
+
+== Implementation
+
+The (non-ASF) http://github.com/isisaddons/isis-module-command[Isis addons' command] module provides an implementation (`org.isisaddons.module.command.dom.CommandServiceJdo`) that persists ``Command``s using the JDO/DataNucleus object store. It further provides a number of supporting services:
+
+* `org.isisaddons.module.command.dom.CommandServiceJdoRepository` is a repository to search for persisted ``Command``s
+
+* `org.isisaddons.module.command.dom.CommandServiceJdoContributions` contributes actions for searching for persisted child and sibling ``Command``s.
+
+
+
+== Usage
+
+The typical way to indicate that an action should be reified into a `Command` is by annotating the action using xref:../rgant/rgant.adoc#_rgant-Action_command[`@Action#command()`].
+
+
+
+
+== Registering the Services
+
+The (non-ASF) http://github.com/isisaddons/isis-module-command[Isis addons' command] module provides an implementation
+of this service (`CommandService`), and also provides a number of related domain services
+(`CommandJdoRepository` and `CommandServiceJdoContributions`). This
+module also provides service implementations of the
+xref:../rgsvc/rgsvc.adoc#_rgsvc_application-layer-spi_CommandService[`BackgroundCommandService`].
+
+Assuming that an `AppManifest` is being used to xref:../rgcms/rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app])
+then this can be activated by updating the `pom.xml` and updating the `AppManifest#getModules()` method.
+
+If contributions are not required in the UI, these can be suppressed either using security or by implementing a
+xref:../ugbtb/ugbtb.adoc#_ugbtb_hints-and-tips_vetoing-visibility[vetoing subscriber].
+
+
+
+
+== Related Services
+
+As discussed above, this service supports the xref:../rgsvc/rgsvc.adoc#_rgsvc_application-layer-api_CommandContext[`CommandContext`], providing the ability for `Command` objects to be
+persisted. This is closely related to the xref:../rgsvc/rgsvc.adoc#_rgsvc_application-layer-spi_BackgroundCommandService[`BackgroundCommandService`]that allows the xref:../rgsvc/rgsvc.adoc#_rgsvc_application-layer-api_BackgroundService[`BackgroundService`] to schedule commands for background/asynchronous execution.
+
+The implementations of `CommandService` and `BackgroundCommandService` are intended to go together, so that persistent parent `Command`s can be associated with their child background `Command`s.
+
+The services provided by this module combines very well with the xref:../rgsvc/rgsvc.adoc#_rgsvc_persistence-layer-spi_AuditingService[`AuditingService`]. The `CommandService` captures the _cause_ of an interaction (an action was invoked, a property was edited), while the `AuditingService3` captures the _effect_ of that interaction in terms of changed state.
+
+You may also want to configure the xref:../rgsvc/rgsvc.adoc#_rgsvc_persistence-layer-spi_PublishingService[`PublishingService`].
+
+All three of these services collaborate implicitly by way of the xref:../rgcms/rgcms.adoc#_rgcms_classes_mixins_HasTransactionId[`HasTransactionId`] interface.
+
http://git-wip-us.apache.org/repos/asf/isis/blob/20b83ae7/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_application-layer-spi_HomePageProviderService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_application-layer-spi_HomePageProviderService.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_application-layer-spi_HomePageProviderService.adoc
new file mode 100644
index 0000000..1520b2e
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_application-layer-spi_HomePageProviderService.adoc
@@ -0,0 +1,40 @@
+[[_rgsvc_application-layer-spi_HomePageProviderService]]
+= `HomePageProviderService`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../../
+:_imagesdir: images/
+
+
+
+This service simply provides access to the home page object (if any) that is returned from the domain service
+action annotated with xref:../rgant/rgant.adoc#_rgant-HomePage[`@HomePage`].
+
+It is originally introduced to support the default implementation of
+xref:../rgsvc/rgsvc.adoc#_rgsvc_presentation-layer-spi_RoutingService[`RoutingService`], but was factored out to support alternative implementations
+of that service (and may be useful for other use cases).
+
+
+== SPI & Implementation
+
+The SPI defined by `HomePageProviderService` is:
+
+[source,java]
+----
+@DomainService(nature = NatureOfService.DOMAIN)
+public interface HomePageProviderService {
+ @Programmatic
+ Object homePage();
+}
+----
+
+The default implementation is provided by `o.a.i.core.runtime.services.homepage.HomePageProviderServiceDefault`.
+
+
+
+== Registering the Service
+
+Assuming that the `configuration-and-annotation` services installer is configured (implicit if using the
+`AppManifest` to xref:../rgcms/rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' core
+implementation of `HomePageProviderService` is automatically registered (it is annotated with `@DomainService`) so no further
+configuration is required.
+
http://git-wip-us.apache.org/repos/asf/isis/blob/20b83ae7/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_bootstrapping-spi.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_bootstrapping-spi.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_bootstrapping-spi.adoc
index d0f0499..ffe748d 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_bootstrapping-spi.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_bootstrapping-spi.adoc
@@ -20,7 +20,7 @@ The table below summarizes the bootstrapping SPI defined by Apache Isis. It als
|Notes
-|xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_ClassDiscoveryService[`o.a.i.applib.` +
+|xref:../rgsvc/rgsvc.adoc#_rgsvc_bootstrapping-spi_ClassDiscoveryService[`o.a.i.applib.` +
`services.classdiscovery` +
`ClassDiscoveryService`]
|Mechanism to locate (from the classpath) classes with a specific annotation (eg xref:../rgant/rgant.adoc#_rgant-DomainService[`@DomainService`])
@@ -44,4 +44,4 @@ Key:
-include::_rgsvc_spi_ClassDiscoveryService.adoc[leveloffset=+1]
+include::_rgsvc_bootstrapping-spi_ClassDiscoveryService.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/20b83ae7/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_bootstrapping-spi_ClassDiscoveryService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_bootstrapping-spi_ClassDiscoveryService.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_bootstrapping-spi_ClassDiscoveryService.adoc
new file mode 100644
index 0000000..24ad22c
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_bootstrapping-spi_ClassDiscoveryService.adoc
@@ -0,0 +1,82 @@
+[[_rgsvc_bootstrapping-spi_ClassDiscoveryService]]
+= `ClassDiscoveryService`
+: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 `ClassDiscovery` service is used to automatically discover subclasses of any given type on the classpath. The primary use case is to support "convention-over-configuration" designs that work with a minimum of configuration.
+
+This service is used by the xref:../rgcms/rgcms.adoc#_rgcms_classes_super_FixtureScripts[`FixtureScripts`] service to automatically locate any xref:../rgcms/rgcms.adoc#_rgcms_classes_super_FixtureScript[`FixtureScript`] implementations.
+
+
+
+== SPI
+
+The SPI defined by the service is:
+
+[source,java]
+----
+public interface ClassDiscoveryService2 {
+ @Programmatic
+ <T> Set<Class<? extends T>> findSubTypesOfClasses(Class<T> type, String packagePrefix);
+ @Deprecated
+ @Programmatic
+ <T> Set<Class<? extends T>> findSubTypesOfClasses(Class<T> type); // <1>
+}
+----
+<1> no longer used
+
+
+
+== Implementation
+
+Isis provides an implementation of this service, namely `o.a.i.applib.services.classdiscovery.ClassDiscoveryServiceUsingReflections`.
+
+[NOTE]
+====
+This implementation is also used to discover domain services annotated with xref:../rgant/rgant.adoc#_rgant-DomainService[`@DomainService`]. Currently this logic uses the implementation directly, so is not pluggable. However, the entire `ServicesInstaller`
+====
+
+
+
+== Usage
+
+The usage will vary depending upon the conventions of the design. As of 1.9.0, the usage of the service has been
+centralized such that the packages to be scanned are located from the xref:../rgcms/rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[`AppManifest`]'s `#getModules()` method.
+
+For example, the xref:../ugfun/ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype]'s app manifest includes:
+
+[source,java]
+----
+public class DomainAppAppManifest implements AppManifest {
+ @Override
+ public List<Class<?>> getModules() {
+ return Arrays.asList(
+ DomainAppDomainModule.class, // domain (entities and repositories)
+ DomainAppFixtureModule.class, // fixtures
+ DomainAppAppModule.class // home page service etc
+ );
+ }
+ ...
+}
+----
+
+where the three module classes in effect define three different package prefixes to search under (for domain services, fixture scripts and persistent entities).
+
+Other usages of the `ClassDiscoveryService` are likely to work in a similar way, requiring some sort of scope to be specified.
+
+
+== Registering the Services
+
+Assuming that the `configuration-and-annotation` services installer is configured (implicit if using the
+`AppManifest` to xref:../rgcms/rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' core
+implementation of `ClassDiscoveryService2` service is automatically registered and injected (it is annotated with
+`@DomainService`) so no further configuration is required.
+
+To use an alternative implementation, use
+xref:../rgant/rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
+in the xref:../rgsvc/rgsvc.adoc#__rgsvc_intro_overriding-the-services[introduction] to this guide).
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/20b83ae7/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_core-domain-api.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_core-domain-api.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_core-domain-api.adoc
index f06ba8b..b353cf2 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_core-domain-api.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_core-domain-api.adoc
@@ -22,7 +22,7 @@ The table below summarizes the core/domain APIs defined by Apache Isis. It also
-|xref:../rgsvc/rgsvc.adoc#_rgsvc_api_ClockService[`o.a.i.applib.` +
+|xref:../rgsvc/rgsvc.adoc#_rgsvc_core-domain-api_ClockService[`o.a.i.applib.` +
`services.clock` +
`ClockService`]
|Access the current time (and for testing, allow the time to be changed)
@@ -33,7 +33,7 @@ The table below summarizes the core/domain APIs defined by Apache Isis. It also
-|xref:../rgsvc/rgsvc.adoc#_rgsvc_api_ConfigurationService[`o.a.i.applib.` +
+|xref:../rgsvc/rgsvc.adoc#_rgsvc_core-domain-api_ConfigurationService[`o.a.i.applib.` +
`services.config` +
`ConfigurationService`]
|Access configuration properties (eg from `isis.properties` file)
@@ -43,10 +43,10 @@ The table below summarizes the core/domain APIs defined by Apache Isis. It also
``isis-core-runtime``
|The ``ConfigurationServiceMenu`` exposes the ``allConfigurationProperties`` action in the user interface. +
+
-Supercedes methods in xref:../rgsvc/rgsvc.adoc#_rgsvc_api_DomainObjectContainer[`DomainObjectContainer`].
+Supercedes methods in xref:../rgsvc/rgsvc.adoc#_rgsvc_core-domain-api_DomainObjectContainer[`DomainObjectContainer`].
-|xref:../rgsvc/rgsvc.adoc#_rgsvc_api_DomainObjectContainer[`o.a.i.applib` +
+|xref:../rgsvc/rgsvc.adoc#_rgsvc_core-domain-api_DomainObjectContainer[`o.a.i.applib` +
`DomainObjectContainer`]
|Miscellaneous functions, eg obtain title of object.
|`DomainObjectContainer-` +
@@ -56,7 +56,7 @@ Supercedes methods in xref:../rgsvc/rgsvc.adoc#_rgsvc_api_DomainObjectContainer[
|
-|xref:../rgsvc/rgsvc.adoc#_rgsvc_api_EventBusService[`o.a.i.applib.` +
+|xref:../rgsvc/rgsvc.adoc#_rgsvc_core-domain-api_EventBusService[`o.a.i.applib.` +
`services.eventbus` +
`EventBusService`]
|Programmatically post events to the internal event bus. Also used by Apache Isis itself to broadcast domain events:
@@ -69,7 +69,7 @@ Supercedes methods in xref:../rgsvc/rgsvc.adoc#_rgsvc_api_DomainObjectContainer[
``isis-core-runtime``
|
-|xref:../rgsvc/rgsvc.adoc#_rgsvc_api_FactoryService[`o.a.i.applib.` +
+|xref:../rgsvc/rgsvc.adoc#_rgsvc_core-domain-api_FactoryService[`o.a.i.applib.` +
`services.factory` +
`FactoryService`]
|Methods to instantiate and initialize domain objects
@@ -77,12 +77,12 @@ Supercedes methods in xref:../rgsvc/rgsvc.adoc#_rgsvc_api_DomainObjectContainer[
``Default`` +
``o.a.i.core`` +
``isis-core-metamodel``
-|Supercedes methods in xref:../rgsvc/rgsvc.adoc#_rgsvc_api_DomainObjectContainer[`DomainObjectContainer`].
+|Supercedes methods in xref:../rgsvc/rgsvc.adoc#_rgsvc_core-domain-api_DomainObjectContainer[`DomainObjectContainer`].
-|xref:../rgsvc/rgsvc.adoc#_rgsvc_api_Scratchpad[`o.a.i.applib.` +
+|xref:../rgsvc/rgsvc.adoc#_rgsvc_core-domain-api_Scratchpad[`o.a.i.applib.` +
`services.scratchpad` +
`Scratchpad`]
|Request-scoped service for interchanging information between and aggregating over multiple method calls; in particular for use by "bulk" actions (invoking of an action for all elements of a collection)
@@ -94,7 +94,7 @@ Supercedes methods in xref:../rgsvc/rgsvc.adoc#_rgsvc_api_DomainObjectContainer[
-|xref:../rgsvc/rgsvc.adoc#_rgsvc_api_UserService[`o.a.i.applib.` +
+|xref:../rgsvc/rgsvc.adoc#_rgsvc_core-domain-api_UserService[`o.a.i.applib.` +
`services.xactn` +
`UserService`]
|Methods to access the currently-logged on user.
@@ -102,7 +102,7 @@ Supercedes methods in xref:../rgsvc/rgsvc.adoc#_rgsvc_api_DomainObjectContainer[
``Default`` +
``o.a.i.core`` +
``isis-core-metamodel``
-|Supercedes methods in xref:../rgsvc/rgsvc.adoc#_rgsvc_api_DomainObjectContainer[`DomainObjectContainer`].
+|Supercedes methods in xref:../rgsvc/rgsvc.adoc#_rgsvc_core-domain-api_DomainObjectContainer[`DomainObjectContainer`].
@@ -135,7 +135,7 @@ There is also a number of deprecated domain services.
|`Bulk.InteractionContext` +
``o.a.i.core`` +
``isis-core-applib``
-|Replaced by xref:../rgsvc/rgsvc.adoc#_rgsvc_api_ActionInvocationContext[`ActionInvocationContext`]
+|Replaced by xref:../rgsvc/rgsvc.adoc#_rgsvc_application-layer-api_ActionInvocationContext[`ActionInvocationContext`]
@@ -153,10 +153,10 @@ Key:
-include::_rgsvc_api_ClockService.adoc[leveloffset=+1]
-include::_rgsvc_api_ConfigurationService.adoc[leveloffset=+1]
-include::_rgsvc_api_DomainObjectContainer.adoc[leveloffset=+1]
-include::_rgsvc_api_EventBusService.adoc[leveloffset=+1]
-include::_rgsvc_api_FactoryService.adoc[leveloffset=+1]
-include::_rgsvc_api_Scratchpad.adoc[leveloffset=+1]
-include::_rgsvc_api_UserService.adoc[leveloffset=+1]
+include::_rgsvc_core-domain-api_ClockService.adoc[leveloffset=+1]
+include::_rgsvc_core-domain-api_ConfigurationService.adoc[leveloffset=+1]
+include::_rgsvc_core-domain-api_DomainObjectContainer.adoc[leveloffset=+1]
+include::_rgsvc_core-domain-api_EventBusService.adoc[leveloffset=+1]
+include::_rgsvc_core-domain-api_FactoryService.adoc[leveloffset=+1]
+include::_rgsvc_core-domain-api_Scratchpad.adoc[leveloffset=+1]
+include::_rgsvc_core-domain-api_UserService.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/20b83ae7/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_core-domain-api_ClockService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_core-domain-api_ClockService.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_core-domain-api_ClockService.adoc
new file mode 100644
index 0000000..3213a26
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_core-domain-api_ClockService.adoc
@@ -0,0 +1,101 @@
+[[_rgsvc_core-domain-api_ClockService]]
+= `ClockService`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../../
+:_imagesdir: images/
+
+
+
+
+Most applications deal with dates and times in one way or another. For example, if an `Order` is placed, then the `Customer` may have 30 days to pay the `Invoice`, otherwise a penalty may be levied.
+
+However, such date/time related functionality can quickly complicate automated testing: "today+30" will be a different value every time the test is run.
+
+Even disregarding testing, there may be a requirement to ensure that date/times are obtained from an NNTP server (rather than the system PC). While instantiating a `java.util.Date` to current the current time is painless enough, we would not want complex technical logic for querying an NNTP server spread around domain logic code.
+
+Therefore it's common to provide a domain service whose responsibility is to provide the current time. This service can be injected into any domain object (and can be mocked out for unit testing). Apache Isis provides such a facade through the `ClockService`.
+
+
+
+== API & Implementation
+
+The API defined by `ClockService` is:
+
+[source,java]
+----
+@DomainService(nature = NatureOfService.DOMAIN)
+public class ClockService {
+ @Programmatic
+ public LocalDate now() { ... }
+ @Programmatic
+ public LocalDateTime nowAsLocalDateTime() { ... }
+ @Programmatic
+ public DateTime nowAsDateTime() { ... }
+ @Programmatic
+ public Timestamp nowAsJavaSqlTimestamp() { ... }
+ @Programmatic
+ public long nowAsMillis() { ... }
+}
+----
+
+This class (`o.a.i.applib.services.clock.ClockService`) is also the default implementation. The time provided by this default implementation is based on the system clock.
+
+
+
+
+== Testing Support
+
+The default `ClockService` implementation in fact simply delegates to another class defined in the API, namely the `o.a.i.applib.clock.Clock`, an abstract singleton class. It is not recommended that your code use the `Clock` directly, but you should understand how this all works:
+
+* there are two subclasses implementations `Clock`, namely `SystemClock` and `FixtureClock`.
+* the first implementation that is instantiated registers itself as the singleton.
+* if running in xref:../rgcfg/rgcfg.adoc#_rgcfg_deployment-types[production] (server) mode, then (unless another implementation has beaten it to the punch) the framework will instantiate the ``SystemClock`. Once instantiated this cannot be replaced.
+* if running in xref:../rgcfg/rgcfg.adoc#_rgcfg_deployment-types[prototype] mode, then the framework will instead instantiate `FixtureClock`. This _can_ be replaced if required.
+
+The `FixtureClock` will behave as the system clock, unless its is explicitly set using `FixtureClock#setDate(...)` or `FixtureClock#setTime(...)` and so forth.
+
+
+
+=== Alternative Implementations
+
+Suppose you want (as discussed in the introduction to this service) to use a clock that delegates to NNTP. For most domain services this would amount to implementing the appropriate service and registering in `isis.properties` so that it is used in preference to any implementations provided by default by the framework.
+
+In the case of the `ClockService`, though, this approach (unfortunately) will not work, because parts of Apache Isis (still) delegate to the `Clock` singleton rather than using the `ClockService` domain service.
+
+The workaround, therefore, is to implement your functionality as a subclass of `Clock`. You can write a domain service that will ensure that your implementation is used ahead of any implementations provided by the framework.
+
+For example:
+
+[source,java]
+----
+@DomainService(nature=NatureOfService.DOMAIN)
+public class NntpClockServiceInitializer {
+ @Programmatic
+ @PostConstruct
+ public void postConstruct(Map<String,String> properties) {
+ new NntpClock(properties); // <1>
+ }
+ private static class NntpClock extends Clock {
+ NntpClock(Map<String,String> properties) { ... } // <2>
+ protected long time() { ... } // <3>
+ ... NNTP stuff here ...
+ }
+ }
+}
+----
+<1> enough to simply instantiate the `Clock`; it will register itself as singleton
+<2> connect to NNTP service using configuration properties from `isis.properties`
+<3> call to NNTP service here
+
+
+
+
+== Registering the Service
+
+Assuming that the `configuration-and-annotation` services installer is configured (implicit if using the
+`AppManifest` to xref:../rgcms/rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' core
+implementation of `ClockService` is automatically registered (it is annotated with `@DomainService`) so no further
+configuration is required.
+
+If you want to use a different implementation of `Clock`, eg delegating to NNTP, then do _not_ register directly, but
+instead subclass from `o.a.i.applib.clock.Clock` singleton (as described in the section above).
http://git-wip-us.apache.org/repos/asf/isis/blob/20b83ae7/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_core-domain-api_ConfigurationService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_core-domain-api_ConfigurationService.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_core-domain-api_ConfigurationService.adoc
new file mode 100644
index 0000000..e69062b
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_core-domain-api_ConfigurationService.adoc
@@ -0,0 +1,94 @@
+[[_rgsvc_core-domain-api_ConfigurationService]]
+= `ConfigurationService`
+: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 `ConfigurationService` allows domain objects to read the configuration properties aggregated from the various xref:../rgcfg/rgcfg.adoc#_rgcfg_configuration-files[configuration files].
+
+
+[IMPORTANT]
+====
+Only configuration properties with the prefix "application" are be exposed.
+====
+
+[NOTE]
+====
+The methods in this service replace similar methods (now deprecated) in xref:../rgsvc/rgsvc.adoc#_rgsvc_core-domain-api_DomainObjectContainer[`DomainObjectContainer`].
+====
+
+
+== API and Usage
+
+The API of `ConfigurationService` is:
+
+[source,java]
+----
+public interface ConfigurationService {
+
+ String getProperty(String name); // <1>
+ String getProperty(String name, String defaultValue); // <2>
+ List<String> getPropertyNames(); // <3>
+ Set<ConfigurationProperty> allProperties(); // <4>
+
+}
+----
+<1> Return the configuration property with the specified name; else return null.
+<2> Return the configuration property with the specified name; if it doesn't exist then return the specified default value.
+<3> Return the names of all the available properties.
+<4> Returns all properties, each as an instance of the `ConfigurationProperty` view model.
+
+For example, here's a fictitious service that might wrap link:http://twitter4j.org/en/configuration.html[Twitter4J]. say:
+
+[source,java]
+----
+@DomainService(nature=NatureOfService.DOMAIN)
+public class TweetService {
+ @Programmatic
+ @PostConstruct
+ public void init() {
+ this.oauthConsumerKey = configurationService.getProperty("application.tweetservice.oauth.consumerKey");
+ this.oauthConsumerSecret = configurationService.getProperty("application.tweetservice.oauth.consumerSecret");
+ this.oauthAccessToken = configurationService.getProperty("application.tweetservice.oauth.accessToken");
+ this.oauthAccessTokenSecret = configurationService.getProperty("application.tweetservice.oauth.accessTokenSecret");
+ }
+ ...
+ @Inject
+ ConfigurationService configurationService;
+}
+----
+
+[TIP]
+====
+If you _do_ have a domain service that needs to access Isis properties, then an alternative is to define a xref:../rgant/rgant.adoc#_rgant-PostConstruct[`@PostConstruct`] method and pass in a `Map<String,String>` of properties.
+This is provided all properties, not just those with the 'application' prefix.
+====
+
+
+
+
+
+== Implementation
+
+The core framework provides a default implementation of this service (`o.a.i.core.runtime.services.config.ConfigurationServiceDefault`).
+
+
+
+
+== Registering the Service
+
+Assuming that the `configuration-and-annotation` services installer is configured (implicit if using the
+`AppManifest` to xref:../rgcms/rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' core
+implementation of `ConfigurationService` service is automatically registered and injected (it is annotated with
+`@DomainService`) so no further configuration is required.
+
+To use an alternative implementation, use
+xref:../rgant/rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
+in the xref:../rgsvc/rgsvc.adoc#__rgsvc_intro_overriding-the-services[introduction] to this guide).
+
+
+
+== Related services
+
+The ``ConfigurationServiceMenu`` exposes the ``allConfigurationProperties`` action in the user interface.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/20b83ae7/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_core-domain-api_DomainObjectContainer.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_core-domain-api_DomainObjectContainer.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_core-domain-api_DomainObjectContainer.adoc
new file mode 100644
index 0000000..e044413
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_core-domain-api_DomainObjectContainer.adoc
@@ -0,0 +1,51 @@
+[[_rgsvc_core-domain-api_DomainObjectContainer]]
+= `DomainObjectContainer`
+: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 `DomainObjectContainer` service provides a set of general purpose functionality for domain objects to call. Principal amongst these are a generic APIs for querying objects and creating and persisting objects. In addition, the service provides access to security context (the "current user"), allows information and warning messages to be raised, and various other miscellaneous functions.
+
+
+[NOTE]
+====
+(Almost all of) the methods in this service have been moved out into a number of more fine-grained services: xref:../rgsvc/rgsvc.adoc#_rgsvc_persistence-layer-api_RepositoryService[`RepositoryService`], xref:../rgsvc/rgsvc.adoc#_rgsvc_application-layer-api_MessageService[`MessageService`], xref:../rgsvc/rgsvc.adoc#_rgsvc_core-domain-api_FactoryService[`FactoryService`], xref:../rgsvc/rgsvc.adoc#_rgsvc_application-layer-api_TitleService[`TitleService`], xref:../rgsvc/rgsvc.adoc#_rgsvc_core-domain-api_ConfigurationService[`ConfigurationService`], xref:../rgsvc/rgsvc.adoc#_rgsvc_core-domain-api_UserService[`UserService`] and xref:../rgsvc/rgsvc.adoc#_rgsvc_metadata-api_ServiceRegistry[`ServiceRegistry`].
+====
+
+
+
+
+== APIs
+
+The sections below discuss the functions provided by the service, broken out into categories.
+
+
+include::_rgsvc_core-domain-api_DomainObjectContainer_object-creation-api.adoc[leveloffset=+2]
+include::_rgsvc_core-domain-api_DomainObjectContainer_generic-repository-api.adoc[leveloffset=+2]
+include::_rgsvc_core-domain-api_DomainObjectContainer_object-persistence-api.adoc[leveloffset=+2]
+include::_rgsvc_core-domain-api_DomainObjectContainer_messages-api.adoc[leveloffset=+2]
+include::_rgsvc_core-domain-api_DomainObjectContainer_security-api.adoc[leveloffset=+2]
+include::_rgsvc_core-domain-api_DomainObjectContainer_presentation-api.adoc[leveloffset=+2]
+include::_rgsvc_core-domain-api_DomainObjectContainer_properties-api.adoc[leveloffset=+2]
+include::_rgsvc_core-domain-api_DomainObjectContainer_services-api.adoc[leveloffset=+2]
+include::_rgsvc_core-domain-api_DomainObjectContainer_validation-api.adoc[leveloffset=+2]
+
+
+
+
+== Implementation
+
+The core framework provides a default implementation of this service (`o.a.i.core.metamodel.services.container.DomainObjectContainerDefault`).
+
+
+
+== Registering the Service
+
+Assuming that the `configuration-and-annotation` services installer is configured (implicit if using the
+`AppManifest` to xref:../rgcms/rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' core
+implementation of `DomainObjectContainer` service is automatically registered and injected (it is annotated with
+`@DomainService`) so no further configuration is required.
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/20b83ae7/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_core-domain-api_DomainObjectContainer_generic-repository-api.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_core-domain-api_DomainObjectContainer_generic-repository-api.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_core-domain-api_DomainObjectContainer_generic-repository-api.adoc
new file mode 100644
index 0000000..bb922ec
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_core-domain-api_DomainObjectContainer_generic-repository-api.adoc
@@ -0,0 +1,84 @@
+[[_rgsvc_core-domain-api_DomainObjectContainer_generic-repository-api]]
+= Generic Repository API
+: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 repository API acts as an abstraction over the JDO/DataNucleus objectstore. You can use it during prototyping to write naive queries (find all rows, then filter using the Guava `Predicate` API, or you can use it to call JDO link:http://www.datanucleus.org/products/accessplatform_4_0/jdo/query.html#named[named queries] using JDOQL.
+
+As an alternative, you could also use link:http://www.datanucleus.org/products/accessplatform_4_0/jdo/jdoql_typesafe.html[JDO typesafe queries] through the xref:../rgsvc/rgsvc.adoc#_rgsvc_persistence-layer-api_IsisJdoSupport[`IsisJdoSupport`] service.
+
+
+[source,java]
+----
+public interface DomainObjectContainer {
+ public <T> List<T> allInstances(Class<T> ofType, long... range); // <1>
+ <T> List<T> allMatches(Query<T> query); // <2>
+ <T> List<T> allMatches(Class<T> ofType, Predicate<? super T> predicate, long... range); // <3>
+ <T> List<T> allMatches(Class<T> ofType, String title, long... range); // <4>
+ <T> List<T> allMatches(Class<T> ofType, T pattern, long... range); // <5>
+ ...
+}
+----
+<1> all persisted instances of specified type. Mostly for prototyping, though can be useful to obtain all instances of domain entities if the number is known to be small. The optional varargs parameters are for paging control; more on this below.
+<2> all persistence instances matching the specified `Query`. Query itself is an Isis abstraction on top of JDO/DataNucleus' Query API. *This is the primary API used for querying*
+<3> all persistenced instances of specified type matching `Predicate`. Only really intended for prototyping because in effect constitutes a client-side WHERE clause
+<4> all persisted instances with the specified string as their title. Only very occasionally used
+<5> all persisted instances matching object (query-by-example). Only very occasionally used
+
+There are various implementations of the `Query` API, but these either duplicate functionality of the other overloads of `allMatches(...)` or they are not supported by the JDO/DataNucleus object store. The only significant implementation of `Query` to be aware of is `QueryDefault`, which identifies a named query and a set of parameter/argument tuples.
+
+For example, in the (non-ASF) http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp] the `ToDoItem` is annotated:
+
+[source,java]
+----
+@javax.jdo.annotations.Queries( {
+ @javax.jdo.annotations.Query(
+ name = "findByAtPathAndComplete", language = "JDOQL", // <1>
+ value = "SELECT "
+ + "FROM todoapp.dom.module.todoitem.ToDoItem "
+ + "WHERE atPath.indexOf(:atPath) == 0 " // <2>
+ + " && complete == :complete"), // <3>
+ ...
+})
+public class ToDoItem ... {
+ ...
+}
+----
+<1> name of the query
+<2> defines the `atPath` parameter
+<3> defines the `complete` parameter
+
+This JDO query definitions are used in the `ToDoItemRepositoryImplUsingJdoql` service:
+
+[source,java]
+----
+@DomainService(nature = NatureOfService.DOMAIN)
+public class ToDoItemRepositoryImplUsingJdoql implements ToDoItemRepositoryImpl {
+ @Programmatic
+ public List<ToDoItem> findByAtPathAndCategory(final String atPath, final Category category) {
+ return container.allMatches(
+ new QueryDefault<>(ToDoItem.class,
+ "findByAtPathAndCategory", // <1>
+ "atPath", atPath, // <2>
+ "category", category)); // <3>
+ }
+ ...
+ @javax.inject.Inject
+ DomainObjectContainer container;
+}
+----
+<1> corresponds to the "findByAtPathAndCategory" JDO named query
+<2> provide argument for the `atPath` parameter. The pattern is parameter, argument, parameter, argument, ... and so on.
+<3> provide argument for the `category` parameter. The pattern is parameter, argument, parameter, argument, ... and so on.
+
+Other JDOQL named queries (not shown) follow the exact same pattern.
+
+With respect to the other query APIs, the varargs parameters are optional, but allow for (client-side and managed) paging. The first parameter is the `start` (0-based, the second is the `count`.
+
+[TIP]
+====
+It is also possible to query using DataNucleus' type-safe query API. For more details, see xref:../rgsvc/rgsvc.adoc#_rgsvc_persistence-layer-api_IsisJdoSupport[`IsisJdoSupport`].
+====
http://git-wip-us.apache.org/repos/asf/isis/blob/20b83ae7/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_core-domain-api_DomainObjectContainer_messages-api.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_core-domain-api_DomainObjectContainer_messages-api.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_core-domain-api_DomainObjectContainer_messages-api.adoc
new file mode 100644
index 0000000..e93885b
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_core-domain-api_DomainObjectContainer_messages-api.adoc
@@ -0,0 +1,45 @@
+[[_rgsvc_core-domain-api_DomainObjectContainer_messages-api]]
+= Messages API
+: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 `DomainObjectContainer` allows domain objects to raise information, warning or error messages. These messages can either be simple strings, or can be translated.
+
+[source,java]
+----
+public interface DomainObjectContainer {
+
+ void informUser(String message); // <1>
+ String informUser(TranslatableString message, Class<?> contextClass, String contextMethod); // <2>
+
+ void warnUser(String message); // <3>
+ String warnUser(TranslatableString message, Class<?> contextClass, String contextMethod); // <4>
+
+ void raiseError(String message); // <5>
+ String raiseError(TranslatableString message, Class<?> contextClass, String contextMethod); // <6>
+ ...
+}
+----
+<1> display as a transient message to the user (not requiring acknowledgement). In the xref:../ugvw/ugvw.adoc#[Wicket viewer] this is implemented as a toast that automatically disappears after a period of time.
+<2> ditto, but with translatable string, for xref:../ugbtb/ugbtb.adoc#_ugbtb_i18n[i18n support].
+<3> warn the user about a situation with the specified message. In the xref:../ugvw/ugvw.adoc#[Wicket viewer] this is implemented as a toast that must be closed by the end-user.
+<4> ditto, but with translatable string, for i18n support.
+<5> show the user an unexpected application error. In the xref:../ugvw/ugvw.adoc#[Wicket viewer] this is implemented as a toast (with a different colour) that must be closed by the end-user.
+<6> ditto, but with translatable string, for i18n support.
+
+
+For example:
+
+[source,java]
+----
+public Order addItem(Product product, @ParameterLayout(named="Quantity") int quantity) {
+ if(productRepository.stockLevel(product) == 0) {
+ container.warnUser(
+ product.getDescription() + " out of stock; order fulfillment may be delayed");
+ }
+ ...
+}
+----
http://git-wip-us.apache.org/repos/asf/isis/blob/20b83ae7/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_core-domain-api_DomainObjectContainer_object-creation-api.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_core-domain-api_DomainObjectContainer_object-creation-api.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_core-domain-api_DomainObjectContainer_object-creation-api.adoc
new file mode 100644
index 0000000..bd9d6fa
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_core-domain-api_DomainObjectContainer_object-creation-api.adoc
@@ -0,0 +1,47 @@
+[[_rgsvc_core-domain-api_DomainObjectContainer_object-creation-api]]
+= Object Creation API
+: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 object creation APIs are used to instantiate new domain objects or view models.
+
+[source,java]
+----
+public interface DomainObjectContainer {
+
+ <T> T newTransientInstance(final Class<T> ofType); // <1>
+ <T> T newViewModelInstance(final Class<T> ofType, final String memento); // <2>
+ <T> T mixin(); // <3>
+ ...
+}
+----
+<1> create a new non-persisted domain entity. Any services will be automatically injected into the service.
+<2> create a new view model, with the specified memento (as per xref:../rgcms/rgcms.adoc#_rgcms_classes_super_AbstractViewModel[ViewModel#viewModelMemento()]. In general it is easier to just annotate with xref:../rgant/rgant.adoc#_rgant-ViewModel[`@ViewModel`] and let Apache Isis manage the memento automatically.
+<3> programmatically instantiate a mixin, as annotated with
+xref:../rgant/rgant.adoc#_rgant-Mixin[`@Mixin`] or xref:../rgant/rgant.adoc#_rgant-DomainObject_nature[`@DomainObject#nature()`].
+
+For example:
+
+[source,java]
+----
+Customer cust = container.newTransientInstance(Customer.class);
+cust.setFirstName("Freddie");
+cust.setLastName("Mercury");
+container.persist(cust);
+----
+
+As an alternative to using `newTransientInstance(...)` or `mixin(...)`, you could also simply `new()` up the object.
+Doing this will not inject any domain services, but they can be injected manually using xref:rg .adoc#_rgsvc_core-domain-api_DomainObjectContainer_services-api[#injectServicesInto(...)`].
+
+[NOTE]
+====
+Calling `new(...)` also this circumvents Apache Isis' xref:../rgcms/rgcms.adoc#_rgcms_methods_reserved_created[`created()`]
+callback, and in addition any default values for properties (either explicitly set by
+xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_default[`default...()`] or defaulted implicitly according to Apache Isis'
+own conventions) will not be called either. If you don't intend to use these features, though, the net effect is code
+that has less coupling to Isis and is arguably easier to understand (has "less magic" happening).
+====
+
http://git-wip-us.apache.org/repos/asf/isis/blob/20b83ae7/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_core-domain-api_DomainObjectContainer_object-persistence-api.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_core-domain-api_DomainObjectContainer_object-persistence-api.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_core-domain-api_DomainObjectContainer_object-persistence-api.adoc
new file mode 100644
index 0000000..8322673
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_core-domain-api_DomainObjectContainer_object-persistence-api.adoc
@@ -0,0 +1,56 @@
+[[_rgsvc_core-domain-api_DomainObjectContainer_object-persistence-api]]
+= Object Persistence API
+: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 persistence API is used to persist newly created objects (as per xref:../rgsvc/rgsvc.adoc#_rgsvc_core-domain-api_DomainObjectContainer_object-creation-api[`#newTransientInstance(...)`], above and to delete (remove) objects that are persistent.
+
+Note that there is no API for updating existing objects; the framework (or rather, JDO/DataNucleus) performs object dirty tracking and so any objects that are modified in the course of a request will be automatically updated).
+
+
+
+[source,java]
+----
+public interface DomainObjectContainer {
+
+ boolean isPersistent(Object domainObject); // <1>
+ boolean isViewModel(Object domainObject); // <2>
+
+ void persist(Object domainObject); // <3>
+ void persistIfNotAlready(Object domainObject); // <4>
+
+ void remove(Object persistentDomainObject); // <5>
+ void removeIfNotAlready(Object domainObject); // <6>
+
+ boolean flush(); // <7>
+ ...
+}
+----
+<1> test whether a particular domain object is persistent or not.
+<2> test whether a particular domain object is a view model or not. Note that this includes any domain objects annotated with xref:../rgant/rgant.adoc#_rgant-DomainObject_nature[`@DomainObject#nature=Nature.EXTERNAL_ENTITY)`] or xref:../rgant/rgant.adoc#_rgant-DomainObject_nature[`@DomainObject#nature=Nature.INMEMORY_ENTITY`]
+<3> persist a transient object. Note though that this will throw an exception if the object is already persistent; this can happen if JDO/DataNucleus's link:http://www.datanucleus.org/products/accessplatform_4_0/jdo/orm/cascading.html[persistence-by-reachability] is in effect. For this reason it is generally better to use `persistIfNotAlready(...)`. Also note that `persist(...)` has been deprecate. When moving to xref:rgsvc_api_RepositoryService.adoc#_rgsvc_persistence-layer-api_RepositoryService[`RepositoryService#persist()`] take into account that its behavior is identical to <4>, being a no-op if the object is persistent, instead of throwing an exception.
+<4> persist an object but only if know to not have been persistent. But if the object is persistent, is a no-op
+<5> remove (ie DELETE) a persistent object. For similar reasons to the persistence, it is generally better to use:
+<6> remove (ie DELETE) an object only if known to be persistent. But if the object has already been deleted, then is a no-op.
+<7> flushes all pending changes to the objectstore. Explained further below.
+
+For example:
+
+[source,java]
+----
+Customer cust = container.newTransientInstance(Customer.class);
+cust.setFirstName("Freddie");
+cust.setLastName("Mercury");
+container.persistIfNotAlready(cust);
+----
+
+You should be aware that by default Apache Isis queues up calls to `#persist()` and `#remove()`. These are then executed either when the request completes (and the transaction commits), or if the queue is flushed. This can be done either implicitly by the framework, or as the result of a direct call to `#flush()`.
+
+By default the framework itself will cause `#flush()` to be called whenever a query is executed by way of `#allMatches(Query)`, as documented xref:../rgsvc/rgsvc.adoc#_rgsvc_core-domain-api_DomainObjectContainer_generic-repository-api[above]. However, this behaviour can be disabled using the xref:../rgcfg/rgcfg.adoc#_rgcfg_configuring-core[configuration property] `isis.services.container.disableAutoFlush`.
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/20b83ae7/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_core-domain-api_DomainObjectContainer_presentation-api.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_core-domain-api_DomainObjectContainer_presentation-api.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_core-domain-api_DomainObjectContainer_presentation-api.adoc
new file mode 100644
index 0000000..37da64f
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_core-domain-api_DomainObjectContainer_presentation-api.adoc
@@ -0,0 +1,47 @@
+[[_rgsvc_core-domain-api_DomainObjectContainer_presentation-api]]
+= Presentation API
+: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/
+
+
+
+
+A responsibility of every domain object is to return a title. This can be done declaratively using the xref:../rgant/rgant.adoc#_rgant-Title[`@Title`] annotation on property/ies, or it can be done imperatively by writing a xref:../rgcms/rgcms.adoc#_rgcms_methods_reserved_title[`title()`] method.
+
+It's quite common for titles to be built up of the titles of other objects. If using building up the title using `@Title` then Apache Isis will automatically use the title of the objects referenced by the annotated properties. We also need programmatic access to these titles if going the imperative route.
+
+Similarly, it often makes sense if xref:../rgsvc/rgsvc.adoc#_rgsvc_core-domain-api_DomainObjectContainer_messages-api[raising messages] to use the title of an object in a message rather (than a some other property of the object), because this is how end-users will be used to identifying the object.
+
+The API defined by `DomainObjectContainer` is simply:
+
+[source,java]
+----
+public interface DomainObjectContainer {
+ String titleOf(Object domainObject); // <1>
+ String iconNameOf(Object domainObject); // <2>
+ ...
+}
+----
+<1> return the title of the object, as rendered in the UI by the Apache Isis viewers.
+<2> return the icon name of the object, as rendered in the UI by the Apache Isis viewers.
+
+
+By way of example, here's some code from the (non-ASF) http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp] showing the use of the API in an message:
+
+[source,java]
+----
+ public List<ToDoItem> delete() {
+ final String title = container.titleOf(this); // <1>
+ ...
+ container.removeIfNotAlready(this);
+ container.informUser(
+ TranslatableString.tr(
+ "Deleted {title}", "title", title), // <2>
+ this.getClass(), "delete");
+ ...
+ }
+
+----
+<1> the title is obtained first, because we're not allowed to reference object after it's been deleted
+<2> use the title in an i18n `TranslatableString`
http://git-wip-us.apache.org/repos/asf/isis/blob/20b83ae7/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_core-domain-api_DomainObjectContainer_properties-api.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_core-domain-api_DomainObjectContainer_properties-api.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_core-domain-api_DomainObjectContainer_properties-api.adoc
new file mode 100644
index 0000000..1d3cb3c
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_core-domain-api_DomainObjectContainer_properties-api.adoc
@@ -0,0 +1,50 @@
+[[_rgsvc_core-domain-api_DomainObjectContainer_properties-api]]
+: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/
+
+
+
+
+= Properties API
+
+The properties API allows domain objects to read the configuration properties aggregated from the various xref:../rgcfg/rgcfg.adoc#_rgcfg_configuration-files[configuration files].
+
+[source,java]
+----
+public interface DomainObjectContainer {
+ String getProperty(String name); // <1>
+ String getProperty(String name, String defaultValue); // <2>
+ List<String> getPropertyNames(); // <3>
+}
+----
+<1> Return the configuration property with the specified name; else return null.
+<2> Return the configuration property with the specified name; if it doesn't exist then return the specified default value.
+<3> Return the names of all the available properties.
+
+For example, here's a fictitious service that might wrap link:http://twitter4j.org/en/configuration.html[Twitter4J]. say:
+
+[source,java]
+----
+@DomainService(nature=NatureOfService.DOMAIN)
+public class TweetService {
+ @Programmatic
+ @PostConstruct
+ public void init() {
+ this.oauthConsumerKey = container.getProperty("tweetservice.oauth.consumerKey");
+ this.oauthConsumerSecret = container.getProperty("tweetservice.oauth.consumerSecret");
+ this.oauthAccessToken = container.getProperty("tweetservice.oauth.accessToken");
+ this.oauthAccessTokenSecret = container.getProperty("tweetservice.oauth.accessTokenSecret");
+ }
+ ...
+ @Inject
+ DomainObjectContainer container;
+}
+----
+
+[TIP]
+====
+If you _do_ have a domain service that needs to access properties, then note that an alternative is to define a xref:../rgant/rgant.adoc#_rgant-PostConstruct[`@PostConstruct`] method and pass in a `Map<String,String>` of properties. The two techniques are almost identical; it's mostly a matter of taste.
+====
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/20b83ae7/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_core-domain-api_DomainObjectContainer_security-api.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_core-domain-api_DomainObjectContainer_security-api.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_core-domain-api_DomainObjectContainer_security-api.adoc
new file mode 100644
index 0000000..3828745
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_core-domain-api_DomainObjectContainer_security-api.adoc
@@ -0,0 +1,47 @@
+[[_rgsvc_core-domain-api_DomainObjectContainer_security-api]]
+= Security API
+: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 security API allows the domain object to obtain the identity of the user interacting with said object.
+
+[source,java]
+----
+public interface DomainObjectContainer {
+ UserMemento getUser();
+ ...
+}
+----
+
+where in turn (the essence of) `UserMemento` is:
+
+[source,java]
+----
+public final class UserMemento {
+ public String getName() { ... }
+ public boolean isCurrentUser(final String userName) { ... }
+
+ public List<RoleMemento> getRoles() { ... }
+ public boolean hasRole(final RoleMemento role) { ... }
+ public boolean hasRole(final String roleName) { ... }
+ ...
+}
+----
+
+and `RoleMemento` is simpler still:
+
+[source,java]
+----
+public final class RoleMemento {
+ public String getName() { ... }
+ public String getDescription() { ... }
+ ...
+}
+----
+
+The roles associated with the `UserMemento` will be based on the configured xref:../ugsec/ugsec.adoc#[security] (typically Shiro).
+
+In addition, when using the xref:../ugvw/ugvw.adoc#[Wicket viewer] there will be an additional "org.apache.isis.viewer.wicket.roles.USER" role; this is used internally to restrict access to web pages without authenticating.
http://git-wip-us.apache.org/repos/asf/isis/blob/20b83ae7/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_core-domain-api_DomainObjectContainer_services-api.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_core-domain-api_DomainObjectContainer_services-api.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_core-domain-api_DomainObjectContainer_services-api.adoc
new file mode 100644
index 0000000..c38df4d
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_core-domain-api_DomainObjectContainer_services-api.adoc
@@ -0,0 +1,36 @@
+[[_rgsvc_core-domain-api_DomainObjectContainer_services-api]]
+= Services API
+: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 services API allows your domain objects to programmatically inject services into arbitrary objects, as well as to look up services by type.
+
+The methods are:
+
+[source,java]
+----
+public interface DomainObjectContainer {
+ <T> T injectServicesInto(final T domainObject); // <1>
+ <T> T lookupService(Class<T> service); // <2>
+ <T> Iterable<T> lookupServices(Class<T> service); // <3>
+ ...
+}
+----
+<1> injects services into domain object; used extensively internally by the framework (eg to inject to other services, or to entities, or integration test instances, or fixture scripts). Service injection is done automatically if objects are created using `#newTransientInstance()`, described xref:../rgsvc/rgsvc.adoc#_rgsvc_core-domain-api_DomainObjectContainer_object-creation-api[above]
+<2> returns the first registered service that implements the specified class
+<3> returns an `Iterable` in order to iterate over all registered services that implement the specified class
+
+The primary use case is to instantiate domain objects using a regular constructor ("new is the new new") rather than using the xref:../rgsvc/rgsvc.adoc#_rgsvc_core-domain-api_DomainObjectContainer_object-creation-api[`#newTransientInstance()`] API, and then using the `#injectServicesInto(...)` API to set up any dependencies.
+
+For example:
+
+[source,java]
+----
+Customer cust = container.injectServicesInto( new Customer());
+cust.setFirstName("Freddie");
+cust.setLastName("Mercury");
+container.persist(cust);
+----
+
http://git-wip-us.apache.org/repos/asf/isis/blob/20b83ae7/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_core-domain-api_DomainObjectContainer_validation-api.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_core-domain-api_DomainObjectContainer_validation-api.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_core-domain-api_DomainObjectContainer_validation-api.adoc
new file mode 100644
index 0000000..a378e7d
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_core-domain-api_DomainObjectContainer_validation-api.adoc
@@ -0,0 +1,28 @@
+[[_rgsvc_core-domain-api_DomainObjectContainer_validation-api]]
+= Validation API
+: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 intent of this API is to provide a mechanism where an object can programmatically check the state any class
+invariants. Specifically, this means the validating the current state of all properties, as well as any object-level
+validation defined by xref:../rgcms/rgcms.adoc#_rgcms_methods_reserved_validate[`validate()`].
+
+[WARNING]
+====
+These methods have been deprecated; this feature should be considered experimental and your mileage may vary.
+====
+
+
+The API provided is:
+
+[source,java]
+----
+public interface DomainObjectContainer {
+ boolean isValid(Object domainObject);
+ String validate(Object domainObject);
+ ...
+}
+----
+