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:05 UTC
[29/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/_rgsvc_api_QueryResultsCache.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_QueryResultsCache.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_QueryResultsCache.adoc
deleted file mode 100644
index 27c30ee..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_QueryResultsCache.adoc
+++ /dev/null
@@ -1,126 +0,0 @@
-[[_rgsvc_api_QueryResultsCache]]
-= `QueryResultsCache`
-: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 purpose of the `QueryResultsCache` is to improve response times to the user, by providing a short-term (link:../../more-advanced-topics/how-to-09-020-How-to-write-a-typical-domain-service.html[request-scoped]) cache of the value of some (safe or idempotent) method call. This will typically be as the result of running a query, but could be any expensive operation.
-
-Caching such values is useful for code that loops "naively" through a bunch of stuff, performing an expensive operation each time. If the data is such that the same expensive operation is made many times, then the query cache is a perfect fit.
-
-
-[NOTE]
-====
-This service was inspired by similar functionality that exists in relational databases, for example Sybase's http://infocenter.sybase.com/help/index.jsp?topic=/com.sybase.dc20023_1251/html/optimizer/X43480.htm[subquery results cache] and Oracle's http://www.dba-oracle.com/oracle11g/oracle_11g_result_cache_sql_hint.htm[result_cache] hint.
-====
-
-
-
-== API & Implementation
-
-The API defined by `QueryResultsCache` is:
-
-[source,java]
-----
-@RequestScoped
-public class QueryResultsCache {
- public static class Key {
- public Key(Class<?> callingClass, String methodName, Object... keys) {...}
- public Class<?> getCallingClass() { ... }
- public String getMethodName() { ... }
- public Object[] getKeys() { ... }
- }
- public static class Value<T> {
- public Value(T result) { ... }
- private T result;
- public T getResult() {
- return result;
- }
- }
- @Programmatic
- public <T> T execute(
- final Callable<T> callable,
- final Class<?> callingClass, final String methodName, final Object... keys) { ... }
- @Programmatic
- public <T> T execute(final Callable<T> callable, final Key cacheKey) { ... }
- @Programmatic
- public <T> Value<T> get(
- final Class<?> callingClass, final String methodName, final Object... keys) { ... }
- @Programmatic
- public <T> Value<T> get(final Key cacheKey) { ... }
- @Programmatic
- public <T> void put(final Key cacheKey, final T result) { ... }
-}
-----
-
-This class (`o.a.i.applib.services.queryresultscache.QueryResultsCache`) is also the implementation.
-
-
-
-
-== Usage
-
-Suppose that there's a `TaxService` that calculates tax on `Taxable` items, with respect to some `TaxType`, and for a given `LocalDate`. To calculate tax it must run a database query and then perform some additional calculations.
-
-Our original implementation is:
-
-[source,java]
-----
-@DomainService
-public class TaxService {
- public BigDecimal calculateTax(
- final Taxable t, final TaxType tt, final LocalDate d) {
- // query against DB using t, tt, d
- // further expensive calculations
- }
-}
-----
-
-Suppose now that this service is called in a loop, for example iterating over a bunch of orders, where several of those orders are for the same taxable products, say. In this case the result of the calculation would always be the same for any given product.
-
-We can therefore refactor the method to use the query cache as follows:
-
-[source,java]
-----
-public class TaxService {
- public BigDecimal calculateTax(
- final Taxable t, final TaxType tt, final LocalDate d) {
- return queryResultsCache.execute(
- new Callable<BigDecimal>(){ // <1>
- public BigDecimal call() throws Exception {
- // query against DB using t, tt, d
- // further expensive calculations
- }
- },
- TaxService.class, // <2>
- "calculateTax",
- t, tt, d);
- }
-}
-----
-<1> the `Callable` is the original code
-<2> the remaining parameters in essence uniquely identify the method call.
-
-This refactoring will be worthwhile provided that enough of the orders being processed reference the same taxable products. If however every order is for a different product, then no benefit will be gained from the refactoring.
-
-
-
-
-== Registering the Service
-
-Assuming that the `configuration-and-annotation` services installer is configured (implicit if using the
-`AppManifest` to xref:rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' core
-implementation of `QueryResultsCache` 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.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
-in the xref:rgsvc.adoc#__rgsvc_intro_overriding-the-services[introduction] to this guide).
-
-
-
-== Related Services
-
-The xref:rgsvc.adoc#_rgsvc_api_Scratchpad[`Scratchpad`] service is also intended for actions that are called many times, allowing arbitrary information to be shared between them. Those methods could be called from some outer loop in domain code, or by the framework itself if the action invoked has the xref:rgant.adoc#_rgant-Action_invokeOn[`@Action#invokeOn()`] annotation attribute set to `OBJECT_AND_COLLECTION` or `COLLECTION_ONLY`.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_RepositoryService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_RepositoryService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_RepositoryService.adoc
deleted file mode 100644
index 64d5a11..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_RepositoryService.adoc
+++ /dev/null
@@ -1,271 +0,0 @@
-[[_rgsvc_api_RepositoryService]]
-= `RepositoryService`
-: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 `RepositoryService` collects together methods for creating, persisting and searching for entities from the underlying persistence store. It 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.adoc#_rgsvc_api_IsisJdoSupport[`IsisJdoSupport`] service.
-
-
-[NOTE]
-====
-The methods in this service replace similar methods (now deprecated) in xref:rgsvc.adoc#_rgsvc_api_DomainObjectContainer[`DomainObjectContainer`].
-====
-
-
-== API
-
-The API of `RepositoryService` is:
-
-[source,java]
-----
-public interface RepositoryService {
- <T> T instantiate(final Class<T> ofType); // <1>
-
- boolean isPersistent(Object domainObject); // <2>
- void persist(Object domainObject); // <3>
- void persistAndFlush(Object domainObject); // <4>
-
- void remove(Object persistentDomainObject); // <5>
- void removeAndFlush(Object persistentDomainObject); // <6>
-
- <T> List<T> allInstances(Class<T> ofType, long... range); // <7>
-
- <T> List<T> allMatches(Query<T> query); // <8>
- <T> List<T> allMatches(Class<T> ofType, Predicate<? super T> predicate, long... range); // <9>
-
- <T> T uniqueMatch(Query<T> query); // <10>
- <T> T uniqueMatch(final Class<T> ofType, final Predicate<T> predicate); // <11>
-
- <T> T firstMatch(Query<T> query); // <12>
- <T> T firstMatch(final Class<T> ofType, final Predicate<T> predicate); // <13>
-}
-----
-<1> create a new non-persisted domain entity. This is identical to
-xref:rgsvc.adoc#_rgsvc_api_FactoryService[`FactoryService`]'s `instantiate(...)` method, but is provided in the
-``RepositoryService``'s API too because instantiating and persisting objects are often done together.
-<2> test whether a particular domain object is persistent or not
-<3> persist (ie save) an object to the persistent object store (or do nothing if it is already persistent).
-<4> persist (ie save) and flush; same as `persist()`, but also flushes changes to database and updates managed properties and collections (i.e., 1-1, 1-n, m-n relationships automatically maintained by the DataNucleus persistence mechanism).
-<5> remove (ie delete) an object from the persistent object store (or do nothing if it has already been deleted).
-<6> remove (delete) and flush; same as `remove()`, but also flushes changes to database and updates managed properties and collections (i.e., 1-1, 1-n, m-n relationships automatically maintained by the DataNucleus persistence mechanism).
-<7> return 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.
-<8> 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*
-<9> As the previous, but with client-side filtering using a `Predicate`. Only really intended for prototyping.
-<10> Returns the first instance that matches the supplied query. If no instance is found then `null `will be returned, while if there is more that one instances a run-time exception will be thrown. Generally this method is preferred for looking up an object by its (primary or alternate) key.
-<11> As the previous, but with client-side filtering using a `Predicate`. Only really intended for prototyping.
-<12> Returns the first instance that matches the supplied query. If no instance is found then `null `will be returned. No exception is thrown if more than one matches, so this is less strict that `uniqueMatch(...)`.
-<13> As the previous, but with client-side filtering using a `Predicate`. Only really intended for prototyping.
-
-
-The `uniqueMatch(...)` methods are the recommended way of querying for (precisely) one instance. The `firstMatch(...)` methods are for less strict querying.
-
-
-== Usage
-
-This section briefly discusses how application code can use (some of) these APIs.
-
-
-=== Persist
-
-[source,java]
-----
-Customer cust = repositoryService.instantiate(Customer.class);
-cust.setFirstName("Freddie");
-cust.setLastName("Mercury");
-repositoryService.persist(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.adoc#_rgsvc_api_DomainObjectContainer_generic-repository-api[above]. However, this behaviour can be disabled using the xref:rgcfg.adoc#_rgcfg_configuring-core[configuration property] `isis.services.container.disableAutoFlush`.
-
-
-
-=== `persistAndFlush(...)`, `removeAndFlush(...)`
-
-In some cases, such as when using managed properties and collections for implementing 1-1, 1-n, or m-n relationships,
-the developer needs to invoke `flush()` to send the changes to the DataNucleus persistence mechanism. These
-managed properties and collections and then updated.
-
-The `persistAndFlush(...)` and `removeAndFlush(...)` methods save the developer from
-having to additionally call the `flush(...)` method after calling `persist()` or `remove()`.
-
-For example, the following code requires a flush to occur, so uses these methods:
-
-[source,java]
-----
-public abstract class Warehouse extends SalesVIPEntity<Marketplace> {
-
- @Persistent(mappedBy = "marketplace", dependentElement = "true")
- @Getter @Setter // <1>
- private SortedSet<MarketplaceExcludedProduct> excludedProducts =
- new TreeSet<MarketplaceExcludedProduct>();
-
- @Action(semantics = SemanticsOf.IDEMPOTENT)
- public MarketplaceExcludedProduct addExcludedProduct(final Product product) {
- MarketplaceExcludedProduct marketplaceExcludedProduct = this.findExcludedProduct(product);
- if (marketplaceExcludedProduct == null) {
- marketplaceExcludedProduct =
- this.factoryService.instantiate(MarketplaceExcludedProduct.class);
- }
-
- this.wrap(marketplaceExcludedProduct).setMarketplace(this);
- this.wrap(marketplaceExcludedProduct).setProduct(product);
-
- this.repositoryService.persistAndFlush(marketplaceExcludedProduct); // <2>
- return marketplaceExcludedProduct;
- }
-
- @Action(semantics = SemanticsOf.IDEMPOTENT)
- public void deleteFromExcludedProducts(final Product product) {
- final MarketplaceExcludedProduct marketplaceExcludedProduct = findExcludedProduct(product);
- if (marketplaceExcludedProduct != null) {
- this.repositoryService.removeAndFlush(marketplaceExcludedProduct);
- }
- }
- ... // <3>
-}
-----
-<1> using lombok for brevity
-<2> Needed for updating the managed properties and collections.
-<3> injected services and other methods ommited
-
-On the \u201caddExcludedProduct()\u201d action, if the user didn\u2019t flush, the following test would fail because the managed
-collection would not containing the given product:
-
-[source,java]
-----
-@Test
-public void addExcludedProduct() {
-
- // given
- final AmazonMarketplace amazonMarketplace = this.wrapSkipRules(
- this.marketplaceRepository).findOrCreateAmazonMarketplace(
- AmazonMarketplaceLocation.FRANCE);
-
- final Product product = this.wrap(this.productRepository)
- .createProduct(UUID.randomUUID().toString(), UUID.randomUUID().toString());
-
- // when
- this.wrap(amazonMarketplace).addExcludedProduct(product);
-
- // then
- Assertions.assertThat(
- this.wrapSkipRules(amazonMarketplace).findAllProductsExcluded()
- ).contains(product); // <1>
-}
-----
-<1> this would fail.
-
-
-
-=== Query and `xxxMatches(...)`
-
-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.adoc#_rgsvc_api_IsisJdoSupport[`IsisJdoSupport`].
-====
-
-
-
-== Implementation
-
-The core framework provides a default implementation of this service (`o.a.i.core.metamodel.services.repository.RepositoryServiceDefault`).
-
-
-
-
-=== (Disabling) Auto-flush
-
-Normally any queries are automatically preceded by flushing pending commands to persist or remove objects.
-
-This key allows this behaviour to be disabled.
-
- *
- * <p>
- * Originally introduced as part of ISIS-1134 (fixing memory leaks in the objectstore)
- * where it was found that the autoflush behaviour was causing a (now unrepeatable)
- * data integrity error (see <a href="https://issues.apache.org/jira/browse/ISIS-1134?focusedCommentId=14500638&page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#comment-14500638">ISIS-1134 comment</a>, in the isis-module-security.
- * However, that this could be circumvented by removing the call to flush().
- * We don't want to break existing apps that might rely on this behaviour, on the
- * other hand we want to fix the memory leak. Adding this configuration property
- * seems the most prudent way forward.
- * </p>
- */
- public static final String KEY_DISABLE_AUTOFLUSH = "isis.services.container.disableAutoFlush";
-
-
-
-== Registering the Service
-
-Assuming that the `configuration-and-annotation` services installer is configured (implicit if using the
-`AppManifest` to xref:rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' core
-implementation of `RepositoryService` 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.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
-in the xref:rgsvc.adoc#__rgsvc_intro_overriding-the-services[introduction] to this guide).
-
-
-
-== Related Services
-
-the xref:rgsvc.adoc#_rgsvc_api_FactoryService[`FactoryService`] is often used in conjunction with the `RepositoryService`, to instantiate domain objects before persisting.
-
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_Scratchpad.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_Scratchpad.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_Scratchpad.adoc
deleted file mode 100644
index 4d170b3..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_Scratchpad.adoc
+++ /dev/null
@@ -1,128 +0,0 @@
-[[_rgsvc_api_Scratchpad]]
-= `Scratchpad`
-: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 `Scratchpad` service is a link:../../more-advanced-topics/how-to-09-020-How-to-write-a-typical-domain-service.html[request-scoped] service to allow objects to exchange information even if they do not directly call each other.
-
-
-
-
-== API & Implementation
-
-The API of `Scratchpad` service is:
-
-[source,java]
-----
-@RequestScoped
-public class Scratchpad {
- @Programmatic
- public Object get(Object key) { ... }
- @Programmatic
- public void put(Object key, Object value) { ... }
- @Programmatic
- public void clear() { ... }
-}
-----
-
-This class (`o.a.i.applib.services.scratchpad.Scratchpad`) is also the implementation. And, as you can see, the service is just a request-scoped wrapper around a `java.util.Map`.
-
-
-
-
-
-== Usage
-
-The most common use-case is for xref:rgant.adoc#_rgant-Action_invokeOn[bulk] actions that act upon multiple objects in a list. The (same) `Scratchpad` service is injected into each of these objects, and so they can use pass information.
-
-For example, the Isis addons example https://github.com/isisaddons/isis-app-todoapp/[todoapp] (not ASF) demonstrates how the `Scratchpad` service can be used to calculate the total cost of the selected `ToDoItem`s:
-
-
-[source,java]
-----
-@Action(
- semantics=SemanticsOf.SAFE,
- invokeOn=InvokeOn.COLLECTION_ONLY
-)
-public BigDecimal totalCost() {
- BigDecimal total = (BigDecimal) scratchpad.get("runningTotal");
- if(getCost() != null) {
- total = total != null ? total.add(getCost()) : getCost();
- scratchpad.put("runningTotal", total);
- }
- return total.setScale(2);
-}
-@Inject
-Scratchpad scratchpad;
-----
-
-A more complex example could use a xref:ugbtb.adoc#_ugbtb_view-models[view model] to enable bulk updates to a set of objects. The view model's job is to gather track of the items to be updated:
-
-[source,java]
-----
-public class ToDoItemUpdateBulkUpdate extends AbstractViewModel {
- private List<ToDoItem> _items = ...;
- public ToDoItemBulkUpdate add(ToDoItem item) {
- _items.add(item);
- return this;
- }
- ... // <1>
-}
-----
-<1> not shown - the implementation of `ViewModel` for converting the list of `_items` into a string.
-
-The bulk action in the objects simply adds the selected item to the view model:
-
-[source,java]
-----
-@Action(
- invokeOn=InvokeOn.COLLECTIONS_ONLY
- semantics=SemanticsOf.SAFE
-)
-public ToDoItemBulkUpdate bulkUpdate() {
- return lookupBulkUpdateViewModel().add(this);
-}
-private ToDoItemBulkUpdate lookupBulkUpdateViewModel() {
- ToDoItemBulkUpdate bulkUpdate =
- (ToDoItemBulkUpdate) scratchpad.get("bulkUpdateViewModel"); // <1>
- if(bulkUpdate == null) {
- bulkUpdate = container.injectServicesInto(new ToDoItemBulkUpdate());
- scratchpad.put("bulkUpdateViewModel", bulkUpdate); // <2>
- }
- return bulkUpdate;
-}
-@Inject
-Scratchpad scratchpad;
-----
-<1> look for the `ToDoItemBulkUpdate` in the scratchpad...
-<2> ... and add one if there isn't one (ie for the first object returned).
-
-If using the xref:ugvw.adoc#[Wicket viewer], the `ToDoItemBulkUpdate` view model returned from the last action invoked will be displayed. Thereafter this view model can be used to perform a bulk update of the "enlisted" items.
-
-
-
-
-
-== Registering the Service
-
-Assuming that the `configuration-and-annotation` services installer is configured (implicit if using the
-`AppManifest` to xref:rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' core
-implementation of `Scratchpad` 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.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
-in the xref:rgsvc.adoc#__rgsvc_intro_overriding-the-services[introduction] to this guide).
-
-
-
-
-
-== Related Services
-
-The xref:rgsvc.adoc#_rgsvc_api_ActionInteractionContext[`ActionInteractionContext`] service allows xref:rgant.adoc#_rgant-Action_invokeOn[bulk actions] to co-ordinate with each other.
-
-The xref:rgsvc.adoc#_rgsvc_api_QueryResultsCache[`QueryResultsCache`] is useful for caching the results of expensive method calls.
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_ServiceRegistry.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_ServiceRegistry.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_ServiceRegistry.adoc
deleted file mode 100644
index 7916878..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_ServiceRegistry.adoc
+++ /dev/null
@@ -1,75 +0,0 @@
-[[_rgsvc_api_ServiceRegistry]]
-= `ServiceRegistry2`
-: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 `ServiceRegistry2` service collects together methods for accessing other domain services.
-
-[NOTE]
-====
-The methods in this service replace similar methods (now deprecated) in xref:rgsvc.adoc#_rgsvc_api_DomainObjectContainer[`DomainObjectContainer`].
-====
-
-
-== API
-
-The API of `ServiceRegistry2` is:
-
-[source,java]
-----
-public interface ServiceRegistry2 {
- <T> T injectServicesInto(final T domainObject); // <1>
- <T> T lookupService(Class<T> service); // <2>
- <T> Iterable<T> lookupServices(Class<T> service); // <3>
- List<Object> getRegisteredServices(); // <4>
-}
-----
-<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).
-<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
-<4> returns the list of all domain services that constitute the running application (including internal domain services).
-
-Service injection is done automatically if objects are created using the
-xref:rgsvc.adoc#_rgsvc_api_FactoryService[`FactoryService`].
-
-
-
-== Usage
-
-The primary use case is to instantiate domain objects using a regular constructor ("new is the new new"), and then using the `#injectServicesInto(...)` API to set up any dependencies.
-
-For example:
-
-[source,java]
-----
-Customer cust = serviceRegistry.injectServicesInto( new Customer());
-cust.setFirstName("Freddie");
-cust.setLastName("Mercury");
-repositoryService.persist(cust);
-----
-
-The alternative is to use the xref:rgsvc.adoc#_rgsvc_api_FactoryService[`FactoryService`] API which performs both steps in a single factory method.
-
-
-
-== Implementation
-
-The core framework provides a default implementation of this service (`o.a.i.core.runtime.services.registry.ServiceRegistryDefault`).
-
-
-
-
-== Registering the Service
-
-Assuming that the `configuration-and-annotation` services installer is configured (implicit if using the
-`AppManifest` to xref:rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' core
-implementation of `ServiceRegistry` 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.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
-in the xref:rgsvc.adoc#__rgsvc_intro_overriding-the-services[introduction] to this guide).
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_SessionManagementService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_SessionManagementService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_SessionManagementService.adoc
deleted file mode 100644
index 8d263eb..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_SessionManagementService.adoc
+++ /dev/null
@@ -1,56 +0,0 @@
-[[_rgsvc_api_SessionManagementService]]
-= `SessionManagementService`
-: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 `SessionManagementService` provides the ability to programmatically manage sessions. The primary use case is
-for fixture scripts or other routines that are invoked from the UI and which create or modify large amounts of data.
-A classic example is migrating data from one system to another.
-
-
-
-== API
-
-The API of `SessionManagementService` is:
-
-
-[source,java]
-----
-public interface SessionManagementService {
- void nextSession();
-}
-----
-
-
-Normally, the framework will automatically start a session and then a transaction before each user interaction
-(action invocation or property modification), and wil then commit that transaction and close the session after the
-interaction has completed. If the interaction throws an exception then the transaction is aborted.
-
-The `nextSession()` method allows a domain object to commit the transaction, close the session, then open a new
-session and start a new transaction.
-
-[IMPORTANT]
-====
-Any domain objects that were created in the "previous" session are no longer usable, and must not be rendered in the UI.
-====
-
-
-
-== Implementation
-
-The core framework provides a default implementation of this service (`o.a.i.core.runtime.services.xactn.SessionManagementServiceDefault`).
-
-
-
-== Registering the Service
-
-Assuming that the `configuration-and-annotation` services installer is configured (implicit if using the
-`AppManifest` to xref:rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' core
-implementation of `SessionManagementService` 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.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
-in the xref:rgsvc.adoc#__rgsvc_intro_overriding-the-services[introduction] to this guide).
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_SudoService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_SudoService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_SudoService.adoc
deleted file mode 100644
index 0020008..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_SudoService.adoc
+++ /dev/null
@@ -1,137 +0,0 @@
-[[_rgsvc_api_SudoService]]
-= `SudoService`
-: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 `SudoService` allows the current user reported by the xref:rgsvc.adoc#_rgsvc_api_UserService[`UserService`] to be temporarily changed to some other user.
-This is useful both for xref:ugtst.adoc#_ugtst_integ-test-support[integration testing] (eg if testing a workflow system whereby objects are moved from one user to another) and while running xref:ugtst.adoc#_ugtst_fixture-scripts[fixture scripts] (eg setting up objects that would normally require several users to have acted upon the objects).
-
-
-== API
-
-The API provided by the service is:
-
-[source,java]
-----
-public interface SudoService {
- @Programmatic
- void sudo(String username, final Runnable runnable);
- @Programmatic
- <T> T sudo(String username, final Callable<T> callable);
- @Programmatic
- void sudo(String username, List<String> roles, final Runnable runnable);
- @Programmatic
- <T> T sudo(String username, List<String> roles, final Callable<T> callable);
-}
-----
-
-which will run the provided block of code (a `Runnable` or a `Callable`) in a way such that calls to
-`UserService#getUser()` will return the specified user (and roles, if specified).
-(If roles are not specified, then the roles of the current user are preserved).
-
-The current user/role reported by the internal xref:rgfis.adoc#_rgfis_spi_AuthenticationSessionProvider[`AuthenticationSessionProvider`] will also return the specified user/roles.
-
-[IMPORTANT]
-====
-Note however that this the "effective user" does not propagate through to the xref:ugsec.adoc#[Shiro security mechanism], which will continue to be evaluated according to the permissions of the current user.
-See the xref:rgsvc.adoc#__rgsvc_api_SudoService_ACCESS-ALL-ROLE[`ACCESS-ALL-ROLE`] below for details of how to circumvent this.
-====
-
-
-== Implementation
-
-The core framework provides a default implementation of this service (`o.a.i.core.runtime.services.sudo.SudoServiceDefault`).
-
-
-
-== Usage
-
-A good example can be found in the (non-ASF) http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp] which uses the `SudoService` in a fixture script to set up `ToDoItem` objects:
-
-[source,java]
-----
-protected void execute(final ExecutionContext ec) {
- ...
- sudoService.sudo(getUsername(),
- new Runnable() {
- @Override
- public void run() {
- wrap(toDoItem).completed();
- }
- });
- ...
-}
-----
-
-
-[[__rgsvc_api_SudoService_ACCESS-ALL-ROLE]]
-=== ACCESS_ALL_ROLE
-
-When `sudo(...)` is called the "effective user" is reported by both xref:rgsvc.adoc#_rgsvc_api_UserService[`UserService`] and by xref:rgfis.adoc#_rgfis_spi_AuthenticationSessionProvider[`AuthenticationSessionProvider`], but does not propagate through to the xref:ugsec.adoc#[Shiro security mechanism].
-These continue to be evaluated according to the permissions of the current user.
-
-This can be a problem in certain use cases.
-For example if running a fixture script (which uses the xref:rgsvc.adoc#_rgsvc_api_WrapperFactory[`WrapperFactory`]) from within an implementation of xref:rgsvc.adoc#_rgsvc_spi_UserRegistrationService[`UserRegistrationService`], this is likely to result in ``HiddenException``s being thrown because there is no effective user.
-
-In such cases, permission checking can simply be disabled by specifying `SudoService.ACCESS_ALL_ROLE` as one of the roles.
-For example:
-
-[source,java]
-----
-protected void execute(final ExecutionContext ec) {
- ...
- sudoService.sudo(getUsername(), Arrays.asList(SudoService.ACCESS_ALL_ROLE),
- new Runnable() {
- @Override
- public void run() {
- wrap(toDoItem).completed();
- }
- });
- ...
-}
-----
-
-[NOTE]
-====
-In the future this service may be used more deeply, eg to propagate permissions through to the Shiro security mechanism also.
-====
-
-
-
-
-== SPI
-
-The `SudoService.Spi` service allows implementations of `SudoService` to notify other services/components that the effective user and roles are different.
-The default implementation of xref:rgsvc.adoc#_rgsvc_api_UserService[`UserService`] has been refactored to leverage this SPI.
-
-[source,java]
-----
-public interface SudoService {
- ...
- interface Spi {
- void runAs(String username, List<String> roles); // <1>
- void releaseRunAs(); // <2>
- }
-}
-----
-<1> Called by `SudoService#sudo(...)`, prior to invoking its `Runnable` or `Callable`.
-<2> Called by `SudoService#sudo(...)`, after its `Runnable` or `Callable` has been invoked.
-
-The names of these methods were chosen based on link:href:https://shiro.apache.org/static/1.2.6/apidocs/org/apache/shiro/subject/Subject.html#runAs-org.apache.shiro.subject.PrincipalCollection-[similar names within Shiro].
-
-
-
-
-== Registering the Service
-
-Assuming that the `configuration-and-annotation` services installer is configured (implicit if using the
-`AppManifest` to xref:rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' core
-implementation of `SudoService` 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.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
-in the xref:rgsvc.adoc#__rgsvc_intro_overriding-the-services[introduction] to this guide).
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_SwaggerService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_SwaggerService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_SwaggerService.adoc
deleted file mode 100644
index c376675..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_SwaggerService.adoc
+++ /dev/null
@@ -1,69 +0,0 @@
-[[_rgsvc_api_SwaggerService]]
-= `SwaggerService`
-: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 `SwaggerService` generates link:http://swagger.io/[Swagger] spec files to describe the public and/or private RESTful APIs exposed by the xref:ugvro.adoc#[RestfulObjects viewer].
-
-These spec files can then be used with the link:http://swagger.io/swagger-ui/[Swagger UI] page to explore the REST API, or used to generate client-side stubs using the link:http://swagger.io/swagger-codegen/[Swagger codegen] tool, eg for use in a custom REST client app.
-
-[NOTE]
-====
-Not all of the REST API exposed by the xref:ugvro.adoc#[Restful Objects viewer] is included in the Swagger spec files; the emphasis is those REST resources that are used to develop custom apps: domain objects, domain object collections and action invocations. When combined with Apache Isis' own xref:ugvro.adoc#_ugvro_simplified-representations[simplified representations], these are pretty much all that is needed for this use case.
-====
-
-
-
-[[__rgsvc_api_SwaggerService_api-and-implementation]]
-== API & Implementation
-
-The API defined by `SwaggerService` is:
-
-[source,java]
-----
-public interface SwaggerService {
- enum Visibility {
- PUBLIC, // <1>
- PRIVATE, // <2>
- PRIVATE_WITH_PROTOTYPING; // <3>
- }
- enum Format { // <4>
- JSON,
- YAML
- }
- String generateSwaggerSpec(final Visibility visibility, final Format format);
-}
-----
-<1> Generate a Swagger spec for use by third-party clients, ie public use. This specification is restricted only to
-xref:ugbtb.adoc#_ugbtb_view-models[view model]s and to domain services with a xref:rgant.adoc#_rgant-DomainService_nature[nature] of `VIEW_REST_ONLY`.
-<2> Generate a Swagger spec for use only by internally-managed clients, ie private internal use. This specification includes domain entities and all menu domain services (as well as any view models).
-<3> Generate a Swagger spec that is the same as private case (above), but also including any xref:rgant.adoc#_rgant-Action_restrictTo[prototype] actions.
-<4> Swagger specs can be written either in JSON or YAML format.
-
-Isis provides a default implementation of the service, `o.a.i.core.metamodel.services.swagger.SwaggerServiceDefault`.
-
-
-
-== Usage within the framework
-
-This service is provided as a convenience for applications, it is not (currently) used by the framework itself.
-
-
-
-== Registering the Service
-
-Assuming that the `configuration-and-annotation` services installer is configured (implicit if using the
-`AppManifest` to xref:rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' core
-implementation of `SwaggerService` service is automatically registered and injected (it is annotated with `@DomainService`) so no further configuration is required.
-
-
-== Related Services
-
-A `SwaggerServiceMenu` domain service provides a prototype action that enables the swagger spec to be downloaded from the Wicket viewer's UI.
-
-Apache Isis' xref:rgmvn.aod[Maven plugin] also provides a xref:rgmvn.adoc#_rgmvn_swagger[swagger goal] which allows the spec file(s) to be generated at build time. this then allows client-side stubs can then be generated in turn as part of a build pipeline.
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_SwitchUserService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_SwitchUserService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_SwitchUserService.adoc
deleted file mode 100644
index 8305ae2..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_SwitchUserService.adoc
+++ /dev/null
@@ -1,42 +0,0 @@
-[[_rgsvc_api_SwitchUserService]]
-= `SwitchUserService` (deprecated)
-: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 `SwitchUserService` domain service provides the ability to install fixtures changing the effective user half-way
-through. For example, this allows the setup of a test of a workflow system which checks that work is moved between
-different users of the system.
-
-
-[NOTE]
-====
-This service is deprecated; use xref:ugtst.adoc#_ugtst_fixture-scripts[fixture scripts] and the
-xref:rgsvc.adoc#_rgsvc_api_SudoService[`SudoService`] instead.
-====
-
-
-
-== API
-
-The API of this service:
-
-[source,java]
-----
-public class SwitchUserService {
- void switchUser(String username, String... roles); // <1>
- void switchUser(String username, List<String> roles); // <2>
-}
-----
-<1> Switches the current user with the list of specified roles.
-<2> Switches the current user with the list of specified roles.
-
-
-
-
-
-== Implementation
-
-The framework provides a default implementation of this service: `SwitchUserServiceImpl` in `isis-core-runtime`
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_TitleService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_TitleService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_TitleService.adoc
deleted file mode 100644
index feb1383..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_TitleService.adoc
+++ /dev/null
@@ -1,74 +0,0 @@
-[[_rgsvc_api_TitleService]]
-= `TitleService`
-: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 `TitleService` provides methods to programmatically obtain the title and icon of a domain object.
-
-[NOTE]
-====
-The methods in this service replace similar methods (now deprecated) in xref:rgsvc.adoc#_rgsvc_api_DomainObjectContainer[`DomainObjectContainer`].
-====
-
-
-
-== API
-
-The API of `TitleService` is:
-
-[source,java]
-----
-public interface PresentationService {
- 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.
-
-
-
-== Usage
-
-By way of example, here's some code based on a system for managing government benefits:
-
-[source,java]
-----
-public class QualifiedAdult {
-
- private Customer qualifying;
-
- public String title() {
- return "QA for " + titleService.titleOf(qualifying);
- }
-
- ...
- @Inject
- TitleService titleService;
-}
-----
-
-In this example, whatever the title of a `Customer`, it is reused within the title of that customer's ``QualifiedAdult`` object.
-
-
-
-== Implementation
-
-The core framework provides a default implementation of this service (`o.a.i.core.metamodel.services.title.TitleServiceDefault`).
-
-
-
-== Registering the Service
-
-Assuming that the `configuration-and-annotation` services installer is configured (implicit if using the
-`AppManifest` to xref:rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' core
-implementation of `TitleService` 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.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
-in the xref:rgsvc.adoc#__rgsvc_intro_overriding-the-services[introduction] to this guide).
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_TransactionService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_TransactionService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_TransactionService.adoc
deleted file mode 100644
index 0eff151..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_TransactionService.adoc
+++ /dev/null
@@ -1,97 +0,0 @@
-[[_rgsvc_api_TransactionService]]
-= `TransactionService`
-: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 `TransactionService` provides a small number of methods to allow domain objects to influence user transactions.
-
-[NOTE]
-====
-The methods in this service replace similar methods (now deprecated) in xref:rgsvc.adoc#_rgsvc_api_DomainObjectContainer[`DomainObjectContainer`].
-====
-
-
-== API
-
-The API of `TransactionService` is:
-
-[source,java]
-----
-public interface TransactionService {
- Transaction currentTransaction(); // <1>
- void nextTransaction(); // <2>
- void flushTransaction(); // <3>
-}
-----
-<1> to obtain a handle on the current `Transaction`, discussed further below
-<2> The framework automatically start a transaction before each user interaction (action invocation or property edit),
-and will commit that transaction after the interaction has completed. Under certain circumstances (eg actions used to
-perform data migration, say, or for large fixture scripts), it can be helpful to programmatically complete one
-transaction and start another one.
-<3> If the user interaction creates/persists an object or deletes an object (eg using the
-xref:rgsvc.adoc#_rgsvc_api_RepositoryService[`RepositoryService`]'s `persist()` or `delete()` methods), then the
-framework actually queues up the work and only performs the persistence command either at the end of the transaction
-or immediately prior to the next query. Performing a flush will cause any pending calls to be performed immediately.
-
-The `nextTransaction()` is also used by the xref:ugvw.adoc#[Wicket viewer]'s support for bulk actions; each action
-is invoked in its own transaction.
-
-The `Transaction` object - as obtained by `currentTransaction()` method, above - is a minimal wrapper around the
-underlying database transaction. Its API is:
-
-[source,java]
-----
-public interface Transaction {
- UUID getTransactionId(); // <1>
- int getSequence(); // <2>
- void flush(); // <3>
- void clearAbortCause(); // <4>
-}
-----
-<1> is a unique identifier for the interaction/request, as defined by the
-xref:rgcms.adoc#_rgcms_classes_mixins_HasTransactionId[`HasTransactionId`] mixin.
-<2> there can actually be multiple transactions within such a request/interaction; the sequence is a (0-based) is used
-to distinguish such.
-<3> as per `TransactionService#flushTransaction()` described above.
-<4> If the cause has been rendered higher up in the stack, then clear the cause so that it won't be picked up and
-rendered elsewhere.
-
-[TIP]
-====
-One place where `clearAboutCause()` may be useful is for application-level handling of SQL integrity exceptions, eg as
-described in link:https://issues.apache.org/jira/browse/ISIS-1476[ISIS-1476]:
-
-[source,java]
-----
-try {
- // do something...
-} catch (final JDODataStoreException e) {
- if (Iterables.filter(Throwables.getCausalChain(e),
- SQLIntegrityConstraintViolationException.class) != null) {
- // ignore
- this.transactionService.currentTransaction().clearAbortCause();
- } else {
- throw e;
- }
-}
-----
-====
-
-
-== Implementation
-
-The core framework provides a default implementation of this service (`o.a.i.core.metamodel.services.xactn.TransactionServiceInternalDefault`).
-
-
-== Registering the Service
-
-Assuming that the `configuration-and-annotation` services installer is configured (implicit if using the
-`AppManifest` to xref:rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' core
-implementation of `TransactionService` 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.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
-in the xref:rgsvc.adoc#__rgsvc_intro_overriding-the-services[introduction] to this guide).
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_UserService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_UserService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_UserService.adoc
deleted file mode 100644
index ba5080c..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_UserService.adoc
+++ /dev/null
@@ -1,85 +0,0 @@
-[[_rgsvc_api_UserService]]
-= `UserService`
-: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 `UserService` allows the domain object to obtain the identity of the user interacting with said object.
-
-If xref:rgsvc.adoc#_rgsvc_api_SudoService[`SudoService`] has been used to temporarily override the user and/or roles, then this service will report the overridden values instead.
-
-
-[NOTE]
-====
-The methods in this service replace similar methods (now deprecated) in xref:rgsvc.adoc#_rgsvc_api_DomainObjectContainer[`DomainObjectContainer`].
-====
-
-
-
-
-== API and Usage
-
-The API of `UserService` is:
-
-[source,java]
-----
-public interface UserService {
- 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.adoc#[security] (typically Shiro).
-
-In addition, when using the xref: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.
-
-
-
-
-
-== Implementation
-
-The core framework provides a default implementation of this service (`o.a.i.core.runtime.services.user.UserServiceDefault`).
-
-
-
-
-== Registering the Service
-
-Assuming that the `configuration-and-annotation` services installer is configured (implicit if using the
-`AppManifest` to xref:rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' core
-implementation of `UserService` 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.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
-in the xref:rgsvc.adoc#__rgsvc_intro_overriding-the-services[introduction] to this guide).
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_WrapperFactory.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_WrapperFactory.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_WrapperFactory.adoc
deleted file mode 100644
index 2114742..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_WrapperFactory.adoc
+++ /dev/null
@@ -1,162 +0,0 @@
-[[_rgsvc_api_WrapperFactory]]
-= `WrapperFactory`
-: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 `WrapperFactory` provides the ability to enforce business rules for programmatic interactions between domain objects. If there is a (lack-of-) trust boundary between the caller and callee -- eg if they reside in different modules -- then the wrapper factory is a useful mechanism to ensure that any business constraints defined by te callee are honoured.
-
-For example, if the calling object attempts to modify an unmodifiable property on the target object, then an exception will be thrown. Said another way: interactions are performed "as if" they are through the viewer.
-
-[NOTE]
-====
-For a discussion of the use of the `WrapperFactory` within integration tests (the primary or at least original use case for this service) can be found xref:ugtst.adoc#_ugtst_integ-test-support_wrapper-factory[here]
-====
-
-This capability goes beyond enforcing the (imperative) constraints within the `hideXxx()`, `disableXxx()` and `validateXxx()` supporting methods; it also enforces (declarative) constraints such as those represented by annotations, eg `@MaxLength` or `@Regex`.
-
-This capability is frequently used within xref:ugtst.adoc#_ugtst_integ-test-support[integration tests], but can also be used in production code. (There are analogies that can be drawn here with the way that JEE beans can interact through an EJB local interface).
-
-
-
-
-== API
-
-The API provided by the service is:
-
-[source,java]
-----
-public interface WrapperFactory {
- @Programmatic
- <T> T wrap(T domainObject); // <1>
- @Programmatic
- <T> T unwrap(T possibleWrappedDomainObject); // <2>
- @Programmatic
- <T> boolean isWrapper(T possibleWrappedDomainObject); // <3>
-
- public static enum ExecutionMode { // <4>
- EXECUTE(true,true),
- SKIP_RULES(false, true), // <5>
- NO_EXECUTE(true, false); // <6>
- }
- @Programmatic
- <T> T wrap(T domainObject, ExecutionMode mode); // <7>
- @Programmatic
- <T> T wrapNoExecute(T domainObject); // <8>
- @Programmatic
- <T> T wrapSkipRules(T domainObject); // <9>
- ...
- }
-----
-<1> wraps the underlying domain object. If it is already wrapped, returns the object back unchanged.
-<2> Obtains the underlying domain object, if wrapped. If the object is not wrapped, returns back unchanged.
-<3> whether the supplied object has been wrapped.
-<4> enumerates how the wrapper interacts with the underlying domain object.
-<5> validate all business rules and then execute.
-<6> skip all business rules and then execute (including creating xref:rgant.adoc#_rgant-Action_command[command]s and firing pre- and post-execute xref:rgant.adoc#_rgant-Action_domainEvent[domain event]s).
-<7> validate all business rules (including those from xref:rgant.adoc#_rgant-Action_domainEvent[domain event]s) but do not execute.
-<8> convenience method to invoke `wrap(...)` with `ExecuteMode#NO_EXECUTE` (make this feature more discoverable)
-<9> convenience method to invoke `wrap(...)` with `ExecuteMode#SKIP_RULES` (make this feature more discoverable)
-
-
-
-The service works by returning a "wrapper" around a supplied domain object (a link:http://www.javassist.org[javassist] proxy), and it is this wrapper that ensures that the hide/disable/validate rules implies by the Apache Isis programming model are enforced. The wrapper can be interacted with as follows:
-
-* a `get...()` method for properties or collections
-* a `set...()` method for properties
-* an `addTo...()` or `removeFrom...()` method for collections
-* any action
-
-Calling any of the above methods may result in a (subclass of) `InteractionException` if the object disallows it. For example, if a property is annotated with `@Hidden` then a `HiddenException` will be thrown. Similarly if an action has a `validateXxx()` method and the supplied arguments are invalid then an `InvalidException` will be thrown.
-
-In addition, the following methods may also be called:
-
-* the xref:rgcms.adoc#_rgcms_methods_reserved_title[`title()`] and `toString()` methods
-* any xref:rgcms.adoc#_rgcms_methods_prefixes_default[`default...()`], xref:rgcms.adoc#_rgcms_methods_prefixes_choices[`choices...()`] or xref:rgcms.adoc#_rgcms_methods_prefixes_autoComplete[`autoComplete...()`] methods
-
-An exception will be thrown if any other methods are thrown.
-
-
-
-
-
-== Usage
-
-The caller will typically obtain the target object (eg from some repository) and then use the injected `WrapperFactory` to wrap it before interacting with it.
-
-For example:
-
-[source,java]
-----
-public class CustomerAgent {
- @Action
- public void refundOrder(final Order order) {
- final Order wrappedOrder = wrapperFactory.wrap(order);
- try {
- wrappedOrder.refund();
- } catch(InteractionException ex) { // <1>
- container.raiseError(ex.getMessage()); // <2>
- return;
- }
- }
- ...
- @Inject
- WrapperFactory wrapperFactory;
- @Inject
- DomainObjectContainer container;
-}
-----
-<1> if any constraints on the `Order`'s `refund()` action would be violated, then ...
-<2> ... these will be trapped and raised to the user as a warning.
-
-[NOTE]
-====
-It ought to be possible to implement an xref:rgsvc.adoc#_rgsvc_spi_ExceptionRecognizer[`ExceptionRecognizer`]s that would allow the above boilerplate to be removed. This recognizer service would recognize the `InteractionException` and convert to a suitable message.
-
-At the time of writing Apache Isis does not provide an out-of-the-box implementation of such an `ExceptionRecognizer`; but it should be simple enough to write one\u2026
-====
-
-
-
-
-== Listener API
-
-The `WrapperFactory` also provides a listener API to allow other services to listen in on interactions.
-
-[source,java]
-----
-public interface WrapperFactory {
- ...
- @Programmatic
- List<InteractionListener> getListeners(); // <1>
- @Programmatic
- public boolean addInteractionListener(InteractionListener listener); // <2>
- @Programmatic
- public boolean removeInteractionListener(InteractionListener listener); // <3>
- @Programmatic
- public void notifyListeners(InteractionEvent ev); // <4>
-}
-----
-<1> all ``InteractionListener``s that have been registered.
-<2> registers an `InteractionListener`, to be notified of interactions on all wrappers. The listener will be notified of interactions even on wrappers created before the listener was installed. (From an implementation perspective this is because the wrappers delegate back to the container to fire the events).
-<3> remove an `InteractionListener`, to no longer be notified of interactions on wrappers.
-<4> used by the framework itself
-
-The original intent of this API was to enable test transcripts to be captured (in a BDD-like fashion) from integration tests. No such feature has yet been implemented however. Also, the capabilities have by and large been superceded by Apache Isis' support for domain events. We may therefore deprecate this API in the future.
-
-
-
-
-== Registering the Service
-
-Assuming that the `configuration-and-annotation` services installer is configured (implicit if using the
-`AppManifest` to xref:rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' core
-implementation of `WrapperFactory` 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.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
-in the xref:rgsvc.adoc#__rgsvc_intro_overriding-the-services[introduction] to this guide).
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_XmlSnapshotService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_XmlSnapshotService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_XmlSnapshotService.adoc
deleted file mode 100644
index f29c93b..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_XmlSnapshotService.adoc
+++ /dev/null
@@ -1,219 +0,0 @@
-[[_rgsvc_api_XmlSnapshotService]]
-= `XmlSnapshotService`
-: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 `XmlSnapshotService` provides the capability to generate XML snapshots (and if required corresponding XSD schemas) based on graphs of domain objects.
-
-Typical use cases include creating mementos for business-focused auditing, such that a report could be generated as to which end-user performed a business action (perhaps for legal reasons). For one system that we know of, a digest of this snapshot of data is signed with the public encryption key so as to enforce non-repudiation.
-
-Another use case is to grab raw data such that it could be merged into a report template or communication.
-
-The service offers a basic API to create a snapshot of a single object, and an more flexible API that allows the size of the graph to be customized.
-
-The core framework provides an implementation of this service (`o.a.i.core.runtime.services.xmlsnapshot.XmlSnapshotServiceDefault`).
-
-
-
-== Standard API
-
-The (basic) API of `XmlSnapshotService` is:
-
-[source]
-----
-public interface XmlSnapshotService {
- public interface Snapshot {
- Document getXmlDocument();
- Document getXsdDocument();
- String getXmlDocumentAsString();
- String getXsdDocumentAsString();
- }
- @Programmatic
- public XmlSnapshotService.Snapshot snapshotFor(Object domainObject);
- ...
-}
-----
-
-
-The most straight-forward usage of this service is simply:
-
-[source,java]
-----
-XmlSnapshot snapshot = xmlsnapshotService.snapshotFor(customer);
-Element customerAsXml = snapshot.getXmlElement();
-----
-
-This will return an XML (document) element that contains the names and values of each of the customer's value properties, along with the titles of reference properties, and also the number of items in collections.
-
-
-As well as obtaining the XML snapshot, it is also possible to obtain an XSD schema that the XML snapshot conforms to.
-
-[source]
-----
-XmlSnapshot snapshot = ...;
-Element customerAsXml = snapshot.getXmlElement();
-Element customerXsd = snapshot.getXsdElement();
-----
-
-This can be useful for some tools. For example, link:http://www.altova.com/stylevision.html[Altova Stylevision] can use the XML and XSD to transform into reports. Please note that this link does not imply endorsement (nor even a recommendation that this is a good design).
-
-
-
-
-
-== Builder API
-
-The contents of the snapshot can be adjusted by including "paths" to other references or collections. To do this, the
-builder is used. The API for this is:
-
-[source,java]
-----
-public interface XmlSnapshotService {
- ...
- public interface Builder {
- void includePath(final String path);
- void includePathAndAnnotation(String path, String annotation);
- XmlSnapshotService.Snapshot build();
- }
- @Programmatic
- public XmlSnapshotService.Builder builderFor(Object domainObject);
-}
-----
-
-We start by obtaining a builder:
-
-[source,java]
-----
-XmlSnapshot.Builder builder = xmlsnapshotService.builderFor(customer);
-----
-
-Suppose now that we want the snapshot to also include details of the customer's address, where `address` in this case is a reference property to an instance of the `Address` class. We can "walk-the-graph" by including these references within the builder.
-
-[source,java]
-----
-builder.includePath("address");
-----
-
-We could then go further and include details of every order in the customer's `orders` collection, and details of every
-product of every order:
-
-[source,java]
-----
-builder.includePath("orders/product");
-----
-
-When all paths are included, then the builder can build the snapshot:
-
-[source,java]
-----
-XmlSnapshot snapshot = builder.build();
-Element customerAsXml = snapshot.getXmlElement();
-----
-
-All of this can be strung together in a fluent API:
-
-[source,java]
-----
-Element customerAsXml = xmlsnapshotService.builderFor(customer)
- .includePath("address")
- .includePath("orders/product")
- .build()
- .getXmlElement();
-----
-
-
-As you might imagine, the resultant XML document can get quite large very quickly with only a few "include"s.
-
-
-[NOTE]
-====
-If an XSD schema is beng generated (using `snapshot.getXsdElement()` then note that for the XSD to be correct, the object being snapshotted must have non-null values for the paths that are `include()`'d. If this isn't done then the XSD will not be correct reflect for another snapshotted object that does have non-null values.
-====
-
-
-
-
-== Automatic inclusions
-
-If the domain object being snapshotted implements the `SnapshottableWithInclusions` interace, then this moves the
-responsibility for determining what is included within the snapshot from the caller to the snapshottable object itself:
-
-[source]
-----
-public interface SnapshottableWithInclusions extends Snapshottable {
- List<String> snapshotInclusions();
-}
-----
-
-If necessary, both approaches can be combined.
-
-
-[TIP]
-====
-As an alternative to using `include()`, you might consider building a view model domain object which can reference only the relevant information required for the snapshot. For example, if only the 5 most recent Orders for a Customer were required, a `CustomerAndRecentOrders` view model could hold a collection of just those 5 ``Order``s. Typically such view models would implement `SnapshottableWithInclusions`.
-
-One reason for doing this is to provide a stable API between the domain model and whatever it is that might be consuming the XML. With a view model you can refactor the domain entities but still preserve a view model such that the XML is the same.
-====
-
-
-
-== Convenience API
-
-The `XmlSnapshotService` also provides some API for simply manipulating XML:
-
-[source]
-----
-public interface XmlSnapshotService {
- ...
- @Programmatic
- public Document asDocument(String xmlStr); // <1>
- @Programmatic
- public <T> T getChildElementValue( // <2>
- Element el, String tagname, Class<T> expectedCls);
- @Programmatic
- public Element getChildElement( // <3>
- Element el, String tagname);
- @Programmatic
- public String getChildTextValue(Element el); // <4>
-}
-----
-<1> is a convenience method to convert xml string back into a W3C Document
-<2> is a convenience method to extract the value of an XML element, based on its type.
-<3> is a convenience method to walk XML document.
-<4> is a convenience method to obtain value of child text node.
-
-
-
-
-
-
-
-== Registering the Service
-
-Assuming that the `configuration-and-annotation` services installer is configured (implicit if using the
-`AppManifest` to xref:rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' core
-implementation of `XmlSnapshotService` 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.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
-in the xref:rgsvc.adoc#__rgsvc_intro_overriding-the-services[introduction] to this guide).
-
-
-
-== Related Services
-
-The xref:rgsvc.adoc#_rgsvc_api_BookmarkService[`BookmarkService`] provides a mechanism for obtaining a string representations of a single domain object.
-
-The xref:rgsvc.adoc#_rgsvc_api_MementoService[`MementoService`] also provides a mechanism for generating string representations of domain objects.
-
-The xref:rgsvc.adoc#_rgsvc_api_JaxbService[`JaxbService`] is a simple wrapper around
-standard JAXB functionality for generating both XMLs and XSDs from JAXB-annotated classes. Note that there is built-in support for JAXB classes (ie annotated with
-xref:rgant.adoc#_rgant-XmlRootElement[`@XmlRootElement`]) to be used as view models.
-
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/_rgsvc_application-layer-api.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_application-layer-api.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc_application-layer-api.adoc
deleted file mode 100644
index c33b7fc..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_application-layer-api.adoc
+++ /dev/null
@@ -1,159 +0,0 @@
-[[_rgsvc_application-layer-api]]
-= Application Layer 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/
-
-
-
-Domain service APIs for the application layer allow the domain objects to control aspects of the application layer, such as sending info messages back to the end-user.
-
-
-The table below summarizes the application layer APIs defined by Apache Isis. It also lists their corresponding implementation, either a default implementation provided by Apache Isis itself, or provided by one of the in (non-ASF) link:http://www.isisaddons.org[Isis Addons] modules.
-
-.Application Layer API
-[cols="2,4a,1,1", options="header"]
-|===
-
-|API
-|Description
-|Implementation
-|Notes
-
-|xref:rgsvc.adoc#_rgsvc_api_AcceptHeaderService[`o.a.i.applib.` +
-`services.acceptheader` +
-`AcceptHeaderService`]
-|Request-scoped access to HTTP Accept headers.
-|`AcceptHeaderServiceDefault` +
-``o.a.i.core`` +
-``isis-viewer-restfulobjects-rendering``
-|Populated only when the domain objects are accessed using the xref:ugvro.adoc#[Restful Objects viewer].
-
-
-|xref:rgsvc.adoc#_rgsvc_api_ActionInvocationContext[`o.a.i.applib.` +
-`services.actinv` +
-`ActionInvocation-` +
-`Context`]
-|Request-scoped access to whether action is invoked on object and/or on collection of objects
-|`ActionInvocationContext` +
-``o.a.i.core`` +
-``isis-core-applib``
-|API is also concrete class
-
-
-
-|xref:rgsvc.adoc#_rgsvc_api_BackgroundService[`o.a.i.applib.` +
-`services.background` +
-`BackgroundService`]
-|Programmatic persistence of commands to be persisted (so can be executed by a background mechanism, eg scheduler)
-|`BackgroundServiceDefault` +
-``o.a.i.core`` +
-``isis-core-runtime``
-|depends on: +
-xref:rgsvc.adoc#_rgsvc_spi_BackgroundCommandService[`BackgroundCommand-Service`]
-
-
-|xref:rgsvc.adoc#_rgsvc_api_CommandContext[`o.a.i.applib.` +
-`services.command` +
-`CommandContext`]
-|Request-scoped access to capture the users's __intention__ to invoke an action or to edit a property.
-|`CommandContext` +
-``o.a.i.core`` +
-``isis-core-applib``
-|API is also a concrete class. +
-depends on: +
-xref:rgsvc.adoc#_rgsvc_spi_CommandService[`CommandService`] for persistent `Command`, else in-memory impl. used.
-
-The xref:rgsvc.adoc#_rgsvc_api_InteractionContext[`InteractionContext`] manages the actual execution of the command.
-
-
-|xref:rgsvc.adoc#_rgsvc_api_InteractionContext[`o.a.i.applib.` +
-`services.iactn` +
-`InteractionContext`]
-|Request-scoped access to the current member execution (action invocation or property edit),
-represented as the `Interaction` context.
-|`InteractionContext` +
-``o.a.i.core`` +
-``isis-core-applib``
-|API is also a concrete class.
-
-
-
-|xref:rgsvc.adoc#_rgsvc_api_MessageService[`o.a.i.applib.` +
-`services.message` +
-`MessageService`]
-|Methods to inform or warn the user, or to raise errors.
-|`FactoryService-` +
-``Default`` +
-``o.a.i.core`` +
-``isis-core-metamodel``
-|Supercedes methods in xref:rgsvc.adoc#_rgsvc_api_DomainObjectContainer[`DomainObjectContainer`].
-
-
-|xref:rgsvc.adoc#_rgsvc_api_SessionManagementService[`o.a.i.applib.` +
-`services.sessmgmt` +
-`SessionManagementService`]
-|Methods for batching long-running work (eg data migration) into multiple sessions.
-|`SessionManagementService-` +
-``Default`` +
-``o.a.i.core`` +
-``isis-core-runtime``
-|
-
-
-|xref:rgsvc.adoc#_rgsvc_api_TitleService[`o.a.i.applib.` +
-`services.title` +
-`TitleService`]
-|Methods to programmatically obtain the title or icon of a domain object.
-|`TitleService-` +
-``Default`` +
-``o.a.i.core`` +
-``isis-core-metamodel``
-|Supercedes methods in xref:rgsvc.adoc#_rgsvc_api_DomainObjectContainer[`DomainObjectContainer`].
-
-
-
-|xref:rgsvc.adoc#_rgsvc_api_TransactionService[`o.a.i.applib.` +
-`services.xactn` +
-`TransactionService`]
-|Methods for managing transactions.
-|`TransactionService-` +
-``Default`` +
-``o.a.i.core`` +
-``isis-core-metamodel``
-|Supercedes methods in xref:rgsvc.adoc#_rgsvc_api_DomainObjectContainer[`DomainObjectContainer`].
-
-
-
-|xref:rgsvc.adoc#_rgsvc_api_WrapperFactory[`o.a.i.applib.` +
-`services.wrapper` +
-`WrapperFactory`]
-|Interact with another domain object "as if" through the UI (enforcing business rules, firing domain events)
-|`WrapperFactoryDefault` +
-``o.a.i.core`` +
-``isis-core-wrapper``
-|
-
-
-
-|===
-
-Key:
-
-* `o.a.i` is an abbreviation for `org.apache.isis`
-* `o.ia.m` is an abbreviation for `org.isisaddons.module`
-* `o.a.i.c.m.s` is an abbreviation for `org.apache.isis.core.metamodel.services`
-* `o.a.i.c.r.s` is an abbreviation for `org.apache.isis.core.runtime.services`
-
-
-
-include::_rgsvc_api_AcceptHeaderService.adoc[leveloffset=+1]
-include::_rgsvc_api_ActionInvocationContext.adoc[leveloffset=+1]
-include::_rgsvc_api_BackgroundService.adoc[leveloffset=+1]
-include::_rgsvc_api_CommandContext.adoc[leveloffset=+1]
-include::_rgsvc_api_InteractionContext.adoc[leveloffset=+1]
-include::_rgsvc_api_MessageService.adoc[leveloffset=+1]
-include::_rgsvc_api_SessionManagementService.adoc[leveloffset=+1]
-include::_rgsvc_api_TitleService.adoc[leveloffset=+1]
-include::_rgsvc_api_TransactionService.adoc[leveloffset=+1]
-include::_rgsvc_api_WrapperFactory.adoc[leveloffset=+1]