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:08 UTC
[32/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/_rgfis_spi_InteractionDtoServiceInternal.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgfis_spi_InteractionDtoServiceInternal.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgfis_spi_InteractionDtoServiceInternal.adoc
deleted file mode 100644
index 643514a..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgfis_spi_InteractionDtoServiceInternal.adoc
+++ /dev/null
@@ -1,44 +0,0 @@
-[[_rgfis_spi_InteractionDtoServiceInternal]]
-= `InteractionDtoServiceInternal`
-: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 `InteractionDtoServiceInternal` internal domain service is used by the framework to create and update DTOs representing member executions, ie the invocation of an action or the editing of a property. The DTO is in all cases a subclass of `MemberExecutionDto`, from the xref:rgcms.adoc#_rgcms_schema-ixn["ixn" schema], and subsequently accessible from the `Interaction` object (per the xref:rgsvc.adoc#_rgsvc_api_InteractionContext[`InteractionContext`] service).
-
-
-== SPI & Implementation
-
-The SPI of the service is:
-
-[source,java]
-----
-public interface InteractionDtoServiceInternal {
- ActionInvocationDto asActionInvocationDto( // <1>
- ObjectAction objectAction,
- ObjectAdapter targetAdapter,
- List<ObjectAdapter> argumentAdapters);
- PropertyEditDto asPropertyEditDto( // <2>
- OneToOneAssociation property,
- ObjectAdapter targetAdapter,
- ObjectAdapter newValueAdapterIfAny);
- ActionInvocationDto updateResult( // <3>
- ActionInvocationDto actionInvocationDto,
- ObjectAction objectAction,
- Object resultPojo);
-}
-----
-<1> called by the framework when invoking an action, to create a DTO capturing the details of the action invocation (target, arguments etc).
-<2> called by the framework when editing a property, to create a DTO (for the xref:rgcms.adoc#_rgcms_schema-ixn["ixn" schema]) capturing the details of the property edit (target, new value etc).
-<3> called by the framework to attach the result of an action invocation to the aforementioned DTO.
-
-The service is implemented by `o.a.i.core.runtime.services.ixn.InteractionDtoServiceInternalDefault`.
-
-
-== Related Services
-
-The design of this service is similar to that of
-xref:rgfis.adoc#_rgfis_spi_CommandDtoServiceInternal[`CommandDtoServiceInternal`], used to create the `CommandDto`
-(from the xref:rgcms.adoc#_rgcms_schema-cmd["cmd" schema]).
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/_rgfis_spi_MessageBrokerServiceInternal.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgfis_spi_MessageBrokerServiceInternal.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgfis_spi_MessageBrokerServiceInternal.adoc
deleted file mode 100644
index 67b78be..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgfis_spi_MessageBrokerServiceInternal.adoc
+++ /dev/null
@@ -1,44 +0,0 @@
-[[_rgfis_spi_MessageBrokerServiceInternal]]
-= `MessageBrokerServiceInternal`
-: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 (internal) `MessageBrokerServiceInternal` domain service is a wrapper around
-xref:rgsvc.adoc#_rgsvc_api_MessageService[`MessageService`].
-
-
-[NOTE]
-====
-The service does not provide any additional capabilities over and those of `MessageService`, and will (most likely) be
-conflated with that service in the future.
-====
-
-
-
-
-
-== SPI
-
-The SPI of the service is:
-
-[source,java]
-----
-public interface MessageBrokerServiceInternal {
- void informUser(String message);
- void warnUser(String message);
- void raiseError(String message);
-}
-----
-
-
-== Runtime vs Noop implementation
-
-The framework provides two implementations:
-
-* `MessageBrokerServiceInternalDefault` is provided by `isis-core-runtime`, and is used during normal use and integration tests
-
-* `MessageBrokerServiceInternalNoop` is provided as a fallback by `isis-core-metamodel`, and is provided to allow the xref:rgmvn.adoc[maven plugin] to be bootstrapped without any "backend" database.
-
-The `...Default` implementation takes priority over the `...Noop` implementation.
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/_rgfis_spi_PersistenceSessionServiceInternal.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgfis_spi_PersistenceSessionServiceInternal.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgfis_spi_PersistenceSessionServiceInternal.adoc
deleted file mode 100644
index bb89ade..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgfis_spi_PersistenceSessionServiceInternal.adoc
+++ /dev/null
@@ -1,96 +0,0 @@
-[[_rgfis_spi_PersistenceSessionServiceInternal]]
-= `PersistenceSessionServiceInternal`
-: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 (internal) `PersistenceSessionServiceInternal` domain service acts as a facade to the underlying JDO persistence session / database connection. As such it provides methods for querying and for persisting objects.
-
-[NOTE]
-====
-The default implementation of this service is not (as of `1.13.0`) request-scoped, however all of the methods delegate
-to the `PersistenceSession` of the current `IsisSession` - obtained from the thread-local of `IsisSessionFactory` singleton service.
-So, in effect the service does act as if it is request scoped.
-====
-
-
-
-== SPI
-
-The SPI of the service is a hierarchy of types. First is `AdapterManagerBase`:
-
-[source,java]
-----
-public interface AdapterManagerBase {
- ObjectAdapter getAdapterFor(Object pojo); // <1>
- ObjectAdapter adapterFor(Object domainObject); // <2>
-----
-<1> Gets the `ObjectAdapter` for the specified domain object if it exists in the identity map, else returns `null`.
-<2> Looks up or creates a standalone (value) or root adapter.
-
-The `AdapterManager` is the immediate subtype:
-
-[source,java]
-----
-public interface AdapterManager extends AdapterManagerBase {
- ObjectAdapter getAdapterFor(Object pojo); // <1>
- ObjectAdapter adapterFor( // <2>
- Object pojo, ObjectAdapter parentAdapter,
- OneToManyAssociation collection);
- ObjectAdapter mapRecreatedPojo(Oid oid, Object recreatedPojo); // <3>
- void removeAdapter(ObjectAdapter adapter); // <4>
-}
-----
-<1> Gets the `ObjectAdapter` for the `Oid` if it exists in the identity map.
-<2> Looks up or creates a collection adapter.
-<3> Enable RecreatableObjectFacet to 'temporarily' map an existing pojo to an oid.
-<4> Enable RecreatableObjectFacet to remove a 'temporarily' mapped an adapter for a pojo.
-
-
-Finally, `PersistenceSessionServiceInternal` is a subtype of `AdapterManager`:
-
-[source,java]
-----
-public interface PersistenceSessionServiceInternal extends AdapterManager {
-
- // instantiate
- ObjectAdapter createTransientInstance(
- ObjectSpecification spec);
- ObjectAdapter createViewModelInstance(
- ObjectSpecification spec, String memento);
-
- // retrieve
- void resolve(Object parent);
- @Deprecated
- void resolve(Object parent, Object field);
- Object lookup(Bookmark bookmark, final BookmarkService2.FieldResetPolicy fieldResetPolicy);
- Bookmark bookmarkFor(Object domainObject);
- Bookmark bookmarkFor(Class<?> cls, String identifier);
-
- // beginTran, flush, commit, currentTransaction
- void beginTran();
- boolean flush();
- void commit();
- Transaction currentTransaction();
- void executeWithinTransaction(TransactionalClosure transactionalClosure);
-
- // makePersistent, remove
- void makePersistent(ObjectAdapter adapter);
- void remove(ObjectAdapter adapter);
- // allMatchingQuery, firstMatchingQuery
- <T> List<ObjectAdapter> allMatchingQuery(Query<T> query);
- <T> ObjectAdapter firstMatchingQuery(Query<T> query);
-}
-----
-
-
-== Runtime vs Noop implementation
-
-The framework provides two implementations:
-
-* `PersistenceSessionServiceInternalDefault` is provided by `isis-core-runtime`, and is used during normal use and integration tests
-
-* `PersistenceSessionServiceInternalNoop` is provided as a fallback by `isis-core-metamodel`, and is provided to allow the xref:rgmvn.adoc[maven plugin] to be bootstrapped without any "backend" database.
-
-The `...Default` implementation takes priority over the `...Noop` implementation.
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/_rgfis_spi_PublishingServiceInternal.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgfis_spi_PublishingServiceInternal.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgfis_spi_PublishingServiceInternal.adoc
deleted file mode 100644
index 9dd56aa..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgfis_spi_PublishingServiceInternal.adoc
+++ /dev/null
@@ -1,76 +0,0 @@
-[[_rgfis_spi_PublishingServiceInternal]]
-= `PublishingServiceInternal`
-: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 (internal) `PublishingServiceInternal` domain service acts as an internal facade to any
-configured xref:rgsvc.adoc#_rgsvc_spi_PublisherService[`PublisherService`] or (deprecated)
-xref:rgsvc.adoc#_rgsvc_spi_PublishingService[`PublishingService`] domain services.
-
-For published action invocations/ property edits, it provides an API for those member executions to call.
-
-For published objects, it provides an API for the framework to call at the end of the interaction; it obtains details
-of the changed objects (from the
-xref:rgfis.adoc#_rgfis_spi_ChangedObjectsServiceInternal[`ChangedObjectsServiceInternal`]) and filters them to just
-those objects that are to be published; these are then passed through to any configured `PublisherService` or
-`PublishingService` implementations.
-
-
-
-== SPI and Implementation
-
-The SPI of the service is:
-
-[source,java]
-----
-public class PublishingServiceInternal {
- void publishAction(
- Interaction.Execution execution, // <1>
- ObjectAction objectAction, // <2>
- IdentifiedHolder identifiedHolder,
- ObjectAdapter targetAdapter,
- List<ObjectAdapter> parameterAdapters,
- ObjectAdapter resultAdapter);
- void publishProperty( // <3>
- Interaction.Execution execution);
- void publishObjects(); // <4>
-}
-----
-<1> to publish an action invocation, as represented by the specified member `Execution` parameter and with the
-xref:rgant.adoc#_rgant-Action_publishing[`@Action#publishing()`] annotation attribute or equivalent, to any configured
-xref:rgsvc.adoc#_rgsvc_spi_PublisherService[`PublisherService`]. The `Execution` object will be an instance of
-`ActionInvocation` (see xref:rgsvc.adoc#_rgsvc_api_InteractionContext[`InteractionContext`] for details).
-<2> the remaining parameters are to support the publishing of the action to any configured
-xref:rgsvc.adoc#_rgsvc_spi_PublishingService[`PublishingService`] services (deprecated).
-<3> to publish a property edit, as as represented by the specified member `Execution` parameter and with the
-xref:rgant.adoc#_rgant-Property_publishing[`@Property#publishing()`] annotation attribute or equivalent, to any
-configured xref:rgsvc.adoc#_rgsvc_spi_PublisherService[`PublisherService`]. The `Execution` object will be an instance
-of `PropertyEdit` (see xref:rgsvc.adoc#_rgsvc_api_InteractionContext[`InteractionContext`] for details).
-<4> to publish all changed objects that are to be published (with the
-xref:rgant.adoc#_rgant-DomainObject_publishing[`@DomainObject#publishing()`] annotation attribute or equivalent).
-
-
-The service implementation is `o.a.i.c.m.s.publishing.PublishingServiceInternal`.
-
-
-
-== 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' default
-implementation of `PublishingServiceInternal` class is automatically registered (it is annotated with `@DomainService`)
-so no further configuration is required.
-
-
-== Related Classes
-
-The service delegates between the (internal)
-xref:rgfis.adoc#_rgfis_spi_ChangedObjectsServiceInternal[`ChangedObjectsServiceInternal`] domain service to the
-configured xref:rgsvc.adoc#_rgsvc_spi_PublisherService[`PublisherService`] and
- xref:rgsvc.adoc#_rgsvc_spi_PublishingService[`PublishingService`].
-
-The (internal) xref:rgfis.adoc#_rgfis_spi_AuditingServiceInternal[`AuditingServiceInternal`] performs a similar
-function for the xref:rgsvc.adoc#_rgsvc_spi_PublisherService[`PublisherService`], also collating details of the
-changed objects from `ChangedObjectsServiceInternal`.
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/_rgfis_spi_RepresentationService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgfis_spi_RepresentationService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgfis_spi_RepresentationService.adoc
deleted file mode 100644
index 4c27dad..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgfis_spi_RepresentationService.adoc
+++ /dev/null
@@ -1,95 +0,0 @@
-[[_rgfis_spi_RepresentationService]]
-= `RepresentationService`
-: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 `RepresentationService` is the main plug-in point for the xref:ugvro.adoc#[RestfulObjects viewer] to generate representations.
-
-The default implementation generates representations according to the link:http://restfulobjects.org[Restful Objects spec] v1.0. However, it also delegates to the xref:rgfis.adoc#_rgfis_spi_ContentNegotiationService[`ContentNegotiationService`] which provides a mechanism for altering representations according to the HTTP `Accept` header.
-
-The principal motivation is to allow more flexible representations to be generated for REST clients that (perhaps through their use of a certain Javascript library, say) expect, or at least works best with, a certain style of representation.
-
-In all there are three domain services that can influence the representations generated: this service, xref:rgfis.adoc#_rgfis_spi_ContentNegotiationService[`ContentNegotiationService`]and the xref:rgsvc.adoc#_rgsvc_spi_ContentMappingService[`ContentMappingService`]. The diagram below shows how these collaborate:
-
-image::{_imagesdir}reference-services-spi/RepresentationService/service-collaborations.png[width="700px",link="{_imagesdir}reference-services-spi/RepresentationService/service-collaborations.png"]
-
-The `RepresentationServiceForRestfulObjects` is the default implementation of this service; likewise `ContentNegotiationServiceXRoDomainType` is the default implementation of the `ContentNegotiationService`. If you inspect the source code you'll see that the default implementation of this service's primary responsibility is to generate the default Restful Objects representations. Therefore, if you what you want to do is to generate a _different _representation then in many cases replacing either this service _or_ the `ContentNegotiationService` will be equivalent (you'll notice that their SPIs are very similar).
-
-
-== SPI
-
-The SPI defined by this service is:
-
-[source,java]
-----
-public interface RepresentationService {
- Response objectRepresentation( // <1>
- Context rendererContext,
- ObjectAdapter objectAdapter);
- Response propertyDetails( // <2>
- Context rendererContext,
- ObjectAndProperty objectAndProperty,
- MemberReprMode memberReprMode);
- Response collectionDetails( // <3>
- Context rendererContext,
- ObjectAndCollection objectAndCollection,
- MemberReprMode memberReprMode);
- Response actionPrompt( // <4>
- Context rendererContext,
- ObjectAndAction objectAndAction);
- Response actionResult( // <5>
- Context rendererContext,
- ObjectAndActionInvocation objectAndActionInvocation,
- ActionResultReprRenderer.SelfLink selfLink);
- public static interface Context extends RendererContext {
- ObjectAdapterLinkTo getAdapterLinkTo();
- }
-}
-----
-<1> representation of a single object, as per section 14.4 of the RO spec, v1.0
-<2> representation of a single property of an object, as per section 16.4 of the RO spec v1.0
-<3> representation of a single collection of an object, as per section 17.5 of the RO spec v1.0
-<4> representation of a single action (prompt) of an object, as per section 18.2 of the RO spec v1.0
-<5> representation of the results of a single action invocation, as per section 19.5 of the RO spec v1.0
-
-These methods provide:
-
-* a `RendererContext` which provides access to request-specific context (eg HTTP headers), session-specific context (eg authentication) and global context (eg configuration settings)
-
-* an object representing the information to be rendered +
-+
-eg `ObjectAdapter`, `ObjectAndProperty`, `ObjectAndCollection` etc
-
-* for members, whether the representation is in read/write mode +
-+
-ie `MemberReprMode`
-
-
-
-
-
-
-== Implementation
-
-As discussed in the introduction, the framework provides a default implementation, `o.a.i.v.ro.rendering.service.RepresentationServiceContentNegotiator`. This delegates to xref:rgfis.adoc#_rgfis_spi_ContentNegotiationService[`ContentNegotiationService`] to generate an alternative representation; but if none is provided then it falls back on generating the representations as defined in the link:http://restfulobjects.org[Restful Objects spec] v1.0.
-
-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).
-
-
-== Registering the Services
-
-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' default implementation of `RepresentationService` service is automatically registered and injected (it is annotated with `@DomainService`) so no further configuration is required.
-
-
-
-
-== Related Services
-
-The default implementation delegates to xref:rgfis.adoc#_rgfis_spi_ContentNegotiationService[`ContentNegotiationService`], whose default implementation may delegate in turn to xref:rgsvc.adoc#_rgsvc_spi_ContentMappingService[`ContentMappingService`] (if present).
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/_rgfis_spi_TransactionStateProviderInternal.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgfis_spi_TransactionStateProviderInternal.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgfis_spi_TransactionStateProviderInternal.adoc
deleted file mode 100644
index 2f0491c..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgfis_spi_TransactionStateProviderInternal.adoc
+++ /dev/null
@@ -1,38 +0,0 @@
-[[_rgfis_spi_TransactionStateProviderInternal]]
-= `TransactionStateProviderInternal`
-: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 (internal) `TransactionStateProviderInternal` domain service simply provides the ability to check as to the
-state of the current transaction.
-
-[NOTE]
-====
-The service will probably be combined with xref:rgsvc.adoc#_rgsvc_api_TransactionService[`TransactionService`]
-in the future.
-====
-
-
-== SPI and Implementation
-
-The SPI of the service is simply:
-
-[source,java]
-----
-public interface TransactionStateProviderInternal {
- TransactionState getTransactionState();
-}
-----
-
-
-== Runtime vs Noop implementation
-
-The framework provides two implementations:
-
-* `TransactionStateProviderInternalDefault` is provided by `isis-core-runtime`, and is used during normal use and integration tests
-
-* `TransactionStateProviderInternalNoop` is provided as a fallback by `isis-core-metamodel`, and is provided to allow the xref:rgmvn.adoc[maven plugin] to be bootstrapped without any "backend" database.
-
-The `...Default` implementation takes priority over the `...Noop` implementation.
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/_rgmvn_intro.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgmvn_intro.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgmvn_intro.adoc
deleted file mode 100644
index 32bc0ce..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgmvn_intro.adoc
+++ /dev/null
@@ -1,93 +0,0 @@
-[[_rgmvn_intro]]
-= Introduction
-: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/
-:toc: right
-
-The Apache Isis Maven plugin defines three goals:
-
-* `validate` +
-+
-Use to verify at build time that the metamodel of an application is valid. This runs the `MetaModelValidator` that is also run when the application is started up.
-
-* `swagger` +
-+
-Uses the xref:rgsvc.adoc#_rgsvc_api_SwaggerService[`SwaggerService`] to generate link:http://swagger.io[Swagger] spec files that describe the public and/or private RESTful APIs exposed by the xref:ugvro.adoc#[RestfulObjects viewer].
-
-* `xsd` +
-+
-Uses the xref:rgsvc.adoc#_rgsvc_api_JaxbService[`JaxbService`] to generate XSD schemas from any JAXB-annotated view models/DTOs. +
-+
-This is instead of and preferable to using the JAXB link:https://jaxb.java.net/2.2.4/docs/schemagen.html[schemagen] tool, because it uses the framework's support (via xref:rgant.adoc#_rgant-XmlJavaTypeAdapter[`@XmlJavaTypeAdapter`]) to translate any references to domain objects into ``OidDto``s (as defined by the Apache Isis xref:rgcms.adoc#_rgcms_schema-common[common schema]).
-
-The `validate` goal is by default bound to the `test` phase, and the `swagger` goal is by default bound to the `package` phase; both are typically of your application's `dom` sub-module. The `xsd` goal meanwhile defaults to the `generate-resources` phase, and this is generally used in a completely separate sub-module. An example can be found in the (non-ASF) http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp] example app; the separate submodule that uses the `xsd` goal is (also) called `todoapp-xsd`.
-
-All of these goals require an xref:rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[`AppManifest`] to point the plugin at, so that
-it knows how to bootstrap an Isis runtime. This is discussed below, followed by sections on configuring the two goals.
-
-
-
-[[__rgmvn_intro_app-manifest]]
-== `AppManifest`
-
-As noted in the introduction, all the goals require an xref:rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[`AppManifest`]
-to point the plugin at, so that it knows how to bootstrap an Isis runtime.
-
-This can be extremely minimal; it isn't necessary to use the main `AppManifest` (in the `app` module) used to
-bootstrap the application, you can instead use a cut-down one. This then allows the plugins to be run during the
-build of the `dom` module, rather than having to run in the context of the `integtest` module.
-
-For example, the xref:ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp]'s
-manifest is:
-
-[source,java]
-----
-package domainapp.dom;
-...
-public class DomainAppDomManifest implements AppManifest {
- @Override
- public List<Class<?>> getModules() {
- return Arrays.asList(
- DomainAppDomainModule.class // domain (entities and repositories)
- );
- }
- @Override
- public List<Class<?>> getAdditionalServices() { return Collections.emptyList(); }
- @Override
- public String getAuthenticationMechanism() { return null; }
- @Override
- public String getAuthorizationMechanism() { return null; }
- @Override
- public List<Class<? extends FixtureScript>> getFixtures() { return null; }
- @Override
- public Map<String, String> getConfigurationProperties() { return null; }
-}
-----
-
-where `DomainAppDomainModule` simply identifies the package for the manifest to search under:
-
-[source,java]
-----
-package domainapp.dom;
-public final class DomainAppDomainModule { }
-----
-
-
-The downside of using a minimal `AppManifest` in the ``dom`` module is that any contributed actions/associations will
-be ignored.
-
-We recommend the following:
-
-* run the `validate` goal in the `dom` submodule; this will give early warning if there are any syntactic errors in the
- model, eg orphaned supporting methods
-
-* run the `swagger` goal in the `integtest` submodule; this ensures that the generated Swagger spec files correctly
- include any contributed actions/associations.
-
-* run the `xsd` plugin in a new `xsd` submodule; contributed actions are irrelevant for this particular goal; having a
-separate submodule allows the configuration of both the `xsd` goal (to generate the XSD schemas) and any other XSD-related configuration to be kept in a single place.
-
-The xref:ug.adoc#_ug_getting-started_simpleapp-archetype[SimpleApp archetype] reflects these recommendations for
-the `validate` and `swagger` goals. You can find an example of the `xsd` plugin in the (non-ASF) http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp] application.
-
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/_rgmvn_swagger.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgmvn_swagger.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgmvn_swagger.adoc
deleted file mode 100644
index 7c5ee80..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgmvn_swagger.adoc
+++ /dev/null
@@ -1,107 +0,0 @@
-[[_rgmvn_swagger]]
-= `swagger` goal
-: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/
-:toc: right
-
-
-The `swagger` goal of the `isis-maven-plugin` uses the xref:rgsvc.adoc#_rgsvc_api_SwaggerService[`SwaggerService`] to
-generate 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, once generated, can then be used in the build pipeline to generate client-side stubs, typically using Swagger's own link:https://github.com/swagger-api/swagger-codegen/tree/master/modules/swagger-codegen-maven-plugin[swagger-codegen-maven] plugin.
-
-
-The `swagger` goal defines the following properties:
-
-* `appManifest` - fully qualified class name for the app manifest used to bootstrap the application (see discussion above)
-
-* `fileNamePrefix` - (optional) a prefix to the generated file names (is suffixed by the requested visibilities, see below). +
-+
-Defaults to `swagger`.
-
-* `visibilities` - (optional) list of required visibilities. +
-+
-Defaults to [`PUBLIC`, `PRIVATE`] (meaning that two spec files will be created).
-
-* `format` - (optional) which format to generate, either `JSON` or `YAML`. +
-+
-Defaults to `JSON`.
-
-* `output` - (optional) subdirectory under the `target` directory to generate the swagger spec files +
-+
-Defaults to `generated-resources/isis-swagger`
-
-
-== `integtest` submodule
-
-Update the `pom.xml` (in your project's `integtest` module):
-
-[source,xml]
-----
-<profile>
- <id>isis-swagger</id>
- <activation>
- <property>
- <name>!skip.isis-swagger</name> <!--1-->
- </property>
- </activation>
- <build>
- <plugins>
- <plugin>
- <groupId>org.apache.isis.tool</groupId>
- <artifactId>isis-maven-plugin</artifactId>
- <version>${isis.version}</version> <!--2-->
- <configuration>
- <appManifest>domainapp.app.DomainAppAppManifest</appManifest> <!--3-->
- <visibilities> <!--4-->
- <visibility>PUBLIC</visibility>
- <visibility>PRIVATE</visibility>
- </visibilities>
- <format>JSON</format> <!--5-->
- <fileNamePrefix>swagger</fileNamePrefix> <!--5-->
- </configuration>
- <dependencies>
- <dependency>
- <groupId>${project.groupId}</groupId>
- <artifactId>simpleapp-dom</artifactId> <!--6-->
- <version>${project.version}</version>
- </dependency>
- <dependency>
- <groupId>com.google.guava</groupId>
- <artifactId>guava</artifactId>
- <version>16.0.1</version>
- </dependency>
- </dependencies>
- <executions>
- <execution>
- <phase>package</phase>
- <goals>
- <goal>swagger</goal> <!--7-->
- </goals>
- </execution>
- </executions>
- </plugin>
- </plugins>
- </build>
-</profile>
-----
-<1> the profile is active by default, though can be disabled using `-Dskip.isis-swagger`
-<2> set to `1.11.0` (or any later version)
-<3> the manifest discussed xref:rgmvn.adoc#_rgmvn_intro_app-manifest[previously]; adjust as required
-<4> the visibilities to create (one swagger spec file per visibility listed)
-<5> which file format to generate the spec files as.
-<6> the `dom` module for the project; adjust as required
-<7> binds the plugin's `swagger` goal to the Maven `package` lifecycle phase (ie the goal will be called when `mvn package` is run).
-
-
-
-
-== To run
-
-The plugin is activated by default, so is run simply using:
-
-[source,bash]
-----
-mvn package
-----
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/_rgmvn_validate.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgmvn_validate.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgmvn_validate.adoc
deleted file mode 100644
index 4f42bfb..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgmvn_validate.adoc
+++ /dev/null
@@ -1,241 +0,0 @@
-[[_rgmvn_validate]]
-= `validate` goal
-: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/
-:toc: right
-
-
-The Apache Isis programming model requires that a number of naming conventions are followed.
-
-For example, the validator will detect any orphaned supporting methods (eg `hideXxx()`) if the corresponding property
-or action has been renamed or deleted but the supporting method was not also updated. Another example is that a class
-cannot have a title specified both using `title()` method and also using `@Title` annotation.
-
-When running the application these are enforced by the `MetaModelValidator` component that detects these errors, failing fast.
-
-The purpose of the `validate` goal of the `isis-maven-plugin` is to enforce these naming conventions at build time,
-typically enforced by way of a continuous integration server.
-
-The `validate` goal defines a single property:
-
-* `appManifest` - fully qualified class name for the app manifest used to bootstrap the application (see discussion above)
-
-The sections below explain how to configure the plugin within an app.
-
-[NOTE]
-====
-The instructions given here relate to `1.10.0`. This goal was also released for `1.9.0`, but with a slightly
-different configuration; see the final section for differences.
-====
-
-
-== `dom` submodule
-
-Update the `pom.xml` (we recommend in your project's `dom` module, and with a xref:rgmvn.adoc#_rgmvn_intro_app-manifest[minimal AppManifest]):
-
-[source,xml]
-----
-<profile>
- <id>isis-validate</id>
- <activation>
- <property>
- <name>!skip.isis-validate</name> <!--1-->
- </property>
- </activation>
- <build>
- <plugins>
- <plugin>
- <groupId>org.apache.isis.tool</groupId>
- <artifactId>isis-maven-plugin</artifactId>
- <version>${isis.version}</version> <!--2-->
- <configuration>
- <appManifest>domainapp.dom.DomainAppDomManifest</appManifest> <!--3-->
- </configuration>
- <dependencies>
- <dependency>
- <groupId>${project.groupId}</groupId>
- <artifactId>simpleapp-dom</artifactId> <!--4-->
- <version>${project.version}</version>
- </dependency>
- <!-- workaround to avoid conflict with plexus-default -->
- <dependency>
- <groupId>com.google.guava</groupId>
- <artifactId>guava</artifactId>
- <version>16.0.1</version>
- </dependency>
- </dependencies>
- <executions>
- <execution>
- <phase>test</phase>
- <goals>
- <goal>validate</goal> <!--5-->
- </goals>
- </execution>
- </executions>
- </plugin>
- </plugins>
- </build>
-</profile>
-----
-<1> the profile is active by default, though can be disabled using `-Dskip.isis-validate`
-<2> set to `1.10.0` (or any later version)
-<3> the manifest discussed xref:rgmvn.adoc#_rgmvn_intro_app-manifest[previously]; adjust as required
-<4> the `dom` module for the project; adjust as required
-<5> binds the plugin's `validate` goal to the Maven `test` lifecycle phase (ie the goal will be called when `mvn test` is run).
-
-
-
-
-== To run
-
-The plugin is activated by default, so is run simply using:
-
-[source,bash]
-----
-mvn test
-----
-
-This will run any tests, and then also - because the plugin is activated by the `isis-validate` property and bound to the `test` phase, will run the plugin's `validate` goal.
-
-
-If for any reason you want to disable the validation, use:
-
-[source,bash]
-----
-mvn test -Dskip.isis-validate
-----
-
-
-
-== Example of failure
-
-In the xref:ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp] application the `SimpleObject` defines an `updateName` action. This has a supporting method:
-
-
-[source,java]
-----
-public SimpleObject updateName( ... ) { ... }
-public String default0UpdateName() { ... }
-----
-
-We can introduce an error by misspelling the supporting method, for example:
-
-[source,java]
-----
-public String default0XUpdateName() { ... }
-----
-
-Running `mvn test` then generates this output:
-
-
-[source,bash]
-----
-[error]
-[error]
-[error]
-[error] domainapp.dom.simple.SimpleObject#default0XUpdateName: has prefix default, is probably a supporting method for a property, collection or action. If the method is intended to be an action, then rename and use @ActionLayout(named="...") or ignore completely using @Programmatic
-[error]
-[error]
-[error]
-[INFO] ------------------------------------------------------------------------
-[INFO] Reactor Summary:
-[INFO]
-[INFO] Simple App ......................................... SUCCESS [ 0.087 s]
-[INFO] Simple App DOM ..................................... FAILURE [ 4.182 s]
-[INFO] Simple App Fixtures ................................ SKIPPED
-[INFO] Simple App Application ............................. SKIPPED
-[INFO] Simple App Integration Tests ....................... SKIPPED
-[INFO] Simple App Webapp .................................. SKIPPED
-[INFO] ------------------------------------------------------------------------
-[INFO] BUILD FAILURE
-[INFO] ------------------------------------------------------------------------
-[INFO] ...
-[ERROR] Failed to execute goal org.apache.isis.tool:isis-maven-plugin:1.13.0:validate (default) on project simpleapp-dom: 1 problems found. -> [Help 1]
-----
-
-If one were to attempt to run the application, the same error would appear in the log files on startup (and the application would not boot).
-
-
-
-
-== Custom validation rules
-
-It is also possible to customize the validation, explained xref:ugbtb.adoc#_ugbtb_programming-model_custom-validator[here]. For example, you could enforce project-specific conventions by implementing a custom `MetaModelValidator`, and registering using a configuration property.
-
-To support this using `AppManifest`s, override its `getConfigurationProperties()` method:
-
-[source,ini]
-----
-public class DomainAppDomManifest implements AppManifest {
- ...
- public Map<String, String> getConfigurationProperties() {
- final Map<String, String> map = Maps.newTreeMap();
- map.put("isis.reflector.validator","com.mycompany.myapp.MyMetaModelValidator");
- return map;
- }
-}
-----
-
-
-== 1.9.0 version
-
-The `1.9.0` version of the plugin requires slightly different configuration. Rather than using an `AppManifest`, instead the configuration directory containing `isis.properties` is specified:
-
-[source,xml]
-----
-<profile>
- <id>isis-validate</id>
- <activation>
- <activeByDefault>false</activeByDefault> <!--1-->
- </activation>
- <build>
- <plugins>
- <plugin>
- <groupId>org.apache.isis.tool</groupId>
- <artifactId>isis-maven-plugin</artifactId>
- <version>1.9.0</version>
- <configuration>
- <isisConfigDir>../webapp/src/main/webapp/WEB-INF</isisConfigDir> <!--2-->
- </configuration>
- <dependencies>
- <dependency>
- <groupId>org.apache.isis.example.application</groupId>
- <artifactId>simpleapp-dom</artifactId>
- <version>1.9.0</version>
- </dependency>
- <!-- workaround to avoid conflict with plexus-default -->
- <dependency>
- <groupId>com.google.guava</groupId>
- <artifactId>guava</artifactId>
- <version>16.0.1</version>
- </dependency>
- </dependencies>
- <executions>
- <execution>
- <phase>test</phase>
- <goals>
- <goal>validate</goal>
- </goals>
- </execution>
- </executions>
- </plugin>
- </plugins>
- </build>
-</profile>
-----
-<1> activated using the `-P` profile flag rather than a `-D` system property
-<2> specify the `isisConfigDir` directory (containing the `isis.properties` file).
-
-To use the `1.9.0` version, use:
-
-[source,bash]
-----
-mvn -P isis-validate test
-----
-
-[NOTE]
-====
-Note that the `isisConfigDir` property was removed in `1.10.0`; only the `AppManifest` approach is supported.
-====
-
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/_rgmvn_xsd.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgmvn_xsd.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgmvn_xsd.adoc
deleted file mode 100644
index 5982bd5..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgmvn_xsd.adoc
+++ /dev/null
@@ -1,333 +0,0 @@
-[[_rgmvn_xsd]]
-= `xsd` goal
-: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/
-:toc: right
-
-
-The `xsd` goal of the `isis-maven-plugin` uses the xref:rgsvc.adoc#_rgsvc_api_JaxbService[`JaxbService`] to
-generate XSD schemas from any JAXB-annotated xref:ugbtb.adoc#_ugbtb_view-models[view model/DTOs].
-
-This is instead of and preferable to using the JAXB link:https://jaxb.java.net/2.2.4/docs/schemagen.html[schemagen]
-tool, because it uses the framework's support (via
-xref:rgant.adoc#_rgant-XmlJavaTypeAdapter[`@XmlJavaTypeAdapter`]) to translate any references to domain
-objects into ``OidDto``s (as defined by the Apache Isis xref:rgcms.adoc#_rgcms_schema-common[common schema]).
-
-The `xsd` goal defines the following properties:
-
-* `appManifest` - fully qualified class name for the app manifest used to bootstrap the application (see discussion above)
-
-* `jaxbClasses` - a list of xref:rg.adoc#_ugbtb_view-models_jaxb[JAXB-annotated view model] classes;
-
-* `output` - (optional) subdirectory under the `target` directory to generate the XSDs +
-+
-Defaults to `generated-resources/isis-xsd`
-
-* `separate` - (optional) whether to create separate directories for each JAXB-class. +
-+
-Defaults to `false`. Most DTO classes will reference one another or the xref:rgcms.adoc#_rgcms_schema-common[common schema]. Normally it's fine to merge all these XSDs together. This property, if set, results in each a separate directory for each generation of its XSD or XSDs.
-
-* `commonSchemas` - (optional) whether to also generate the isis common schema(s). +
-+
-Defaults to `false`; if set then the call to xref:rgsvc.adoc#_rgsvc_api_JaxbService[`JaxbService`] will set `IsisSchemas.INCLUDE` flag.
-
-As a convenience to any (Java) consumers, the XSDs generated from the view models can then in turn be generated
-into DTOs. The original view models and these DTOs are similar but not identical: while the view models can only be used
-within the Isis application (they may reference underlying domain entities) whereas the DTO classes generated from the
-XSDs can be used standalone, eg by a Java subscriber running on an ESB such as Apache Camel.
-
-The rest of this section explains how to configure a new `xsd` submodule that uses the `isis-maven-plugin` along with
-other standard plugins in order to generate both XSDs and DTOs. The `pom.xml` described below uses Maven profiles
-to separate out these two responsibilities.
-
-
-[[__rgmvn_xsd]]
-== `xsd` submodule
-
-We recommend creating a new submodule that will perform the following build steps:
-
-* run the `xsd` goal (in the `generate-resources` phase) to generate the XSDs from the specified view model/DTOs
-
-* use the link:http://maven.apache.org/plugins/maven-assembly-plugin/[maven-assembly-plugin] to bundle the
- generated XSD files into a zip file.
-
-* use the `xjc-gen` to generate corresponding DTO classes from the XSDs. +
-+
-These are _not_ the same as the original view models; they are provided as a convenience for subscribers to marshall XML documents into Java classes, but running as a standalone process (not part of the Isis app)
-
-
-These two main responsibilities can then be placed into separate Maven profiles, for better modularity. The diagram
-below shows the overall design:
-
-image::{_imagesdir}maven-plugin/xsd-goal.png[width="800px",link="{_imagesdir}maven-plugin/xsd-goal.png"]
-
-For example, here is the `pom.xml` file for the (non-ASF)
-http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp] example app's `todoapp-xsd` submodule.
-
-First, the usual boilerplate:
-
-[source,xml]
-----
-<?xml version="1.0" encoding="UTF-8"?>
-<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
- <modelVersion>4.0.0</modelVersion>
-
- <parent>
- <groupId>mleder.analistappb</groupId>
- <artifactId>todoapp</artifactId>
- <version>1.15.0-SNAPSHOT</version>
- </parent>
-
- <artifactId>todoapp-xsd</artifactId>
- <name>Isis Addons ToDoApp XSD</name>
-
- <dependencies>
- <dependency>
- <groupId>${project.groupId}</groupId>
- <artifactId>todoapp-app</artifactId> <!--1-->
- </dependency>
- </dependencies>
-
- <profiles>
- <profile>
- <id>isis-xsd</id> <!--2-->
- ...
- </profile>
- <profile>
- <id>xjc</id> <!--3-->
- ...
- </profile>
- </profiles>
-</project>
-----
-<1> depends on the rest of the application's modules
-<2> XSD generation, to run the `xsd` goal and then assemble into a zip file; within a profile for modularity
-<3> XJC generation, to run the `xjc` to generate Java DTO classes from XSDs; within a profile for modularity
-
-
-
-
-
-
-=== XSD profile
-
-The `isis-xsd` profile runs the `xsd` goal of the `isis-maven-plugin`; these are then zipped up by the assembly plugin:
-
-[source,xml]
-----
-<profile>
- <id>isis-xsd</id>
- <activation>
- <property>
- <name>!skip.isis-xsd</name> <!--1-->
- </property>
- </activation>
- <build>
- <plugins>
- <plugin>
- <groupId>org.apache.isis.tool</groupId>
- <artifactId>isis-maven-plugin</artifactId>
- <version>${isis.version}</version>
- <configuration>
- <appManifest>todoapp.dom.ToDoAppDomManifest</appManifest> <!--2-->
- <jaxbClasses> <!--3-->
- <jaxbClass>todoapp.app.viewmodels.todoitem.v1_0.ToDoItemDto</jaxbClass>
- <jaxbClass>todoapp.app.viewmodels.todoitem.v1_1.ToDoItemDto</jaxbClass>
- </jaxbClasses>
- </configuration>
- <dependencies>
- <dependency>
- <groupId>${project.groupId}</groupId>
- <artifactId>todoapp-dom</artifactId>
- <version>${project.version}</version>
- </dependency>
- <dependency> <!--4-->
- <groupId>com.google.guava</groupId>
- <artifactId>guava</artifactId>
- <version>16.0.1</version>
- </dependency>
- </dependencies>
- <executions>
- <execution>
- <phase>generate-sources</phase> <!--5-->
- <goals>
- <goal>xsd</goal> <!--6-->
- </goals>
- </execution>
- </executions>
- </plugin>
- <plugin>
- <artifactId>maven-assembly-plugin</artifactId> <!--7-->
- <version>2.5.3</version>
- <configuration>
- <descriptor>src/assembly/dep.xml</descriptor> <!--8-->
- </configuration>
- <executions>
- <execution>
- <id>create-archive</id>
- <phase>package</phase>
- <goals>
- <goal>single</goal>
- </goals>
- </execution>
- </executions>
- </plugin>
- </plugins>
- </build>
-</profile>
-----
-<1> enabled _unless_ `skip.isis-xsd` property specified
-<2> specify the app manifest to bootstrap the Isis runtime within the maven plugin
-<3> enumerate all JAXB-annotated view models
-<4> workaround to avoid conflict with plexus-default
-<5> by default is bound to `generate-resources`, but bind instead to `generate-sources` if also running the `xjc` profile: the XSD are an input to `xjc`, but it is bound by default to `generate-sources` and the `generate-sources` phase runs before the `generate-resources`.
-<6> run the `xsd` goal
-<7> define the assembly plugin
-<8> assembles the XSD schemas into a zip file, as defined by the `dep.xml` file (see below).
-
- The `dep.xml` file, referenced by the `assembly` plugin, is defined as:
-
-[source,xml]
-----
-<assembly xmlns="http://maven.apache.org/plugins/maven-assembly-plugin/assembly/1.1.2"
- xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xsi:schemaLocation="http://maven.apache.org/plugins/maven-assembly-plugin/assembly/1.1.2
- http://maven.apache.org/xsd/assembly-1.1.2.xsd">
- <id>xsd</id>
- <formats>
- <format>zip</format>
- </formats>
- <fileSets>
- <fileSet>
- <directory>${project.build.directory}/generated-resources/isis-xsd</directory> <!--1-->
- <outputDirectory>/</outputDirectory>
- </fileSet>
- </fileSets>
-</assembly>
-----
-<1> the location that the `xsd` goal writes to.
-
-
-
-=== XJC profile
-
-The `xjc` profile reads the XSD generated by the `xsd` goal, and from it generates Java DTOs. Note that this isn't
-round-tripping: the original view model is only for use within the Isis app, whereas the DTO generated from the XSDs
-is for use in a standalone context, eg in a Java subscriber on an event bus.
-
-The `xjc` profile is defined as:
-
-[source,xml]
-----
-<profile>
- <id>xjc</id>
- <activation>
- <property>
- <name>!skip.xjc</name> <!--1-->
- </property>
- </activation>
- <build>
- <plugins>
- <plugin>
- <groupId>org.jvnet.jaxb2.maven2</groupId>
- <artifactId>maven-jaxb2-plugin</artifactId>
- <version>0.12.3</version>
- <executions>
- <execution>
- <id>xjc-generate</id>
- <phase>generate-sources</phase>
- <goals>
- <goal>generate</goal>
- </goals>
- </execution>
- </executions>
- <configuration>
- <removeOldOutput>true</removeOldOutput>
- <schemaDirectory> <!--2-->
- target/generated-resources/isis-xsd/viewmodels.app.todoapp/todoitem
- </schemaDirectory>
- <schemaIncludes> <!--3-->
- <schemaInclude>v1_0/todoitem.xsd</schemaInclude>
- <schemaInclude>v1_1/todoitem.xsd</schemaInclude>
- </schemaIncludes>
- <catalog>src/main/resources/catalog.xml</catalog> <!--4-->
- </configuration>
- </plugin>
- <plugin>
- <groupId>org.codehaus.mojo</groupId>
- <artifactId>build-helper-maven-plugin</artifactId> <!--5-->
- <version>1.9.1</version>
- <executions>
- <execution>
- <id>add-source</id>
- <phase>generate-sources</phase>
- <goals>
- <goal>add-source</goal>
- </goals>
- <configuration>
- <sources>
- <source>target/generated-sources/xjc</source> <!--6-->
- </sources>
- </configuration>
- </execution>
- </executions>
- </plugin>
- </plugins>
- </build>
-</profile>
-----
-<1> enabled _unless_ `skip.xjc` property specified
-<2> specifies the directory that the XSD schemas were generated to by the `isis-maven-plugin`
-<3> specify each of the XSDs to be processed
-<4> catalog file indicates the location of the referenced link:_rgcms_schema-common[common schema] XSDs.
-<5> the `build-helper-maven-plugin` adds the Java source generated by the `xjc` plugin so that it can be compiled and
-packaged as any other code
-<6> the location that the `xjc` plugin generates its source code.
-
-
-The referenced `catalog.xml` file instructs the `xjc` plugin how to resolve referenced schema locations. Only a
-reference for the Apache Isis link:_rgcms_schema-common[common schema] is likely to be needed:
-
-[source,xml]
-----
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE catalog
- PUBLIC "-//OASIS//DTD Entity Resolution XML Catalog V1.0//EN"
- "http://www.oasis-open.org/committees/entity/release/1.0/catalog.dtd">
-<catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog">
- <public publicId="http://isis.apache.org/schema/common"
- uri="http://isis.apache.org/schema/common/common.xsd"/> <!--1-->
-</catalog>
-----
-<1> resolve the common schema from the Apache Isis website
-
-
-== To run
-
-The plugin is activated by default, so is run simply using:
-
-[source,bash]
-----
-mvn package
-----
-
-This will generate the XSDs, the DTOs from the XSDs, and package up the XSDs into a ZIP file and the generated DTO
-class files into a regular JAR package.
-
-
-If for any reason you want to disable the generation of the DTOs, use:
-
-[source,bash]
-----
-mvn package -Dskip.xjc
-----
-
-If you want to disable the generation of both the XSDs and the DTOs, use:
-
-[source,bash]
-----
-mvn package -Dskip.xjc -Dskip.isis-xsd
-----
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_AcceptHeaderService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_AcceptHeaderService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_AcceptHeaderService.adoc
deleted file mode 100644
index 372e9dd..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_AcceptHeaderService.adoc
+++ /dev/null
@@ -1,79 +0,0 @@
-[[_rgsvc_api_AcceptHeaderService]]
-= `AcceptHeaderService`
-: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 `AcceptHeaderService` domain service is a xref:rgant.adoc#_rgant-RequestScoped[`@RequestScoped`] service that
-simply exposes the HTTP `Accept` header to the domain. Its intended use is to support multiple versions of a REST API, where the responsibility for content negotiation (determining which version of the REST API is to be used) is managed by logic in the domain objects themselves.
-
-[NOTE]
-====
-As an alternative to performing content negotiation within the domain classes, the xref:rgfis.adoc#_rgfis_spi_ContentNegotiationService[`ContentNegotiationService`] and
-xref:rgsvc.adoc#_rgsvc_spi_ContentMappingService[`ContentMappingService`] SPI domain services allow the framework to perform the content negotiation responsibility.
-====
-
-== API & Implementation
-
-The API defined by the service is:
-
-[source,java]
-----
-@DomainService(nature = NatureOfService.DOMAIN)
-@RequestScoped // <1>
-public interface AcceptHeaderService {
- @Programmatic
- List<MediaType> getAcceptableMediaTypes(); // <2>
-}
-----
-<1> is xref:rgant.adoc#_rgant-RequestScoped[`@RequestScoped`], so this domain service instance is scoped to a particular request and is then destroyed
-<2> returns the list of media types found in the HTTP Accept header.
-
-
-The default implementation is provided by `o.a.i.v.ro.rendering.service.acceptheader.AcceptHeaderServiceForRest`.
-
-[NOTE]
-====
-Note that the service will only return a list when the request is initiated through the xref:ugvro.adoc#[Restful Objects viewer]. Otherwise the service will return `null`.
-====
-
-
-== Usage
-
-The intended use of this service is where there are multiple concurrent versions of a REST API, for backward
-compatibility of existing clients. The `AcceptHeaderService` allows the responsibility for content negotiation
-(determining which version of the REST API is to be used) to be performed by logic in the domain objects themselves.
-
-The diagram below illustrated this:
-
-image::{_imagesdir}reference-services-api/acceptheaderservice.png[width="700px",link="{_imagesdir}reference-services-api/acceptheaderservice.png"]
-
-The REST request is submitted to a domain service with a xref:rgant.adoc#_rgant-DomainService_nature[nature] of `VIEW_REST_ONLY` (`MyRestApi` in the diagram). This uses the `AcceptHeaderService` to obtain the values of the
-HTTP `Accept` header. Based on this it delegates to the appropriate underlying domain service (with a nature of
-`DOMAIN` so that they are not exposed in the REST API at all).
-
-[TIP]
-====
-The service does not define any conventions as to the format of the media types. The option is to use the media type's
-type/subtype, eg `application/vnd.myrestapi-v1+json`; an alternative is to use a media type parameter as a hint, eg
-`application/json;x-my-rest-api-version=1` (where `x-my-rest-api-version` is the media type parameter).
-
-The Restful Objects specification does this something similar with its own `x-ro-domain-type` media type parameter;
-this is used by the xref:rgsvc.adoc#_rgsvc_spi_ContentMappingService[`ContentMappingService`] to determine how to
-map domain objects to view models/DTOs.
-====
-
-
-
-
-== 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' default
-implementation of `AcceptHeaderService` class is automatically registered (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_ActionInvocationContext.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_ActionInvocationContext.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_ActionInvocationContext.adoc
deleted file mode 100644
index 5427e1c..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_ActionInvocationContext.adoc
+++ /dev/null
@@ -1,99 +0,0 @@
-[[_rgsvc_api_ActionInvocationContext]]
-= `ActionInvocationContext`
-: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 `ActionInvocationContext` domain service is a xref:rgant.adoc#_rgant-RequestScoped[`@RequestScoped`] service intended to support the implementation of "bulk" actions annotated with xref:rgant.adoc#_rgant-Action_invokeOn[`@Action#invokeOn()`]. This allows the user to select multiple objects in a table and then invoke the same action against all of them.
-
-When an action is invoked in this way, this service allows each object instance to "know where it is" in the collection; it acts a little like an iterator. In particular, an object can determine if it is the last object to be called, and so can perform special processing, eg to return a summary calculated result.
-
-
-== API & Implementation
-
-The API defined by the service is:
-
-[source,java]
-----
-@DomainService(nature = NatureOfService.DOMAIN)
-@RequestScoped // <1>
-public static class ActionInvocationContext {
- public InvokedOn getInvokedOn() { ... } // <2>
- public List<Object> getDomainObjects() { ... } // <3>
- public int getSize() { ... }
- public int getIndex() { ... } // <4>
- public boolean isFirst() { ... }
- public boolean isLast() { ... }
-}
-----
-<1> is xref:rgant.adoc#_rgant-RequestScoped[`@RequestScoped`], so this domain service instance is scoped to a particular request and is then destroyed
-<2> an enum set to either `OBJECT` (if action has been invoked on a single object) or `COLLECTION` (if has been invoked on a collection).
-<3> returns the list of domain objects which are being acted upon
-<4> is the 0-based index to the object being acted upon.
-
-
-
-== Usage
-
-For actions that are void or that return null, Apache Isis will return to the list once executed. But for bulk actions that are non-void, Apache Isis will render the returned object/value from the last object invoked (and simply discards the object/value of all actions except the last).
-
-One idiom is for the domain objects to also use the xref:rgsvc.adoc#_rgsvc_api_Scratchpad[`Scratchpad`] service to share information, for example to aggregate values. The `ActionInvocationContext#isLast()` method can then be used to determine if all the information has been gathered, and then do something with it (eg derive variance across a range of values, render a graph etc).
-
-More prosaically, the `ActionInvocationContext` can be used to ensure that the action behaves appropriately depending on how it has been invoked (on a single object and/or a collection) whether it is called in bulk mode or regular mode. Here's a snippet of code from the bulk action in the Isis addon example https://github.com/isisaddons/isis-app-todoapp/[todoapp] (not ASF):
-
-[source,java]
-----
-public class ToDoItem ... {
- @Action(invokeOn=InvokeOn.OBJECTS_AND_COLLECTIONS)
- public ToDoItem completed() {
- setComplete(true);
- ...
- return actionInvocationContext.getInvokedOn() == InvokedOn.OBJECT
- ? this // <1>
- : null; // <2>
- }
- @Inject
- ActionInvocationContext actionInvocationContext;
-}
-----
-<1> if invoked as a regular action, return this object;
-<2> otherwise (if invoked on collection of objects), return null, so that the xref:ugvw.adoc#[Wicket viewer] will re-render the list of objects
-
-
-
-
-== 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' default
-implementation of `ActionInvocationContext` class is automatically registered (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).
-
-
-
-== Unit testing support
-
-The `ActionInvocationContext` class also has a couple of static factory methods intended to support unit testing:
-
-[source,java]
-----
-@DomainService(nature = NatureOfService.DOMAIN)
-@RequestScoped
-public class ActionInvocationContext {
- public static ActionInvocationContext onObject(final Object domainObject) {
- return new ActionInvocationContext(InvokedOn.OBJECT, Collections.singletonList(domainObject));
- }
- public static ActionInvocationContext onCollection(final Object... domainObjects) {
- return onCollection(Arrays.asList(domainObjects));
- }
- public static ActionInvocationContext onCollection(final List<Object> domainObjects) {
- return new ActionInvocationContext(InvokedOn.COLLECTION, domainObjects);
- }
- ...
-}
-----
\ 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_ApplicationFeatureRepository.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_ApplicationFeatureRepository.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_ApplicationFeatureRepository.adoc
deleted file mode 100644
index aac9dec..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_ApplicationFeatureRepository.adoc
+++ /dev/null
@@ -1,66 +0,0 @@
-[[_rgsvc_api_ApplicationFeatureRepository]]
-= `ApplicationFeatureRepository`
-: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 `ApplicationFeatureRepository` provides the access to string representations of the packages, classes and
-class members (collectively: "application features") of the domain classes within the Apache Isis' internal metamodel.
-
-[TIP]
-====
-This functionality was originally implemented as part of (non-ASF) link:http://isisaddons.org[Isis Addons] security
-module, where the string representations of the various features are used to represent permissions.
-====
-
-
-== API & Implementation
-
-The API defined by the service is:
-
-[source,java]
-----
-public interface ApplicationFeatureRepository {
- List<String> packageNames();
- List<String> packageNamesContainingClasses(ApplicationMemberType memberType);
- List<String> classNamesContainedIn(String packageFqn, ApplicationMemberType memberType);
- List<String> classNamesRecursivelyContainedIn(String packageFqn);
- List<String> memberNamesOf(String packageFqn, String className, ApplicationMemberType memberType);
-}
-----
-
-where `ApplicationMemberType` in turn is:
-
-[source,java]
-----
-public enum ApplicationMemberType {
- PROPERTY,
- COLLECTION,
- ACTION;
-}
-----
-
-These methods are designed primarily to return lists of strings for use in drop-downs.
-
-
-
-
-== 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 `ApplicationFeatureRepository` 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 default implementation of this service - `ApplicationFeatureRepositoryDefault` uses the `ApplicationFeatureFactory` service to instantiate `ApplicationFeature` instances.
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_BackgroundService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_BackgroundService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_BackgroundService.adoc
deleted file mode 100644
index bd4a802..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_BackgroundService.adoc
+++ /dev/null
@@ -1,134 +0,0 @@
-[[_rgsvc_api_BackgroundService]]
-= `BackgroundService2`
-: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 `BackgroundService2` domain service, and also the companion
-xref:rgsvc.adoc#_rgsvc_spi_BackgroundCommandService[`BackgroundCommandService2`] SPI service, enable commands
-to be persisted such that they may be invoked in the background.
-
-The `BackgroundService2` is responsible for capturing a memento representing the command in a typesafe way,
-and persisting it rather than executing it directly.
-
-The default `BackgroundServiceDefault` implementation works by using a proxy wrapper around the target so that it can
-capture the action to invoke and its arguments. (As of `1.13.0`), this is done using xref:rgfis.adoc#_rgfis_spi_CommandDtoServiceInternal[`CommandDtoServiceInternal`] (in previous releases it used (a private copy of) xref:rgsvc.adoc#_rgsvc_api_MementoService[`MementoService`]).
-
-The persistence delegates the persistence of the memento to an appropriate implementation of the companion
-`BackgroundCommandService2`. One such implementation of `BackgroundCommandService` is provided by (non-ASF)
-http://github.com/isisaddons/isis-module-command[Isis addons' command] module.
-
-The persisting of commands is only half the story; there needs to be a separate process to read the commands and
-execute them. The `BackgroundCommandExecution` abstract class (discussed
-xref:rgsvc.adoc#_rgsvc_api_BackgroundService_BackgroundCommandExecution[below]) provides infrastructure to do this;
-the concrete implementation of this class depends on the configured `BackgroundCommandService` (in order to query for
-the persisted (background) ``Command``s.
-
-
-
-== API & Implementation
-
-The API is:
-
-[source,java]
-----
-public interface BackgroundService2 {
- <T> T execute(final T object); // <1>
- <T> T executeMixin(Class<T> mixinClass, Object mixedIn); // <2>
-}
-----
-<1> returns a proxy around the domain object; any methods executed against this proxy will result in a command (to invoke the corresponding action) being persisted by xref:rgsvc.adoc#_rgsvc_spi_BackgroundCommandService2[`BackgroundCommandService2`]
-<2> Returns a proxy around the mixin; any methods executed against this proxy will result in a command (to invoke the corresponding mixin action) being persisted by xref:rgsvc.adoc#_rgsvc_spi_BackgroundCommandService2[`BackgroundCommandService2`].
-
-The default implementation is provided by core (`o.a.i.core.runtime.services.background.BackgroundServiceDefault`).
-
-
-
-== Usage
-
-Using the service is very straight-forward; wrap the target domain object using `BackgroundService#execute(...)` and invoke the method on the object returned by that method.
-
-For example:
-
-[source,java]
-----
-public void submitCustomerInvoices() {
- for(Customer customer: customerRepository.findCustomersToInvoice()) {
- backgroundService.execute(customer).submitInvoice();
- }
- messageService.informUser("Calculating...");
-}
-----
-
-This will create a bunch of background commands executing the `submitInvoice()` action for each of the customers returned from the customer repository.
-
-The action method invoked must be part of the Apache Isis metamodel, which is to say it must be public, accept only scalar arguments, and must not be annotated with xref:rgant.adoc#_rgant-Programmatic[`@Programmatic`] or `@Ignore`. However, it may be annotated with xref:rgant.adoc#_rgant-Action_hidden[`@Action#hidden()`] or xref:rgant.adoc#_rgant-ActionLayout_hidden[`@ActionLayout#hidden()`] and it will still be invoked.
-
-In fact, when invoked by the background service, no business rules (hidden, disabled, validation) are enforced; the action method must take responsibility for performing appropriate validation and error checking.
-
-[TIP]
-====
-If you want to check business rules, you can use xref:rgant.adoc#_rgant-WrapperFactory[`@WrapperFactory#wrapNoExecute(...)`].
-====
-
-
-
-== End-user experience
-
-For the end-user, executing an action that delegates work off to the `BackgroundService` raises the problem of how does the user know the work is complete?
-
-One option is for the background jobs to take responsibility to notify the user themselves. In the above example, this would be the `submitInvoice()` method called upon each customer. One could imagine more complex designs where only the final command executed notifies the user.
-
-However, an alternative is to rely on the fact that the `BackgroundService` will automatically hint that the `Command` representing the original interaction (to `submitCustomerInvoices()` in the example above) should be persisted. This will be available if the related xref:rgsvc.adoc#_rgsvc_api_CommandContext[`CommandContext`] and xref:rgsvc.adoc#_rgsvc_spi_CommandService[`CommandService`] domain services are configured, and the `CommandService` supports persistent commands. Note that (non-ASF) http://github.com/isisaddons/isis-module-command[Isis addons' command] module does indeed provide such an implementation of `CommandService` (as well as of the required `BackgroundCommandService`).
-
-Thus, the original action can run a query to obtain it corresponding `Command`, and return this to the user. The upshot is that the child ``Command``s created by the `BackgroundService` will then be associated with `Command` for the original action.
-
-We could if we wanted write the above example as follows:
-
-[source,java]
-----
-public Command submitCustomerInvoices() {
- for(Customer customer: customerRepository.findCustomersToInvoice()) {
- backgroundService.execute(customer).submitInvoice();
- }
- return commandContext.getCommand();
-}
-@Inject
-CommandContext commandContext; // <1>
-----
-<1> the injected xref:rgsvc.adoc#_rgsvc_api_CommandContext[`CommandContext`] domain service.
-
-The user would be returned a domain object representing their action invocation.
-
-
-
-
-== Registering the Services
-
-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 `BackgroundService` is automatically registered (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
-
-This service is closely related to the xref:rgsvc.adoc#_rgsvc_api_CommandContext[`CommandContext`] and also that service's supporting xref:rgsvc.adoc#_rgsvc_spi_CommandService[`CommandService`] 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. The latter is analogous to the way in which the `BackgroundCommandService` persists the child background `Command`s.
-
-The implementations of `CommandService` and `BackgroundCommandService` go together; typically both parent `Command`s and child background `Command`s will be persisted in the same way. The (non-ASF) http://github.com/isisaddons/isis-module-command[Isis addons' command] module provides implementations of both (see xref:rgsvc.adoc#_rgsvc_spi_CommandService[`CommandService`] and xref:rgsvc.adoc#_rgsvc_spi_BackgroundCommandService[`BackgroundCommandService`]).
-
-The xref:rgfis.adoc#_rgfis_spi_CommandDtoServiceInternal[`CommandDtoServiceInternal`] is used to obtain
-a memento of the command such that it can be persisted. (In earlier versions, xref:rgsvc.adoc#_rgsvc_api_MementoService[`MementoService`] was used for this purpose).
-
-
-include::_rgsvc_api_BackgroundService_BackgroundCommandExecution.adoc[leveloffset=+1]
-include::_rgsvc_api_BackgroundService_Quartz.adoc[leveloffset=+1]
-
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_BackgroundService_BackgroundCommandExecution.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_BackgroundService_BackgroundCommandExecution.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_BackgroundService_BackgroundCommandExecution.adoc
deleted file mode 100644
index fede5f0..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_BackgroundService_BackgroundCommandExecution.adoc
+++ /dev/null
@@ -1,25 +0,0 @@
-[[_rgsvc_api_BackgroundService_BackgroundCommandExecution]]
-= `BackgroundCommandExec'n` abstract class
-: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 `BackgroundCommandExecution` (in isis-core) is an abstract template class provided by isis-core 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.
-
-
-
-
-