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:06 UTC
[30/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_EventBusService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_EventBusService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_EventBusService.adoc
deleted file mode 100644
index 3d325f7..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_EventBusService.adoc
+++ /dev/null
@@ -1,405 +0,0 @@
-[[_rgsvc_api_EventBusService]]
-= `EventBusService`
-: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 `EventBusService` allows domain objects to emit events to subscribing domain services using an in-memory event bus.
-
-The primary user of the service is the framework itself, which automatically emit events for xref:rgant.adoc#_rgant-Action_domainEvent[actions], xref:rgant.adoc#_rgant-Property_domainEvent[properties] and xref:rgant.adoc#_rgant-Collection_domainEvent[collections]. Multiple events are generated:
-
-* when an object member is to be viewed, an event is fired; subscribers can veto (meaning that the member is hidden)
-* when an object member is to be enabled, the same event instance is fired; subscribers can veto (meaning that the member is disabled, ie cannot be edited/invoked)
-* when an object member is being validated, then a new event instance is fired; subscribers can veto (meaning that the candidate values/action arguments are rejected)
-* when an object member is about to be changed, then the same event instance is fired; subscribers can perform pre-execution operations
-* when an object member has been changed, then the same event instance is fired; subscribers can perform post-execution operations
-
-If a subscriber throws an exception in the first three steps, then the interaction is vetoed. If a subscriber throws an exception in the last two steps, then the transaction is aborted. For more on this topic, see xref:rgant.adoc#_rgant-Action_domainEvent[`@Action#domainEvent()`], xref:rgant.adoc#_rgant-Property_domainEvent[`@Property#domainEvent()`] and xref:rgant.adoc#_rgant-Collection_domainEvent[`@Collection#domainEvent()`].
-
-It is also possible for domain objects to programmatically generate domain events. However the events are published, the primary use case is to decoupling interactions from one module/package/namespace and another.
-
-Two implementations are available, using either link:https://code.google.com/p/guava-libraries/[Guava]'s https://code.google.com/p/guava-libraries/wiki/EventBusExplained[`EventBus`], or alternatively using the link:http://www.axonframework.org/[AxonFramework]'s link:http://www.axonframework.org/docs/2.4/single.html#d5e1489[SimpleEventBus]. It is also possible to plug in a custom implementation.
-
-
-
-[[__rgsvc_api_EventBusService_api-and-implementation]]
-== API & Implementation
-
-The API defined by `EventBusService` is:
-
-[source,java]
-----
-public abstract class EventBusService {
- @Programmatic
- public void post(Object event) { ... } // <1>
- @Programmatic
- public void register(final Object domainService) { ... } // <2>
- @Programmatic
- public void unregister(final Object domainService) { ... } // <3>
-}
-----
-<1> posts the event onto event bus
-<2> allows domain services to register themselves. This should be done in their xref:rgant.adoc#_rgant-PostConstruct[`@PostConstruct`] initialization method (for both singleton and xref:rgant.adoc#_rgant-RequestScoped[`@RequestScoped`] domain services.
-<3> exists for symmetry, but need never be called (it is in fact deliberately a no-op).
-
-Isis provides a default implementation of the service, `o.a.i.objectstore.jdo.datanucleus.service.eventbus.EventBusServiceJdo`.
-
-
-
-
-
-== Registering Subscribers
-
-The `register()` method should be called in the xref:rgant.adoc#_rgant-PostConstruct[`@PostConstruct`] lifecycle method. It is valid and probably the least confusing to readers to also "unregister" in the xref:rgant.adoc#_rgant-PreDestroy[`@PreDestroy`] lifecycle method (though as noted xref:rgsvc.adoc#__rgsvc_api_EventBusService_api-and-implementation[above], unregistering is actually a no-op).
-
-For example:
-
-[source,java]
-----
-@DomainService(nature=NatureOfService.DOMAIN) // <1>
-@DomainServiceLayout( menuOrder="1") // <2>
-public class MySubscribingDomainService {
- @PostConstruct
- public void postConstruct() {
- eventBusService.register(this); // <3>
- }
- @PreDestroy
- public void preDestroy() {
- eventBusService.unregister(this); // <4>
- }
- ...
- @javax.inject.Inject
- EventBusService eventBusService;
-}
-----
-<1> subscribers are typically not visible in the UI, so specify a `DOMAIN` nature
-<2> It's important that subscribers register before any domain services that might emit events on the event bus service.
-For example, the (non-ASF) http://github.com/isisaddons/isis-module-security[Isis addons' security] module provides a
-domain service that automatically seeds certain domain entities; these will generate
-xref:rgcms.adoc#_rgcms_classes_lifecycleevent[lifecycle events] and so any subscribers must be registered before such seed
-services. The easiest way to do this is to use the xref:rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] attribute.
-<3> register with the event bus service during xref:rgant.adoc#_rgant-PostConstruct[`@PostConstruct`]
- initialization
-<4> corresponding deregister when shutting down
-
-This works for both singleton (application-scoped) and also xref:rgant.adoc#_rgant-RequestScoped[`@RequestScoped`] domain services.
-
-
-[TIP]
-====
-The xref:rgcms.adoc#_rgcms_classes_super_AbstractSubscriber[`AbstractSubscriber`] class automatically performs this
-registration. As a convenience, it is also annotated with the
-xref:rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] attribute.
-====
-
-
-
-== Annotating Members
-
-As discussed in the introduction, the framework will automatically emit domain events for all of the object members (actions, properties or collections) of an object whenever that object is rendered or (more generally) interacted with.
-
-For example:
-
-[source,java]
-----
-public class Customer {
- @Action
- public Customer placeOrder(Product product, @ParameterLayout(named="Quantity") int qty) { ... }
- ...
-}
-----
-
-will propagate an instance of the default `o.a.i.applib.services.eventbus.ActionDomainEvent.Default` class. If using the Guava event bus this can be subscribed to using:
-
-[source,java]
-----
-@DomainService(nature=NatureOfService.DOMAIN)
-public class MySubscribingDomainService
- @Programmatic
- @com.google.common.eventbus.Subscribe
- public void on(ActionDomainEvent ev) { ... }
- ...
-}
-----
-
-or if using Axonframework, the subscriber uses a different annotation:
-
-[source,java]
-----
-@DomainService(nature=NatureOfService.DOMAIN)
-public class MySubscribingDomainService
- @Programmatic
- @org.axonframework.eventhandling.annotation.EventHandler
- public void on(ActionDomainEvent ev) { ... }
- ...
-}
-----
-
-More commonly though you will probably want to emit domain events of a specific subtype. As a slightly more interesting example, suppose in a library domain that a `LibraryMember` wants to leave the library. A letter should be sent out detailing any books that they still have out on loan:
-
-In the `LibraryMember` class, we publish the event by way of an annotation:
-
-[source,java]
-----
-public class LibraryMember {
- @Action(domainEvent=LibraryMemberLeaveEvent.class) // <1>
- public void leave() { ... }
- ...
-}
-----
-<1> `LibraryMemberLeaveEvent` is a subclass of `o.a.i.applib.eventbus.ActionDomainEvent`. The topic of subclassing is discussed in more detail xref:rgsvc.adoc#__rgsvc_api_EventBusService_event-hierarchy[below].
-
-Meanwhile, in the `BookRepository` domain service, we subscribe to the event and act upon it. For example:
-
-[source,java]
-----
-public class BookRepository {
- @Programmatic
- @com.google.common.eventbus.Subscribe
- public void onLibraryMemberLeaving(LibraryMemberLeaveEvent e) {
- LibraryMember lm = e.getLibraryMember();
- List<Book> lentBooks = findBooksOnLoanFor(lm);
- if(!lentBooks.isEmpty()) {
- sendLetter(lm, lentBooks);
- }
- }
- ...
-}
-----
-
-This design allows the `libraryMember` module to be decoupled from the `book` module.
-
-
-
-[[__rgsvc_api_EventBusService_event-hierarchy]]
-== Event hierarchy
-
-By creating domain event subtypes we can be more semantically precise and in turn providesmore flexibility for subscribers: they can choose whether to be broadly applicable (by subscribing to a superclass) or to be tightly focussed (by subscribing to a subclass).
-
-We recommend that you define event classes at (up to) four scopes:
-
-* at the top "global" scope is the Apache Isis-defined `o.a.i.applib.event.ActionDomainEvent`
-* for the "module" scope, create a static class to represent the module itself, and creating nested classes within
-* for each "class" scope, create a nested static event class in the domain object's class for all of the domain object's actions
-* for each "action" scope, create a nested static event class for that action, inheriting from the "domain object" class.
-
-To put all that into code; at the module level we can define:
-
-[source,java]
-----
-package com.mycompany.modules.libmem;
-...
-public static class LibMemModule {
- private LibMemModule() {}
- public abstract static class ActionDomainEvent<S>
- extends org.apache.isis.applib.event.ActionDomainEvent<S> {}
- ... // <1>
- public abstract static class PropertyDomainEvent<S,T>
- extends org.apache.isis.applib.event.PropertyDomainEvent<S,T> {}
- public abstract static class CollectionDomainEvent<S,E>
- extends org.apache.isis.applib.event.CollectionDomainEvent<S,E> {}
-}
-----
-<1> similar events for properties and collections should also be defined
-
-For the class-level we can define:
-
-[source,java]
-----
-public static class LibraryMember {
- public abstract static class ActionDomainEvent
- extends LibMemModule.ActionDomainEvent<LibraryMember> { }
- ... // <1>
-}
-----
-<1> similar events for properties and collections should also be defined
-
-and finally at the action level we can define:
-
-[source,java]
-----
-public class LibraryMember {
- public static class LeaveEvent extends LibraryMember.ActionDomainEvent { }
- @Action(domainEvent=LeaveEvent.class)
- public void leave() { ... }
- ...
-}
-----
-
-The subscriber can subscribe either to the general superclass (as before), or to any of the classes in the hierarchy.
-
-
-=== Variation (for contributing services)
-
-A slight variation on this is to not fix the generic parameter at the class level, ie:
-
-[source,java]
-----
-public static class LibraryMember {
- public abstract static class ActionDomainEvent<S>
- extends LibMemModule.ActionDomainEvent<S> { }
- ...
-}
-----
-
-and instead parameterize down at the action level:
-
-[source,java]
-----
-public class LibraryMember {
- public static class LeaveEvent
- extends LibraryMember.ActionDomainEvent<LibraryMember> { } // <1>
- }
- @Action(domainEvent=LeaveEvent.class)
- public void leave() { ... }
- ...
-}
-----
-
-This then allows for other classes - in particular domain services contributing members - to also inherit from the class-level domain events.
-
-
-
-
-== Programmatic posting
-
-To programmatically post an event, simply call `#post()`.
-
-The `LibraryMember` example described above could for example be rewritten into:
-
-[source,java]
-----
-public class LibraryMember {
- ...
- public void leave() {
- ...
- eventBusService.post(new LibraryMember.LeaveEvent(...)); // <1>
- }
- ...
-}
-----
-<1> `LibraryMember.LeaveEvent` could be _any_ class, not just a subclass of `o.a.i.applib.event.ActionDomainEvent`.
-
-In practice we suspect there will be few cases where the programmatic approach is required rather than the declarative approach afforded by xref:rgant.adoc#_rgant-Action_domainEvent[`@Action#domainEvent()`] et al.
-
-
-
-== Using `WrapperFactory`
-
-An alternative way to cause events to be posted is through the xref:rgsvc.adoc#_rgsvc_api_WrapperFactory[`WrapperFactory`]. This is useful when you wish to enforce a (lack-of-) trust boundary between the caller and the callee.
-
-For example, suppose that `Customer#placeOrder(...)` emits a `PlaceOrderEvent`, which is subscribed to by a `ReserveStockSubscriber`. This subscriber in turn calls `StockManagementService#reserveStock(...)`. Any business rules on `#reserveStock(...)` should be enforced.
-
-In the `ReserveStockSubscriber`, we therefore use the `WrapperFactory`:
-
-[source,java]
-----
-@DomainService(nature=NatureOfService.DOMAIN)
-public class ReserveStockSubscriber {
- @Programmatic
- @Subscribe
- public void on(Customer.PlaceOrderEvent ev) {
- wrapperFactory.wrap(stockManagementService)
- .reserveStock(ev.getProduct(), ev.getQuantity());
- }
- ...
- @Inject
- StockManagementService stockManagementService;
- @Inject
- WrapperFactory wrapperFactory;
-}
-----
-
-
-== Implementation SPI
-
-The implementation of `EventBusService` provided by Apache Isis will by default use link:https://code.google.com/p/guava-libraries/[Guava]'s https://code.google.com/p/guava-libraries/wiki/EventBusExplained[`EventBus`] as the underlying in-memory event bus. Alternatively the link:http://www.axonframework.org/[AxonFramework]'s link:http://www.axonframework.org/docs/2.4/single.html#d5e1489[SimpleEventBus] can be used. Which is used is specified through configuration property (described xref:rgsvc.adoc#__rgsvc_api_EventBusService_Configuration[below]).
-
-[NOTE]
-.Guava vs Axon, which to use?
-====
-Guava actually queues up events; they are not guaranteed to be dispatched immediately. This generally is not problem, but can be for cases where the subscriber may in turn want to post its own events (using xref:rgsvc.adoc#_rgsvc_api_WrapperFactory[`WrapperFactory`]).
-
-The Axon `SimpleEventBus`-based implementation on the other hand is fully synchronous; events are dispatched as soon as they are posted. This works well in all scenarios (that we have tested).
-====
-
-
-It is also possible to use some other implementation.
-
-[source,java]
-----
-public interface EventBusImplementation {
- void register(Object domainService);
- void unregister(Object domainService);
- void post(Object event);
-}
-----
-
-As is probably obvious, the `EventBusService` just delegates down to these method calls when its own similarly named methods are called.
-
-If you do provide your own implementation of this SPI, be aware that your subscribers will need to use whatever convention is required (eg different annotations) such that the events are correctly routed through to your subscribers.
-
-
-
-[[__rgsvc_api_EventBusService_Configuration]]
-== Configuration
-
-The implementation of `EventBusService` provided by Apache Isis will by default use link:https://code.google.com/p/guava-libraries/[Guava]'s https://code.google.com/p/guava-libraries/wiki/EventBusExplained[`EventBus`] as the underlying in-memory event bus. Alternatively the link:http://www.axonframework.org/[AxonFramework]'s link:http://www.axonframework.org/docs/2.4/single.html#d5e1489[SimpleEventBus] can be used.
-
-To specify which, add the xref:rgcfg.adoc#_rgcfg_configuring-core[configuration property] `isis.services.eventbus.implementation`:
-
-[source,ini]
-----
-isis.services.eventbus.implementation=guava
-----
-
-or
-
-[source,ini]
-----
-isis.services.eventbus.implementation=axon
-----
-
-If you have written your own implementation of the `EventBusServiceImplementation` SPI, then specify instead its fully-qualified class name:
-
-[source,ini]
-----
-isis.services.eventbus.implementation=com.mycompany.isis.MyEventBusServiceImplementation
-----
-
-
-
-In addition, there is one further configuration property, whether to allow "late registration":
-
-[source,ini]
-----
-isis.services.eventbus.allowLateRegistration=false
-----
-
-Late registration refers to the idea that a domain service can register itself with the `EventBusService` after events have been posted. Since domain services are set up at boot time, this almost certainly constitutes a bug in the code and so by default late registration is _not_ allowed. Setting the above property to `true` disables this check.
-
-
-
-
-
-== 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 `EventBusService` 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 `EventBusService` is intended for fine-grained publish/subscribe for object-to-object interactions within an Apache Isis domain object model. The event propagation is strictly in-memory, and there are no restrictions on the object acting as the event (it need not be serializable, for example).
-
-The xref:rgsvc.adoc#_rgsvc_spi_PublishingService[`PublishingService`] meanwhile is intended for coarse-grained publish/subscribe for system-to-system interactions, from Apache Isis to some other system. Here the only events published are those that action invocations (for actions annotated with xref:rgant.adoc#_rgant-Action_publishing[`@Action#publishing()`]) and of changed objects (for objects annotated with xref:rgant.adoc#_rgant-DomainObject_publishing[`@DomainObject#publishing()`]).
\ 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_ExecutionParametersService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_ExecutionParametersService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_ExecutionParametersService.adoc
deleted file mode 100644
index 02ce4e6..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_ExecutionParametersService.adoc
+++ /dev/null
@@ -1,30 +0,0 @@
-[[_rgsvc_api_ExecutionParametersService]]
-= `ExecutionParametersService`
-: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 `ExecutionParametersService` ...
-
-Apache Isis provides a default implementation
-
-
-
-== API & Implementation
-
-The API and implementation of this service is simply:
-
-[source,java]
-----
-public class ExecutionParametersService {
- public ExecutionParameters newExecutionParameters(final String parameters) {
- return new ExecutionParameters(parameters);
- }
-}
-----
-
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_FactoryService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_FactoryService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_FactoryService.adoc
deleted file mode 100644
index fc15140..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_FactoryService.adoc
+++ /dev/null
@@ -1,79 +0,0 @@
-[[_rgsvc_api_FactoryService]]
-= `FactoryService`
-: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 `FactoryService` collects together methods for instantiating domain objects.
-
-[NOTE]
-====
-The methods in this service replace similar methods (now deprecated) in xref:rgsvc.adoc#_rgsvc_api_DomainObjectContainer[`DomainObjectContainer`].
-====
-
-
-== API
-
-The API of `FactoryService` is:
-
-[source,java]
-----
-public interface FactoryService {
- <T> T instantiate(final Class<T> ofType); // <1>
- <T> T mixin(); // <2>
-}
-----
-<1> create a new non-persisted domain entity. Any services will be automatically injected into the service.
-<2> programmatically instantiate a mixin, as annotated with xref:rgant.adoc#_rgant-Mixin[`@Mixin`] or xref:rgant.adoc#_rgant-DomainObject_nature[`@DomainObject#nature()`].
-
-
-The object is created in memory, but is not persisted. The benefits of using this method (instead of simply using the Java `new` keyword) are:
-
-* any services will be injected into the object immediately (otherwise they will not be injected until the frameworkbecomes aware of the object, typically when it is persisted through the xref:rgsvc.adoc#_rgsvc_api_RepositoryService[`RepositoryService`]
-
-* the default value for any properties (usually as specified by `defaultXxx()` supporting methods) will not be set and the `created()` callback will be called.
-
-The corollary is: if your code never uses `defaultXxx()` or the `created()` callback, then you can just `new` up the object. The xref:rgsvc.adoc#_rgsvc_api_ServiceRegistry[`ServiceRegistry`] service can be used to inject services into the domain object.
-
-
-
-== Usage
-
-For example:
-
-[source,java]
-----
-Customer cust = factoryService.instantiate(Customer.class);
-cust.setFirstName("Freddie");
-cust.setLastName("Mercury");
-repositoryService.persist(cust);
-----
-
-
-== Implementation
-
-The core framework provides a default implementation of this service (`o.a.i.core.metamodel.services.factory.FactoryServiceDefault`).
-
-
-
-
-== 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 `FactoryService` 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_RepositoryService[`RepositoryService`] is often used in conjunction with the `FactoryService`, to persist domain objects after they have been instantiated and populated.
-
-An alternative to using the factory service is to simply instantiate the object ("new is the new new") and then use the
-xref:rgsvc.adoc#_rgsvc_api_ServiceRegistry[`ServiceRegistry`] service to inject other domain services into the
-instantiated object.
\ 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_FixtureScriptsDefault.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_FixtureScriptsDefault.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_FixtureScriptsDefault.adoc
deleted file mode 100644
index 166658b..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_FixtureScriptsDefault.adoc
+++ /dev/null
@@ -1,50 +0,0 @@
-[[_rgsvc_api_FixtureScriptsDefault]]
-= `FixtureScriptsDefault`
-: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 `FixtureScriptsDefault` service provides the ability to execute xref:ugtst.adoc#_ugtst_fixture-scripts_api-and-usage[fixture scripts] .
-
-The service extends from the xref:rgcms.adoc#_rgcms_classes_super_FixtureScripts[`FixtureScripts`], and is only instantiated by the framework if there no custom implementation of `FixtureScripts` has been otherwise provided; in other words it is a fallback.
-
-If this service is instantiated (as a fallback) then it uses the xref:rgsvc.adoc#_rgsvc_spi_FixtureScriptsSpecificationProvider[`FixtureScriptsSpecificationProvider`] to obtain a `FixtureScriptsSpecification`. This configures this service, telling it which package to search for `FixtureScript` classes, how to execute those classes, and hints that influence the UI.
-
-[TIP]
-====
-We recommend using xref:rgsvc.adoc#_rgsvc_spi_FixtureScriptsSpecificationProvider[`FixtureScriptsSpecificationProvider`] rather than subclassing xref:rgcms.adoc#_rgcms_classes_super_FixtureScripts[`FixtureScripts`].
-====
-
-
-
-== API & Implementation
-
-The API for the service is:
-
-[source,java]
-----
-public class FixtureScriptsDefault ... {
- @Programmatic
- public List<FixtureResult> runFixtureScript(
- FixtureScript fixtureScript,
- String parameters) { ... }
-}
-----
-
-... in other words the same as xref:rgcms.adoc#_rgcms_classes_super_FixtureScripts[`FixtureScripts`] superclass that it inherits from.
-
-
-== Configuration
-
-As noted in the introduction, this service is only instantiated if there is no other implementation of `FixtureScripts` available on the classpath.
-
-If an instance of `FixtureScriptsSpecificationProvider` is available on the classpath, then the service will be visible in the UI (assuming xref:rgcfg.adoc#_rgcfg_deployment-types[prototype mode]). Otherwise the service will be available only to be injected and invoked programmatically.
-
-
-
-
-== Related Services
-
-The service interacts with xref:rgsvc.adoc#_rgsvc_spi_FixtureScriptsSpecificationProvider[`FixtureScriptsSpecificationProvider`].
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_GuiceBeanProvider.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_GuiceBeanProvider.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_GuiceBeanProvider.adoc
deleted file mode 100644
index a004dfd..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_GuiceBeanProvider.adoc
+++ /dev/null
@@ -1,91 +0,0 @@
-[[_rgsvc_api_GuiceBeanProvider]]
-= `GuiceBeanProvider`
-: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 `GuiceBeanProvider` domain service acts as a bridge between Apache Isis' xref:ugvw.adoc#[Wicket viewer] internal bootstrapping using link:https://github.com/google/guice[Google Guice].
-
-This service operates at a very low-level, and you are unlikely to have a need for it. It is used internally by the framework, in the default implementation of the xref:rgsvc.adoc#_rgsvc_api_DeepLinkService[`DeepLinkService`].
-
-[NOTE]
-====
-Currently Apache Isis uses a combination of Guice (within the Wicket viewer only) and a home-grown dependency injection framework. In future versions we intended to refactor the framework to use CDI throughout. At that time this service is likely to become redundant because we will allow any of the internal components of Apache Isis to be injected into your domain object code.
-====
-
-
-== API & Implementation
-
-The API defined by this service is:
-
-[source,java]
-----
-public interface GuiceBeanProvider {
- @Programmatic
- <T> T lookup(Class<T> beanType);
- @Programmatic
- <T> T lookup(Class<T> beanType, final Annotation qualifier);
-}
-----
-
-The xref:ugvw.adoc#[Wicket viewer] this provides an implementation of this service.
-
-
-
-== Usage
-
-Using the xref:ugvw.adoc#[Wicket viewer] requires subclassing of `IsisWicketApplication`. In the subclass it is commonplace to override `newIsisWicketModule()`, for example:
-
-[source,java]
-----
-@Override
-protected Module newIsisWicketModule() {
- final Module isisDefaults = super.newIsisWicketModule();
- final Module overrides = new AbstractModule() {
- @Override
- protected void configure() {
- bind(String.class).annotatedWith(Names.named("applicationName"))
- .toInstance("ToDo App");
- bind(String.class).annotatedWith(Names.named("applicationCss"))
- .toInstance("css/application.css");
- bind(String.class).annotatedWith(Names.named("applicationJs"))
- .toInstance("scripts/application.js");
- ...
- }
- };
- return Modules.override(isisDefaults).with(overrides);
-}
-----
-
-This "module" is in fact a Guice module, and so the `GuiceBeanProvider` service can be used to lookup any of the components bound into it.
-
-For example:
-
-[source,java]
-----
-public class SomeDomainObject {
- private String lookupApplicationName() {
- return guiceBeanProvider.lookup(String.class, Names.named("applicationName"));
- }
- @Inject
- GuiceBeanProvider guiceBeanProvider;
-}
-----
-
-should return "ToDo App".
-
-
-
-== 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]), _and_ that the
-xref:ugvw.adoc#[Wicket viewer] is being used, then an implementation of `GuiceBeanProvider` 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_HomePageProviderService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_HomePageProviderService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_HomePageProviderService.adoc
deleted file mode 100644
index 7065303..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_HomePageProviderService.adoc
+++ /dev/null
@@ -1,40 +0,0 @@
-[[_rgsvc_api_HomePageProviderService]]
-= `HomePageProviderService`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-
-This service simply provides access to the home page object (if any) that is returned from the domain service
-action annotated with xref:rgant.adoc#_rgant-HomePage[`@HomePage`].
-
-It is originally introduced to support the default implementation of
-xref:rgsvc.adoc#_rgsvc_spi_RoutingService[`RoutingService`], but was factored out to support alternative implementations
-of that service (and may be useful for other use cases).
-
-
-== API & Implementation
-
-The API defined by `HomePageProviderService` is:
-
-[source,java]
-----
-@DomainService(nature = NatureOfService.DOMAIN)
-public interface HomePageProviderService {
- @Programmatic
- Object homePage();
-}
-----
-
-The default implementation is provided by `o.a.i.core.runtime.services.homepage.HomePageProviderServiceDefault`.
-
-
-
-== Registering the Service
-
-Assuming that the `configuration-and-annotation` services installer is configured (implicit if using the
-`AppManifest` to xref:rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' core
-implementation of `HomePageProviderService` is automatically registered (it is annotated with `@DomainService`) so no further
-configuration is required.
-
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_InteractionContext.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_InteractionContext.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_InteractionContext.adoc
deleted file mode 100644
index a59ce85..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_InteractionContext.adoc
+++ /dev/null
@@ -1,205 +0,0 @@
-[[_rgsvc_api_InteractionContext]]
-= `InteractionContext`
-: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 `InteractionContext` is a request-scoped domain service that is used to obtain the current
-`Interaction`.
-
-An `Interaction` generally consists of a single top-level `Execution`, either to invoke an action or to edit a
-property. If that top-level action or property uses xref:rgsvc.adoc#_rgsvc_api_WrapperFactory[`WrapperFactory`] to
-invoke child actions/properties, then those sub-executions are captured as a call-graph. The `Execution` is thus a
-graph structure.
-
-If a bulk action is performed (as per an action annotated using
-xref:rgant.adoc#_rgant-Action_invokeOn[`@Action#invokeOn()`]), then this will result in multiple ``Interaction``s, one
-per selected object (not one `Interaction` with multiple top-level ``Execution``s).
-
-
-It is possible for ``Interaction.Execution``s to be persisted; this is supported by the (non-ASF)
-http://github.com/isisaddons/isis-module-publishmq[Isis addons' publishmq] module, for example. Persistent
-``Interaction``s support several use cases:
-
-* they enable profiling of the running application (which actions are invoked then most often, what is their response
-time)
-
-* if auditing is configured (using either xref:rgsvc.adoc#_rgsvc_spi_AuditingService[auditing] or
-xref:rgsvc.adoc#_rgsvc_spi_AuditerService[`AuditerService`]), they provide better audit information, since the
-`Interaction.Execution` captures the 'cause' of an interaction and can be correlated to the audit records (the "effect"
-of the interaction) by way of the xref:rgcms.adoc#_rgcms_classes_mixins_HasTransactionId[`transactionId`]
-
-
-
-
-
-== API & Implementation
-
-The public API of the service consists of several related classes:
-
-* `InteractionContext` domain service itself:
-* `Interaction` class, obtainable from the `InteractionContext`
-* `Execution` class, obtainable from the `Interaction`.
-
-The `Execution` class itself is abstract; there are two subclasses, `ActionInvocation` and `PropertyEdit`.
-
-=== `InteractionContext`
-
-The public API of the `InteractionContext` domain service itself consists of simply:
-
-[source,java]
-----
-@RequestScoped
-public class InteractionContext {
- public Interaction getInteraction(); // <1>
-}
-----
-<1> Returns the currently active {@link Interaction} for this thread.
-
-This class is concrete (is also the implementation).
-
-
-=== `Interaction`
-
-The public API of the `Interaction` class consists of:
-
-[source,java]
-----
-public class Interaction {
- public UUID getTransactionId(); // <1>
- public Execution getPriorExecution(); // <2>
- public Execution getCurrentExecution(); // <3>
- public List<Execution> getExecutions(); // <4>
- public int next(final String sequenceId); // <5>
-}
-----
-<1> The unique identifier of this interaction. This will be the same value as held in `Command` (obtainable from xref:rgsvc.adoc#_rgsvc_api_CommandContext[`CommandContext`]).
-<2> The member `Execution` (action invocation or property edit) that preceded the current one.
-<3> The current execution.
-<4> * Returns a (list of) execution}s in the order that they were pushed. Generally there will be just one entry in this list, but additional entries may arise from the use of mixins/contributions when re-rendering a modified object.
-<5> Generates numbers in a named sequence. Used by the framework both to number successive interaction ``Execution``s and for events published by the xref:rgsvc.adoc#_rgsvc_spi_PublisherService[`PublisherService`].
-
-This class is concrete (is also the implementation).
-
-
-=== `Interaction.Execution`
-
-The `Interaction.Execution` (static nested) class represents an action invocation/property edit as a node in a
-call-stack execution graph. Sub-executions can be performed using the
-xref:rgsvc.adoc#_rgsvc_api_WrapperFactory[`WrapperFactory`].
-
-It has the following public API:
-
-[source,java]
-----
-public abstract class Execution {
- public Interaction getInteraction(); // <1>
- public InteractionType getInteractionType(); // <2>
- public String getMemberIdentifier(); // <3>
- public Object getTarget(); // <4>
-
- public String getTargetClass(); // <5>
- public String getTargetMember();
-
- public Execution getParent(); // <6>
- public List<Execution> getChildren();
-
- public AbstractDomainEvent getEvent(); // <7>
-
- public Timestamp getStartedAt(); // <8>
- public Timestamp getCompletedAt();
-
- public Object getReturned(); // <9>
- public Exception getThrew();
-
- public T getDto(); // <10>
-}
-----
-<1> The owning `Interaction`.
-<2> Whether this is an action invocation or a property edit.
-<3> A string uniquely identifying the action or property (similar to Javadoc syntax).
-<4> The object on which the action is being invoked or property edited. In the case of a mixin this will be the mixin object itself (rather than the mixed-in object).
-<5> A human-friendly description of the class of the target object, and of the name of the action invoked/property
-edited on the target object.
-<6> The parent action/property that invoked this action/property edit (if any), and any actions/property edits made in
-turn via the xref:rgsvc.adoc#_rgsvc_api_WrapperFactory[`WrapperFactory`].
-<7> The domain event fired via the xref:rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] representing the
-execution of this action invocation/property edit.
-<8> The date/time at which this execution started/completed.
-<9> The object returned by the action invocation/property edit, or the exception thrown. For `void` methods and for actions returning collections, the value will be `null`.
-<10> A DTO (instance of the xref:rgcms.adoc#_rgcms_schema_ixn["ixn" schema]) being a serializable representation of this action invocation/property edit.
-
-
-
-There are two concrete subclasses of `Execution`.
-
-The first is `ActionInvocation`, representing the execution of an action being invoked:
-
-[source,java]
-----
-public class ActionInvocation extends Execution {
- public List<Object> getArgs(); // <1>
-}
-----
-<1> The objects passed in as the arguments to the action's parameters. Any of these could be `null`.
-
-
-The second is `PropertyEdit`, and naturally enough represents the execution of a property being edited:
-
-[source,java]
-----
-public class PropertyEdit extends Execution {
- public Object getNewValue(); // <1>
-}
-----
-<1> The object used as the new value of the property. Could be `null` if the property is being cleared.
-
-
-
-== Interacting with the services
-
-Typically domain objects will have little need to interact with the `InteractionContext` and `Interaction` directly.
-The services are used within the framework however, primarily to support the
-xref:rgsvc.adoc#_rgsvc_spi_PublisherService[`PublisherService`] SPI, and to emit domain events over the
-xref:rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`].
-
-
-
-== 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 `InteractionContext` class is automatically registered (it is annotated with `@DomainService`)
-so no further configuration is required.
-
-The framework also takes responsibility for instantiating the `Interaction`, using the
-xref:rgsvc.adoc#_rgsvc_api_FactoryService[`FactoryService`].
-
-[NOTE]
-====
-Unlike the similar xref:rgsvc.adoc#_rgsvc_api_CommandContext[`CommandContext`] (discussed
-xref:rgsvc.adoc#__rgsvc_api_InteractionContext_Related-Classes[below]) there is no domain service to different
-implementations of `Interaction` to be used. If this were to be needed, then a custom implementation of
- xref:rgsvc.adoc#_rgsvc_api_FactoryService[`FactoryService`] could always used).
-====
-
-
-
-
-[[__rgsvc_api_InteractionContext_Related-Classes]]
-== Related Classes
-
-This service is very similar in nature to xref:rgsvc.adoc#_rgsvc_api_CommandContext[`CommandContext`], in that the
-`Interaction` object accessed through it is very similar to the `Command` object obtained from the `CommandContext`.
-The principle distinction is that while `Command` represents the __intention__ to invoke an action or edit a property,
-the `Interaction` (and contained ``Execution``s) represents the actual execution.
-
-Most of the time a `Command` will be followed directly by its corresponding `Interaction`. However, if the `Command`
-is annotated to run in the background (using xref:rgant.adoc#_rgant-Action_command[`@Action#commandExecuteIn()`], or
-is explicitly created through the xref:rgsvc.adoc#_rgsvc_api_BackgroundService[`BackgroundService`], then the actual
-interaction/execution is deferred until some other mechanism invokes the command (eg as described
-xref:ugbtb.adoc#_ugbtb_headless-access_BackgroundCommandExecution[here]).
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_IsisJdoSupport.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_IsisJdoSupport.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_IsisJdoSupport.adoc
deleted file mode 100644
index ec94584..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_IsisJdoSupport.adoc
+++ /dev/null
@@ -1,276 +0,0 @@
-[[_rgsvc_api_IsisJdoSupport]]
-= `IsisJdoSupport`
-: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 `IsisJdoSupport` service provides a number of general purpose methods for working with the JDO/DataNucleus objectstore. In general these act at a lower-level of abstraction than the APIs normally used (specifically, those of xref:rgsvc.adoc#_rgsvc_api_DomainObjectContainer[`DomainObjectContainer`]), but nevertheless deal with some of the most common use cases. For service also provides access to the underlying JDO `PersistenceManager` for full control.
-
-The following sections discuss the functionality provided by the service, broken out into categories.
-
-
-
-
-[[__rgsvc_api_IsisJdoSupport_executing-sql]]
-== Executing SQL
-
-You can use the `IsisJdoSupportService` to perform arbitrary SQL SELECTs or UPDATEs:
-
-[source,java]
-----
-public interface IsisJdoSupport {
- @Programmatic
- List<Map<String, Object>> executeSql(String sql);
- @Programmatic
- Integer executeUpdate(String sql);
- ...
-}
-----
-
-
-The `executeSql(...)` method allows arbitrary SQL `SELECT` queries to be submitted:
-
-[source,java]
-----
-List<Map<String, Object>> results = isisJdoSupport.executeSql("select * from custMgmt.customers");
-----
-
-The result set is automatically converted into a list of maps, where the map key is the column name.
-
-
-In a similar manner, the `executeUpdate(...)` allows arbitrary SQL ``UPDATE``s to be performed.
-
-[source,java]
-----
-int count = isisJdoSupport.executeUpdate("select count(*) from custMgmt.customers);
-----
-
-The returned value is the number of rows updated.
-
-[TIP]
-====
-As an alternative, consider using DataNucleus' link:http://www.datanucleus.org/products/accessplatform_4_0/jdo/jdoql_typesafe.html[type-safe JDO query API], discussed xref:rgsvc.adoc#__rgsvc_api_IsisJdoSupport_type-safe-query-api[below].
-====
-
-
-
-
-[[__rgsvc_api_IsisJdoSupport_type-safe-jdoql-queries]]
-== Type-safe JDOQL Queries
-
-DataNucleus provides an link:http://www.datanucleus.org/products/accessplatform_4_0/jdo/jdoql_typesafe.html[extension to JDO], so that JDOQL queries can be built up and executed using a set of type-safe classes.
-
-The types in question for type safe queries are not the domain entities, but rather are companion "Q..." query classes. These classes are generated dynamically by an link:https://www.jcp.org/en/jsr/detail?id=269[annotation processor] as a side-effect of compilation, one "Q..." class for each of the xref:rgant.adoc#_rgant-PersistenceCapable[`@PersistenceCapable`] domain entity in your application. For example, a `ToDoItem` domain entity will give rise to a `QToDoItem` query class. These "Q..." classes mirror the structure of domain entity, but expose properties that allow predicates to be built up for querying instances, as well as other functions in support of order by. group by and other clauses.
-
-[NOTE]
-====
-Most IDEs (including IntelliJ and Eclipse) enable annotation processing by default, as does Maven. The DataNucleus' link:http://www.datanucleus.org/products/accessplatform_4_0/jdo/jdoql_typesafe.html[documentation] offers some guidance on confirming that APT is enabled.
-====
-
-The `IsisJdoSupport` service offers two methods at different levels of abstraction:
-
-[source,java]
-----
-public interface IsisJdoSupport {
- @Programmatic
- <T> List<T> executeQuery(final Class<T> cls, final BooleanExpression be);
- @Programmatic
- <T> TypesafeQuery<T> newTypesafeQuery(Class<T> cls);
- ...
-}
-----
-
-
-The `executeQuery(...)` method supports the common case of obtaining a set of objects that meet some criteria, filtered using the provided `BooleanExpression`. To avoid memory leaks, the returned list is cloned and the underlying query closed.
-
-For example, in the (non-ASF) http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp] there is an implementation of `ToDoItemRepository` using type-safe queries. The following JDOQL:
-
-[source,sql]
-----
-SELECT
-FROM todoapp.dom.module.todoitem.ToDoItem
-WHERE atPath.indexOf(:atPath) == 0
- && complete == :complete")
-----
-
-can be expressed using type-safe queries as follows:
-
-[source,java]
-----
-public List<ToDoItem> findByAtPathAndCategory(final String atPath, final Category category) {
- final QToDoItem q = QToDoItem.candidate();
- return isisJdoSupport.executeQuery(ToDoItem.class,
- q.atPath.eq(atPath).and(
- q.category.eq(category)));
-}
-----
-
-[NOTE]
-====
-You can find the full example of the JDOQL equivalent in the xref:rgsvc.adoc#_rgsvc_api_DomainObjectContainer_generic-repository-api[`DomainObjectContainer`]
-====
-
-
-The `newTypesafeQuery(...)` method is a lower-level API that allows a type safe query to be instantiated for most sophisticated querying, eg using group by or order by clauses. See the
-DataNucleus link:http://www.datanucleus.org/products/accessplatform_4_0/jdo/jdoql_typesafe.html[documentation] for full details of using this.
-
-One thing to be aware of is that after the query has been executed, it should be closed, using `query.closeAll()`. If calling `query.executeList()` we also recommend cloning the resultant list first. The following utility method does both of these tasks:
-
-[source,java]
-----
-private static <T> List<T> executeListAndClose(final TypesafeQuery<T> query) {
- final List<T> elements = query.executeList();
- final List<T> list = Lists.newArrayList(elements);
- query.closeAll();
- return list;
-}
-----
-
-
-
-[[__rgsvc_api_IsisJdoSupport_fixture-support]]
-== Fixture support
-
-When writing xref:ugtst.adoc#_ugtst_integ-test-support[integration tests] you'll usually need to tear down some/all mutable transactional data before each test. One way to do that is to use the `executeUpdate(...)` method described xref:rgsvc.adoc#__rgsvc_api_IsisJdoSupport_executing-sql[above].
-
-Alternatively, the `deleteAll(...)` method will let your test delete all instances of a class without resorting to SQL:
-
-[source,java]
-----
-public interface IsisJdoSupport {
- @Programmatic
- void deleteAll(Class<?>... pcClasses);
- ...
-}
-----
-
-For example:
-
-[source,java]
-----
-public class TearDownAll extends FixtureScriptAbstract {
- @Override
- protected void execute(final ExecutionContext ec) {
- isisJdoSupport.deleteAll(Order.class);
- isisJdoSupport.deleteAll(CustomerAddress.class);
- isisJdoSupport.deleteAll(Customer.class);
- }
- @Inject
- IsisJdoSupport isisJdoSupport;
-}
-----
-
-[NOTE]
-====
-It can occasionally be the case that Apache Isis' internal adapter for the domain object is
-still in memory. JDO/DataNucleus seems to bump up the version of the object prior to its deletion,
-which under normal circumstances would cause Apache Isis to throw a concurrency exception. Therefore
-to prevent this from happening (ie to _force_ the deletion of all instances), concurrency checking
-is temporarily disabled while this method is performed.
-====
-
-
-
-
-[[__rgsvc_api_IsisJdoSupport_reloading-entities]]
-== Reloading entities
-
-An http://www.datanucleus.org/products/datanucleus/jdo/orm/relationships.html[(intentional) limitation] of JDO/DataNucleus is that persisting a child entity (in a 1:n bidirectional relationship) does not cause the parent's collection to be updated.
-
-[source,java]
-----
-public interface IsisJdoSupport {
- @Programmatic
- <T> T refresh(T domainObject);
- @Programmatic
- void ensureLoaded(Collection<?> collectionOfDomainObjects);
- ...
-}
-----
-
-
-
-The `refresh(T domainObject)` method can be used to reload the parent object (or indeed any object). Under the covers it uses the JDO `PersistenceManager#refresh(...)` API.
-
-
-For example:
-
-[source,java]
-----
-@DomainService(nature=NatureOfService.VIEW_CONTRIBUTIONS_ONLY)
-public class OrderContributions {
- public Order newOrder(final Customer customer) {
- Order order = newTransientInstance(Order.class);
- order.setCustomer(customer);
- container.persist(customer);
- container.flush(); // <1>
- isisJdoSupport.refresh(customer); // <2>
- return order;
- }
- @Inject
- DomainObjectContainer container;
- @Inject
- IsisJdoSupport isisJdoSupport;
-}
-----
-<1> flush to database, ensuring that the database row corresponding to the `Order` exists in its `order` table.
-<2> reload the parent (customer) from the database, so that its collection of ``Order``s is accurate.
-
-
-[NOTE]
-====
-The particular example that led to this method being added was a 1:m bidirectional relationship,
-analogous to `Customer 1<-->* Order`. Persisting the child `Order` object did not cause
-the parent ``Customer``'s collection of orders to be updated. In fact, JDO does not make any
-such guarantee to do so. Options are therefore either to maintain the collection in code, or to
-refresh the parent.
-====
-
-
-The `ensureLoaded(...)` method allows a collection of domain objects to be loaded from the database in a single hit. This can be valuable as a performance optimization to avoid multiple roundtrips to the database. Under the covers it uses the `PersistenceManager#retrieveAll(...)` API.
-
-
-
-
-
-[[__rgsvc_api_IsisJdoSupport_jdo-persistencemanager]]
-== JDO `PersistenceManager`
-
-The functionality provided by `IsisJdoSupport` focus only on the most common use cases. If you require more flexibility than this, eg for dynamically constructed queries, then you can use the service to access the underlying JDO `PersistenceManager` API:
-
-[source,java]
-----
-public interface IsisJdoSupport {
- @Programmatic
- PersistenceManager getJdoPersistenceManager();
- ...
-}
-----
-
-For example:
-
-[source,java]
-----
-public List<Order> findOrders(...) {
- javax.jdo.PersistenceManager pm = isisJdoSupport.getPersistenceManager();
-
- // knock yourself out...
-
- return someListOfOrders;
-}
-----
-
-
-
-
-== 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 `IsisJdoSupport` 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_JaxbService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_JaxbService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_JaxbService.adoc
deleted file mode 100644
index 755895a..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_JaxbService.adoc
+++ /dev/null
@@ -1,68 +0,0 @@
-[[_rgsvc_api_JaxbService]]
-= `JaxbService`
-: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 `JaxbService` allows instances of JAXB-annotated classes to be marshalled to XML and
-unmarshalled from XML back into domain objects.
-
-
-
-
-
-[[__rgsvc_api_JaxbService_api-and-implementation]]
-== API & Implementation
-
-The API defined by `JaxbService` is:
-
-[source,java]
-----
-public interface JaxbService {
- @Programmatic
- <T> T fromXml(Class<T> domainClass, String xml); // <1>
- @Programmatic
- public String toXml(final Object domainObject); // <2>
- public enum IsisSchemas { // <3>
- INCLUDE, IGNORE
- }
- @Programmatic
- public Map<String, String> toXsd(final Object domainObject, final IsisSchemas isSchemas);} // <4>
-}
-----
-<1> unmarshalls the XML into an instance of the class.
-<2> marshalls the domain object into XML
-<3> whether to include or exclude the Isis schemas in the generated map of XSDs. Discussed further below.
-<4> generates a map of each of the schemas referenced; the key is the schema namespace, the value is the XML of the schema itself.
-
-With respect to the `IsisSchemas` enum: a JAXB-annotated domain object will live in its own XSD namespace and may
-reference multiple other XSD schemas. In particular, many JAXB domain objects will reference the
-xref:rgcms.adoc#_rgcms_schema[common Isis schemas] (for example the `OidDto` class that represents a reference to
-a persistent entity). The enum indicates whether these schemas should be included or excluded from the map.
-
-Isis provides a default implementation of the service, `o.a.i.schema.services.jaxb.JaxbServiceDefault`.
-
-
-
-== Usage within the framework
-
-This service is provided as a convenience for applications, but is also used internally by the framework to
-xref:rgant.adoc#_rgant-XmlRootElement[`@XmlRootElement`]-annotated
-xref:ugbtb.adoc#_ugbtb_view-models[view models]. The functionality to download XML and XSD schemas is also
-exposed in the UI through mixins to xref:rgcms.adoc#_rgcms_classes_mixins_Dto[`Dto`] interface.
-
-
-
-== 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 `JaxbService` 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_LayoutService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_LayoutService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_LayoutService.adoc
deleted file mode 100644
index d443615..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_LayoutService.adoc
+++ /dev/null
@@ -1,107 +0,0 @@
-[[_rgsvc_api_LayoutService]]
-= `LayoutService`
-: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 `LayoutService` provides the ability to obtain the XML layout for a single domain object or for all domain
-objects. This functionality is surfaced through the user interface through a related xref:__rgsvc_api_LayoutService_related-mixins-and-menus[mixin and menu action].
-
-
-
-[[__rgsvc_api_LayoutService_api-and-implementation]]
-== API & Implementation
-
-The API defined by `LayoutService` is:
-
-[source,java]
-----
-public interface LayoutService {
- String toXml(Class<?> domainClass, Style style); // <1>
- byte[] toZip(Style style); // <2>
-}
-----
-<1> Returns the serialized XML form of the layout (grid) for the specified domain class, in specified style (discussed below).
-<2> Returns (a byte array) of a zip of the serialized XML of the layouts (grids), for all domain entities and view models.
-
-The `Style` enum is defined as:
-
-[source,java]
-----
-enum Style {
- CURRENT,
- COMPLETE,
- NORMALIZED,
- MINIMAL
-}
-----
-
-The `CURRENT` style corresponds to the layout already loaded for the domain class, typically from an already persisted
-`layout.xml` file. The other three styles allow the developer to choose how much metadata is to be specified in the
-XML, and how much (if any) will be obtained elsewhere, typically from annotations in the metamodel (but also from
-`.layout.json` file if present). The table below summarises the choices:
-
-.Table caption
-[cols="<.>,^.>,^.>,^.>", options="header"]
-|===
-
-| Style
-|xref:rgant.adoc#_rgant-MemberGroupLayout[`@MemberGroupLayout`]
-| xref:rgant.adoc#_rgant-MemberOrder[`@MemberOrder`]
-| xref:rgant.adoc#_rgant-ActionLayout[`@ActionLayout`], xref:rgant.adoc#_rgant-PropertyLayout[`@PropertyLayout`], xref:rgant.adoc#_rgant-CollectionLayout[`@CollectionLayout`]
-
-
-|`COMPLETE`
-|serialized as XML
-|serialized as XML
-|serialized as XML
-
-
-|`NORMALIZED`
-|serialized as XML
-|serialized as XML
-|not in the XML
-
-
-|`MINIMAL`
-|serialized as XML
-|not in the XML
-|not in the XML
-
-|===
-
-As a developer, you therefore have a choice as to how you provide the metadata required for customised layouts:
-
-* if you want all layout metadata to be read from the `.layout.xml` file, then download the "complete" version, and copy the file alongside the domain class. You can then remove all `@MemberGroupLayout`, `@MemberOrder`, `@ActionLayout`, `@PropertyLayout` and `@CollectionLayout` annotations from the source code of the domain class.
-
-* if you want to use layout XML file to describe the grid (columns, tabs etc) and specify which object members are associated with those regions of the grid, then download the "normalized" version. You can then remove the `@MemberGroupLayout` and `@MemberOrder` annotations from the source code of the domain class, but retain the `@ActionLayout`, `@PropertyLayout` and `@CollectionLayout` annotations.
-
-* if you want to use layout XML file ONLY to describe the grid, then download the "minimal" version. The grid regions will be empty in this version, and the framework will use the `@MemberOrder` annotation to bind object members to those regions. The only annotation that can be safely removed from the source code with this style is the `@MemberGroupLayout` annotation.
-
-
-
-
-[[__rgsvc_api_LayoutService_related-mixins-and-menus]]
-== Related Mixins and Menus
-
-The service's functionality is exposed in the UI through a mixin (per object) and a menu action (for all objects):
-
-* the xref:rgant.adoc#_rgcms_classes_mixins_Object[`Object` mixin] provides the ability to download the XML layout for
-any domain object (entity or view model).
-
-* the `LayoutServiceMenu` provides the ability to download all XML layouts as a single ZIP file (in any of the
-three styles).
-
-The XML can then be copied into the codebase of the application, and annotations in the domain classes removed as
-desired.
-
-
-
-[[__rgsvc_api_LayoutService_related-domain-services]]
-== Related Domain Services
-
-The xref:rgsvc.adoc#_rgsvc_spi_GridService[`GridService`] is responsible for loading and normalizing layout XML for
-a domain class. It in turn uses the xref:rgsvc.adoc#_rgsvc_spi_GridLoaderService[`GridLoaderService`] and xref:rgsvc.adoc#_rgsvc_spi_GridSystemService[`GridSystemService`]
-services.
\ 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_MementoService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_MementoService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_MementoService.adoc
deleted file mode 100644
index d52c43b..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_MementoService.adoc
+++ /dev/null
@@ -1,146 +0,0 @@
-[[_rgsvc_api_MementoService]]
-= `MementoService` (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 `MementoService` was originally introduced to simplify the implementation of
-xref:ugbtb.adoc#_ugbtb_view-models[ViewModel]s which are required by the framework to return string representation of
-all of their backing state, moreover which is safe for use within a URL. This usage is deprecated; use xref:ugbtb.adoc#_ugbtb_view-models_jaxb[JAXB view models] instead.
-
-The service can also be used to create a memento of arbitrary objects, however this usage is also deprecated. (Prior
-to `1.13.0` it was used internally by the core implementation of
-xref:rgsvc.adoc#_rgsvc_api_BackgroundService[`BackgroundService`] to capture the state of action invocations so that
-they can be executed by a background process; this is now done using
-xref:rgfis.adoc#_rgfis_spi_CommandDtoServiceInternal[`CommandDtoServiceInternal`]).
-
-
-[NOTE]
-====
-As of `1.13.0` this service is deprecated, replaced by internal domain services.
-====
-
-
-
-
-== API & Implementation
-
-The API defined by `MementoService` is:
-
-[source,java]
-----
-@Deprecated
-public interface MementoService {
- @Deprecated
- public static interface Memento {
- public Memento set(String name, Object value);
- public <T> T get(String name, Class<T> cls);
- public String asString();
- public Set<String> keySet();
- }
- public Memento create();
- public Memento parse(final String str);
- public boolean canSet(Object input);
-}
-----
-
-The core framework provides a default implementation of this API, namely
-`o.a.i.c.r.services.memento.MementoServiceDefault`. The string returned (from `Memento#asString()`) is a base-64 URL
-encoded representation of the underlying format (an XML string).
-
-[NOTE]
-====
-In fact, the `MementoServiceDefault` implementation does provide a mechanism to disable the URL encoding, but this is
-not part of the `MementoService` public API. Note also that the encoding method is not pluggable.
-====
-
-The types of objects that are supported by the `MementoService` are implementation-specific, but would typically
-include all the usual value types as well as Apache Isis' `Bookmark` class (to represent references to arbitrary
-entities). Nulls can also be set.
-
-In the case of the default implementation provided by the core framework, the types supported are:
-
-* `java.lang.String`
-* `java.lang.Boolean`, `boolean`
-* `java.lang.Byte`, `byte`
-* `java.lang.Short`, `short`
-* `java.lang.Integer`, `int`
-* `java.lang.Long`, `long`
-* `java.lang.Float`, `float`
-* `java.lang.Double`, `double`
-* `java.lang.Character`, `char`
-* `java.math.BigDecimal`
-* `java.math.BigInteger`
-* `org.joda.time.LocalDate`
-* `org.apache.isis.applib.services.bookmark.Bookmark`
-
-If using another implementation, the `canSet(...)` method can be used to check if the candidate object's type is supported.
-
-
-
-== Usage
-
-As noted in the introduction, a common use case for this service is in the implementation of the xref:rgcms.adoc#_rgcms_classes_super_AbstractViewModel[`ViewModel`] interface.
-
-[TIP]
-====
-Rather than implementing `ViewModel`, it's usually easier to annotate your view models with xref:rgant.adoc#_rgant-ViewModel[`@ViewModel`] (or equivalently xref:rgant.adoc#_rgant-DomainObject_nature[`@DomainObject#nature=EXTERNAL_ENTITY`] or xref:rgant.adoc#_rgant-DomainObject_nature[`@DomainObject#nature=INMEMORY_ENTITY`].
-====
-
-For example, suppose you were implementing a view model that represents an external entity in a SOAP web service. To access this service the view model needs to store (say) the hostname, port number and an id to the object.
-
-Using an injected `MementoService` the view model can roundtrip to and from this string, thus implementing the `ViewModel` API:
-
-[source,java]
-----
-public class ExternalEntity implements ViewModel {
- private String hostname;
- private int port;
- private String id;
- public String viewModelMemento() { // <1>
- return mementoService.create()
- .set("hostname", hostname)
- .set("port", port)
- .set("id", id)
- .asString();
- }
- public void viewModelInit(String mementoStr) { // <2>
- Memento memento = mementoService.parse(mementoStr);
- hostname = memento.get("hostname", String.class);
- port = memento.get("port", int.class);
- id = memento.get("id", String.class);
- ...
- @Inject
- MementoService mementoService;
-}
-----
-<1> part of the `ViewModel` API
-<2> part of the `ViewModel` API
-
-
-
-
-
-== Related Services
-
-(Prior to `1.13.0`), the memento service was used by the xref:rgsvc.adoc#_rgsvc_api_CommandContext[`CommandContext`]
-service and also
-xref:rgsvc.adoc#_rgsvc_spi_BackgroundCommandService[`BackgroundCommandService`]. These both use a memento to capture a
-representation of an action invocation. This is now done using
-xref:rgfis.adoc#_rgfis_spi_CommandDtoServiceInternal[`CommandDtoServiceInternal`].
-
-
-
-
-== 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 `MementoService` 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_MessageService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_MessageService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_MessageService.adoc
deleted file mode 100644
index 2acc924..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_MessageService.adoc
+++ /dev/null
@@ -1,78 +0,0 @@
-[[_rgsvc_api_MessageService]]
-= `MessageService`
-: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 `MessageService` allows domain objects to raise information, warning or error messages. These messages can either be simple strings, or can be translated.
-
-[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 `MessageService` is:
-
-[source,java]
-----
-public interface MessageService {
-
- void informUser(String message); // <1>
- String informUser(TranslatableString message, Class<?> contextClass, String contextMethod); // <2>
-
- void warnUser(String message); // <3>
- String warnUser(TranslatableString message, Class<?> contextClass, String contextMethod); // <4>
-
- void raiseError(String message); // <5>
- String raiseError(TranslatableString message, Class<?> contextClass, String contextMethod); // <6>
- ...
-}
-----
-<1> display as a transient message to the user (not requiring acknowledgement). In the xref:ugvw.adoc#[Wicket viewer] this is implemented as a toast that automatically disappears after a period of time.
-<2> ditto, but with translatable string, for xref:ugbtb.adoc#_ugbtb_i18n[i18n support].
-<3> warn the user about a situation with the specified message. In the xref:ugvw.adoc#[Wicket viewer] this is implemented as a toast that must be closed by the end-user.
-<4> ditto, but with translatable string, for i18n support.
-<5> show the user an unexpected application error. In the xref:ugvw.adoc#[Wicket viewer] this is implemented as a toast (with a different colour) that must be closed by the end-user.
-<6> ditto, but with translatable string, for i18n support.
-
-
-
-For example:
-
-[source,java]
-----
-public Order addItem(Product product, @ParameterLayout(named="Quantity") int quantity) {
- if(productRepository.stockLevel(product) == 0) {
- messageService.warnUser(
- product.getDescription() + " out of stock; order fulfillment may be delayed");
- }
- ...
-}
-----
-
-
-
-== Implementation
-
-The core framework provides a default implementation of this service (`o.a.i.core.runtime.services.message.MessageServiceInternalDefault`).
-
-
-
-
-== 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 `MessageService` 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_MetamodelService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_MetamodelService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_MetamodelService.adoc
deleted file mode 100644
index f1d5b8c..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_MetamodelService.adoc
+++ /dev/null
@@ -1,68 +0,0 @@
-[[_rgsvc_api_MetaModelService]]
-= `MetaModelService3`
-: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 `MetaModelService3` service provides access to a number of aspects of Apache Isis' internal metamodel.
-
-
-== API
-
-
-The API defined by the service is:
-
-[source,java]
-----
-public interface MetaModelService2 {
- Class<?> fromObjectType(String objectType); // <1>
- String toObjectType(Class<?> domainType); // <2>
- void rebuild(Class<?> domainType); // <3>
- List<DomainMember> export(); // <4>
-
- enum Sort { // <5>
- VIEW_MODEL, JDO_ENTITY, DOMAIN_SERVICE,
- MIXIN, VALUE, COLLECTION, UNKNOWN;
- }
- enum Mode {
- STRICT,
- RELAXED
- }
- Sort sortOf(Class<?> domainType); // <6>
- Sort sortOf(Bookmark bookmark);
- Sort sortOf(Class<?> domainType, Mode mode);
- Sort sortOf(Bookmark bookmark, Mode mode);
-}
-----
-<1> reverse lookup of a domain class' object type
-<2> lookup of a domain class' object type
-<3> invalidate and rebuild the internal metadata (an `ObjectSpecification`) for the specified domain type.
-<4> returns a list of representations of each of member of each domain class.
-<5> what sort of object a domain type is (or bookmark) represents
-<6> whether to throw an exception or return `Sort.UNKNOWN` if the object type is not recognized. (The overloads with no `Mode` parameter default to strict mode).
-
-
-== Implementation
-
-The framework provides a default implementation of this service, `o.a.i.c.m.services.metamodel.MetaModelServiceDefault`.
-
-
-== 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 `MetamodelService` 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 `MetaModelServiceMenu` provides a method to download all domain members as a CSV. Internally
-this calls `MetaModelService#export()`. Under the covers this uses the API provided by the
-xref:rgsvc.adoc#_rgsvc_api_ApplicationFeatureRepository[`ApplicationFeatureRepository`] domain service.
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_MetricsService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_MetricsService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_MetricsService.adoc
deleted file mode 100644
index a7237f6..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_MetricsService.adoc
+++ /dev/null
@@ -1,49 +0,0 @@
-[[_rgsvc_api_MetricsService]]
-= `MetricsService`
-: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 `MetricsService` is a request-scoped domain service that hooks into the JDO/DataNucleus
-ObjectStore to provide a number of counters relating to numbers of object loaded, dirtied etc.
-
-The service is used by the xref:rgsvc.adoc#_rgsvc_api_InteractionContext[`InteractionContext`] domain service (to populate the DTO held by the `Interaction.Execution`) and also by the (internal) xref:rgfis.adoc#_rgfis_spi_PublishingServiceInternal[`PublishingServiceInternal`] domain service (to populate
-the `PublishedObjects` class.
-
-
-== API & Implementation
-
-The API of the service is:
-
-[source,java]
-----
-@RequestScoped
-public interface MetricsService {
- int numberObjectsLoaded(); // <1>
- int numberObjectsDirtied(); // <2>
- int numberObjectPropertiesModified(); // <3>
-}
-----
-<1> The number of objects that have, so far in this request, been loaded from the database. Corresponds to the number of times that `javax.jdo.listener.LoadLifecycleListener#postLoad(InstanceLifecycleEvent)` is fired.
-<2> The number of objects that have, so far in this request, been dirtied/will need updating in the database); a good measure of the footprint of the interaction. Corresponds to the number of times that `javax.jdo.listener.DirtyLifecycleListener#preDirty(InstanceLifecycleEvent)` callback is fired.
-<3> The number of individual properties of objects that were modified; a good measure of the amount of work being done in the interaction. Corresponds to the number of times that the xref:rgsvc.adoc#_rgsvc_spi_AuditingService[`AuditingService`]'s (or
-xref:rgsvc.adoc#_rgsvc_spi_AuditerService[`AuditerService`]'s) `audit(...)` method will be called as the transaction
-completes.
-
-The framework provides a default implementation of this API, namely `o.a.i.c.r.s.metrics.MetricsServiceDefault`.
-
-
-== 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 `MetricsService` class is automatically registered (it is annotated with `@DomainService`)
-so no further configuration is required.
-
-
-== Related Services
-
-The xref:rgsvc.adoc#_rgsvc_spi_PublisherService[`PublisherService`] also captures the metrics gathered by the
-`MetricsService` and publishes them as part of the `PublishedObjects` class (part of its SPI).