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 2015/12/03 19:15:34 UTC
[16/51] [abbrv] isis git commit: ISIS-1243: removing "manpage" from
all rgsvc .adoc pages.
http://git-wip-us.apache.org/repos/asf/isis/blob/88993cf3/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_manpage-DomainObjectContainer_validation-api.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_manpage-DomainObjectContainer_validation-api.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_manpage-DomainObjectContainer_validation-api.adoc
deleted file mode 100644
index b6ad616..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_manpage-DomainObjectContainer_validation-api.adoc
+++ /dev/null
@@ -1,26 +0,0 @@
-[[_rgsvc-api_manpage-DomainObjectContainer_validation-api]]
-= Validation API
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-
-The validation API allows a domain object to programmatically validate itself or any other domain object. Specifically, this means the validating the current state of all properties, as well as any object-level validation defined by xref:rg.adoc#_rg_methods_reserved_manpage-validate[`validate()`].
-
-The API provided is:
-
-[source,java]
-----
-public interface DomainObjectContainer {
- @Programmatic
- boolean isValid(Object domainObject);
- @Programmatic
- String validate(Object domainObject);
- ...
-}
-----
-
-If an object is changed by editing its properties, then (using the xref:ugvw.adoc#[Wicket viewer] at least) Apache Isis will check that the state of the object is valid. There is currently however no equivalent guarantee for actions.
-
-The intent of this API was (originally at least) to provide a fallback whereby actions could at least be able to perform this validation programmatically (eg in their own xref:rg.adoc#_rg_methods_prefixes_manpage-validate[`validate...()`] or xref:rg.adoc#_rg_methods_prefixes_manpage-disable[`disable...()`] methods. However, this feature should be considered experimental; your mileage may vary.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/88993cf3/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_manpage-EmailService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_manpage-EmailService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_manpage-EmailService.adoc
deleted file mode 100644
index 3a7cef9..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_manpage-EmailService.adoc
+++ /dev/null
@@ -1,95 +0,0 @@
-[[_rgsvc-api_manpage-EmailService]]
-= `EmailService`
-: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 `EmailService` provides the ability to send HTML emails, with attachments, to one or more recipients.
-
-Apache Isis provides a default implementation to send emails using an external SMTP provider. Note that this must be configured (using a number of configuration properties) before it can be used. The that sends email as an HTML message, using an external SMTP provider.
-
-
-
-== API & Implementation
-
-The API for the service is:
-
-[source,java]
-----
-public interface EmailService {
- @Programmatic
- boolean send( // <1>
- List<String> to, List<String> cc, List<String> bcc, // <2>
- String subject,
- String body, // <3>
- DataSource... attachments);
- @Programmatic
- boolean isConfigured(); // <4>
- }
-----
-<1> is the main API to send the email (and optional attachments). Will return `false` if failed to send
-<2> pass either `null` or `Collections.emptyList()` if not required
-<3> should be HTML text
-<4> indicates whether the implementation was configured and initialized correctly. If this returns `false` then any attempt to call `send(...)` will fail.
-
-As noted in the introduction, the core framework provides a default implementation (`EmailServiceDefault`) that sends email as an HTML message, using an external SMTP provider.
-
-
-
-== Configuration
-
-To use this service the following properties must be configured:
-
-* `isis.service.email.sender.address`
-* `isis.service.email.sender.password`
-
-and these properties may optionally be configured (each has a default to use gmail, documented xref:rg.adoc#_rg_runtime_configuring-core[here]):
-
-* `isis.service.email.sender.hostname`
-* `isis.service.email.port`
-* `isis.service.email.tls.enabled`
-
-These configuration properties can be specified either in `isis.properties` or in an xref:ugbtb.adoc#_ugbtb_deployment_externalized-configuration[external configuration file].
-
-If prototyping (that is, running the app using `org.apache.isis.WebServer`), the configuration properties can also be specified as system properties. For example, if you create a test email account on gmail, you can configure the service using:
-
-[source,ini]
-----
--Disis.service.email.sender.address=xxx@gmail.com -Disis.service.email.sender.password=yyy
-----
-
-where "xxx" is the gmail user account and "yyy" is its password
-
-
-
-
-== Alternative Implementations
-
-If you wish to write an alternative implementation, be aware that it should process the message body as HTML (as opposed to plain text or any other format).
-
-Also, note that (unlike most Apache Isis domain services) the implementation is also instantiated and injected by Google Guice. This is because `EmailService` is used as part of the xref:ugvw.adoc#_ugvw_features_user-registration[user registration] functionality and is used by Wicket pages that are accessed outside of the usual Apache Isis runtime. This implies a couple of additional constraints:
-
-* first, implementation class should also be annotated with `@com.google.inject.Singleton`
-* second, there may not be any Apache Isis session running. (If necessary, one can be created on the fly using `IsisContext.doInSession(...)`)
-
-To ensure that your alternative implementation takes the place of the default implementation, register it explicitly in `isis.properties`.
-
-
-
-== Registering the Services
-
-Assuming that the `configuration-and-annotation` services installer is configured (implicit if using the
-`AppManifest` to xref:rg.adoc#_rg_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' core
-implementation of `EmailService` 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
-further in this xref:ug.adoc#_ug_how-tos_replacing-default-service-implementations["how to"] tip).
-
-
-== Related Services
-
-The email service is used by the xref:rgsvc.adoc#_rgsvc-spi_manpage-EmailNotificationService[`EmailNotificationService`] which is, in turn, used by xref:rgsvc.adoc#_rgsvc-spi_manpage-UserRegistrationService[`UserRegistrationService`].
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/88993cf3/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_manpage-EventBusService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_manpage-EventBusService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_manpage-EventBusService.adoc
deleted file mode 100644
index 05eec70..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_manpage-EventBusService.adoc
+++ /dev/null
@@ -1,405 +0,0 @@
-[[_rgsvc-api_manpage-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_manpage-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_manpage-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:rg.adoc#_rg_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:rg.adoc#_rg_classes_super_manpage-AbstractSubscriber[`AbstractSubscriber`] class automatically performs this
-registration. As a convenience, (as of `1.11.0-SNAPSHOT`) 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.EventHandle
- 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_manpage-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_manpage-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_manpage-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_manpage-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_manpage-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_manpage-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:rg.adoc#_rg_runtime_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:rg.adoc#_rg_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
-further in this xref:ug.adoc#_ug_how-tos_replacing-default-service-implementations["how to"] tip).
-
-
-
-
-== 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_manpage-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/88993cf3/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_manpage-FixtureScriptsDefault.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_manpage-FixtureScriptsDefault.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_manpage-FixtureScriptsDefault.adoc
deleted file mode 100644
index 0e506bb..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_manpage-FixtureScriptsDefault.adoc
+++ /dev/null
@@ -1,50 +0,0 @@
-[[_rgsvc-api_manpage-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:rg.adoc#_rg_classes_super_manpage-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_manpage-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_manpage-FixtureScriptsSpecificationProvider[`FixtureScriptsSpecificationProvider`] rather than subclassing xref:rg.adoc#_rg_classes_super_manpage-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:rg.adoc#_rg_classes_super_manpage-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:rg.adoc#_rg_runtime_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_manpage-FixtureScriptsSpecificationProvider[`FixtureScriptsSpecificationProvider`].
http://git-wip-us.apache.org/repos/asf/isis/blob/88993cf3/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_manpage-GuiceBeanProvider.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_manpage-GuiceBeanProvider.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_manpage-GuiceBeanProvider.adoc
deleted file mode 100644
index fb80df6..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_manpage-GuiceBeanProvider.adoc
+++ /dev/null
@@ -1,91 +0,0 @@
-[[_rgsvc-api_manpage-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_manpage-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:rg.adoc#_rg_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
-further in this xref:ug.adoc#_ug_how-tos_replacing-default-service-implementations["how to"] tip).
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/88993cf3/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_manpage-IsisJdoSupport.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_manpage-IsisJdoSupport.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_manpage-IsisJdoSupport.adoc
deleted file mode 100644
index a6220bb..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_manpage-IsisJdoSupport.adoc
+++ /dev/null
@@ -1,276 +0,0 @@
-[[_rgsvc-api_manpage-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_manpage-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_manpage-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_manpage-IsisJdoSupport_type-safe-query-api[below].
-====
-
-
-
-
-[[_rgsvc-api_manpage-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_manpage-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_manpage-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_manpage-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_manpage-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_manpage-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:rg.adoc#_rg_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
-further in this xref:ug.adoc#_ug_how-tos_replacing-default-service-implementations["how to"] tip).
http://git-wip-us.apache.org/repos/asf/isis/blob/88993cf3/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_manpage-JaxbService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_manpage-JaxbService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_manpage-JaxbService.adoc
deleted file mode 100644
index aa94e08..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_manpage-JaxbService.adoc
+++ /dev/null
@@ -1,67 +0,0 @@
-[[_rgsvc-api_manpage-JaxbService]]
-= `JaxbService` (`1.11.0-SNAPSHOT`)
-: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` (`1.11.0-SNAPSHOT`) allows instances of JAXB-annotated classes to be marshalled to XML and
-unmarshalled from XML back into domain objects.
-
-
-
-
-
-[[_rgsvc-api_manpage-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:rg.adoc#_rg_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_more-advanced_view-models[view models]. The functionality to download XML and XSD schemas is also
-exposed in the UI through mixins to xref:rg.adoc#_rg_classes_roles_manpage-Dto[`Dto`] interface.
-
-
-
-== Registering the Service
-
-Assuming that the `configuration-and-annotation` services installer is configured (implicit if using the
-`AppManifest` to xref:rg.adoc#_rg_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
-further in this xref:ug.adoc#_ug_how-tos_replacing-default-service-implementations["how to"] tip).
-
http://git-wip-us.apache.org/repos/asf/isis/blob/88993cf3/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_manpage-MementoService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_manpage-MementoService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_manpage-MementoService.adoc
deleted file mode 100644
index d2448e4..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_manpage-MementoService.adoc
+++ /dev/null
@@ -1,131 +0,0 @@
-[[_rgsvc-api_manpage-MementoService]]
-= `MementoService`
-: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_more-advanced_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.
-
-However, it can also be used to create a memento of arbitrary objects. Indeed, it is used internally by the core implementation of xref:rgsvc.adoc#_rgsvc-api_manpage-BackgroundService[`BackgroundService`] to capture the state of action invocations so that they can be executed by a background process.
-
-
-
-
-== API & Implementation
-
-The API defined by `MementoService` is:
-
-[source,java]
-----
-public interface MementoService {
- public static interface Memento {
- @Programmatic
- public Memento set(String name, Object value);
- @Programmatic
- public <T> T get(String name, Class<T> cls);
- @Programmatic
- public String asString();
- public Set<String> keySet();
- }
- @Programmatic
- public Memento create();
- @Programmatic
- public Memento parse(final String str);
- @Programmatic
- public boolean canSet(Object input);
-}
-----
-
-The core framework provides a default implementation of this API, namely `o.a.i.core.runtime.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.
-
-However, you are of course free to write some other implementation of `MementoService`, perhaps based on `MementoServiceDefault` code if you wish.
-====
-
-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:rg.adoc#_rg_classes_super_manpage-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
-
-The memento service is used by the xref:rgsvc.adoc#_rgsvc-api_manpage-CommandContext[`CommandContext`] service and also xref:rgsvc.adoc#_rgsvc-spi_manpage-BackgroundCommandService[`BackgroundCommandService`]. These both use a memento to capture a representation of an action invocation.
-
-
-
-
-== Registering the Service
-
-Assuming that the `configuration-and-annotation` services installer is configured (implicit if using the
-`AppManifest` to xref:rg.adoc#_rg_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
-further in this xref:ug.adoc#_ug_how-tos_replacing-default-service-implementations["how to"] tip).
http://git-wip-us.apache.org/repos/asf/isis/blob/88993cf3/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_manpage-MetamodelService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_manpage-MetamodelService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_manpage-MetamodelService.adoc
deleted file mode 100644
index d63ff60..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_manpage-MetamodelService.adoc
+++ /dev/null
@@ -1,42 +0,0 @@
-[[_rgsvc-api_manpage-MetamodelService]]
-= `MetamodelService`
-: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 `MetaModelService` provides access (albeit currently extremely limited) to aspects of Apache Isis' internal metamodel.
-
-Currently this is limited to looking up the object type (as specified in xref:rgant.adoc#_rgant-DomainObject_objectType[`@DomainObject#objectType()`] and equivalent mechanisms, and as used in xref:rgsvc.adoc#_rgsvc-api_manpage-BookmarkService[`Bookmark`]s and elsewhere) from an object's class, and vice versa. In the future we expect other aspects of the metamodel to also be formally surfaced through this API.
-
-
-== API & Implementation
-
-The API defined by the service is:
-
-[source,java]
-----
-public interface MetaModelService {
- @Programmatic
- Class<?> fromObjectType(final String objectType); // <1>
- @Programmatic
- String toObjectType(final Class<?> domainType); // <2>
-}
-----
-<1> reverse lookup of a domain class' object type
-<2> lookup of a domain class' object type
-
-
-
-
-== Registering the Service
-
-Assuming that the `configuration-and-annotation` services installer is configured (implicit if using the
-`AppManifest` to xref:rg.adoc#_rg_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
-further in this xref:ug.adoc#_ug_how-tos_replacing-default-service-implementations["how to"] tip).
http://git-wip-us.apache.org/repos/asf/isis/blob/88993cf3/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_manpage-QueryResultsCache.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_manpage-QueryResultsCache.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_manpage-QueryResultsCache.adoc
deleted file mode 100644
index 30bc031..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_manpage-QueryResultsCache.adoc
+++ /dev/null
@@ -1,126 +0,0 @@
-[[_rgsvc-api_manpage-QueryResultsCache]]
-= `QueryResultsCache`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-
-The purpose of the `QueryResultsCache` is to improve response times to the user, by providing a short-term (link:../../more-advanced-topics/how-to-09-020-How-to-write-a-typical-domain-service.html[request-scoped]) cache of the value of some (safe or idempotent) method call. This will typically be as the result of running a query, but could be any expensive operation.
-
-Caching such values is useful for code that loops "naively" through a bunch of stuff, performing an expensive operation each time. If the data is such that the same expensive operation is made many times, then the query cache is a perfect fit.
-
-
-[NOTE]
-====
-This service was inspired by similar functionality that exists in relational databases, for example Sybase's http://infocenter.sybase.com/help/index.jsp?topic=/com.sybase.dc20023_1251/html/optimizer/X43480.htm[subquery results cache] and Oracle's http://www.dba-oracle.com/oracle11g/oracle_11g_result_cache_sql_hint.htm[result_cache] hint.
-====
-
-
-
-== API & Implementation
-
-The API defined by `QueryResultsCache` is:
-
-[source,java]
-----
-@RequestScoped
-public class QueryResultsCache {
- public static class Key {
- public Key(Class<?> callingClass, String methodName, Object... keys) {...}
- public Class<?> getCallingClass() { ... }
- public String getMethodName() { ... }
- public Object[] getKeys() { ... }
- }
- public static class Value<T> {
- public Value(T result) { ... }
- private T result;
- public T getResult() {
- return result;
- }
- }
- @Programmatic
- public <T> T execute(
- final Callable<T> callable,
- final Class<?> callingClass, final String methodName, final Object... keys) { ... }
- @Programmatic
- public <T> T execute(final Callable<T> callable, final Key cacheKey) { ... }
- @Programmatic
- public <T> Value<T> get(
- final Class<?> callingClass, final String methodName, final Object... keys) { ... }
- @Programmatic
- public <T> Value<T> get(final Key cacheKey) { ... }
- @Programmatic
- public <T> void put(final Key cacheKey, final T result) { ... }
-}
-----
-
-This class (`o.a.i.applib.services.queryresultscache.QueryResultsCache`) is also the implementation.
-
-
-
-
-== Usage
-
-Suppose that there's a `TaxService` that calculates tax on `Taxable` items, with respect to some `TaxType`, and for a given `LocalDate`. To calculate tax it must run a database query and then perform some additional calculations.
-
-Our original implementation is:
-
-[source,java]
-----
-@DomainService
-public class TaxService {
- public BigDecimal calculateTax(
- final Taxable t, final TaxType tt, final LocalDate d) {
- // query against DB using t, tt, d
- // further expensive calculations
- }
-}
-----
-
-Suppose now that this service is called in a loop, for example iterating over a bunch of orders, where several of those orders are for the same taxable products, say. In this case the result of the calculation would always be the same for any given product.
-
-We can therefore refactor the method to use the query cache as follows:
-
-[source,java]
-----
-public class TaxService {
- public BigDecimal calculateTax(
- final Taxable t, final TaxType tt, final LocalDate d) {
- return queryResultsCache.execute(
- new Callable<BigDecimal>(){ // <1>
- public BigDecimal call() throws Exception {
- // query against DB using t, tt, d
- // further expensive calculations
- }
- },
- TaxService.class, // <2>
- "calculateTax",
- t, tt, d);
- }
-}
-----
-<1> the `Callable` is the original code
-<2> the remaining parameters in essence uniquely identify the method call.
-
-This refactoring will be worthwhile provided that enough of the orders being processed reference the same taxable products. If however every order is for a different product, then no benefit will be gained from the refactoring.
-
-
-
-
-== Registering the Service
-
-Assuming that the `configuration-and-annotation` services installer is configured (implicit if using the
-`AppManifest` to xref:rg.adoc#_rg_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' core
-implementation of `QueryResultsCache` service is automatically registered and injected (it is annotated with
-`@DomainService`) so no further configuration is required.
-
-To use an alternative implementation, use
-xref:rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
-further in this xref:ug.adoc#_ug_how-tos_replacing-default-service-implementations["how to"] tip).
-
-
-
-== Related Services
-
-The xref:rgsvc.adoc#_rgsvc-api_manpage-Scratchpad[`Scratchpad`] service is also intended for actions that are called many times, allowing arbitrary information to be shared between them. Those methods could be called from some outer loop in domain code, or by the framework itself if the action invoked has the xref:rgant.adoc#_rgant-Action_invokeOn[`@Action#invokeOn()`] annotation attribute set to `OBJECT_AND_COLLECTION` or `COLLECTION_ONLY`.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/88993cf3/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_manpage-Scratchpad.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_manpage-Scratchpad.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_manpage-Scratchpad.adoc
deleted file mode 100644
index 1f890aa..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_manpage-Scratchpad.adoc
+++ /dev/null
@@ -1,128 +0,0 @@
-[[_rgsvc-api_manpage-Scratchpad]]
-= `Scratchpad`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-
-The `Scratchpad` service is a link:../../more-advanced-topics/how-to-09-020-How-to-write-a-typical-domain-service.html[request-scoped] service to allow objects to exchange information even if they do not directly call each other.
-
-
-
-
-== API & Implementation
-
-The API of `Scratchpad` service is:
-
-[source,java]
-----
-@RequestScoped
-public class Scratchpad {
- @Programmatic
- public Object get(Object key) { ... }
- @Programmatic
- public void put(Object key, Object value) { ... }
- @Programmatic
- public void clear() { ... }
-}
-----
-
-This class (`o.a.i.applib.services.scratchpad.Scratchpad`) is also the implementation. And, as you can see, the service is just a request-scoped wrapper around a `java.util.Map`.
-
-
-
-
-
-== Usage
-
-The most common use-case is for xref:rgant.adoc#_rgant-Action_invokeOn[bulk] actions that act upon multiple objects in a list. The (same) `Scratchpad` service is injected into each of these objects, and so they can use pass information.
-
-For example, the Isis addons example https://github.com/isisaddons/isis-app-todoapp/[todoapp] (not ASF) demonstrates how the `Scratchpad` service can be used to calculate the total cost of the selected `ToDoItem`s:
-
-
-[source,java]
-----
-@Action(
- semantics=SemanticsOf.SAFE,
- invokeOn=InvokeOn.COLLECTION_ONLY
-)
-public BigDecimal totalCost() {
- BigDecimal total = (BigDecimal) scratchpad.get("runningTotal");
- if(getCost() != null) {
- total = total != null ? total.add(getCost()) : getCost();
- scratchpad.put("runningTotal", total);
- }
- return total.setScale(2);
-}
-@Inject
-Scratchpad scratchpad;
-----
-
-A more complex example could use a xref:ugbtb.adoc#_ugbtb_more-advanced_view-models[view model] to enable bulk updates to a set of objects. The view model's job is to gather track of the items to be updated:
-
-[source,java]
-----
-public class ToDoItemUpdateBulkUpdate extends AbstractViewModel {
- private List<ToDoItem> _items = ...;
- public ToDoItemBulkUpdate add(ToDoItem item) {
- _items.add(item);
- return this;
- }
- ... // <1>
-}
-----
-<1> not shown - the implementation of `ViewModel` for converting the list of `_items` into a string.
-
-The bulk action in the objects simply adds the selected item to the view model:
-
-[source,java]
-----
-@Action(
- invokeOn=InvokeOn.COLLECTIONS_ONLY
- semantics=SemanticsOf.SAFE
-)
-public ToDoItemBulkUpdate bulkUpdate() {
- return lookupBulkUpdateViewModel().add(this);
-}
-private ToDoItemBulkUpdate lookupBulkUpdateViewModel() {
- ToDoItemBulkUpdate bulkUpdate =
- (ToDoItemBulkUpdate) scratchpad.get("bulkUpdateViewModel"); // <1>
- if(bulkUpdate == null) {
- bulkUpdate = container.injectServicesInto(new ToDoItemBulkUpdate());
- scratchpad.put("bulkUpdateViewModel", bulkUpdate); // <2>
- }
- return bulkUpdate;
-}
-@Inject
-Scratchpad scratchpad;
-----
-<1> look for the `ToDoItemBulkUpdate` in the scratchpad...
-<2> ... and add one if there isn't one (ie for the first object returned).
-
-If using the xref:ugvw.adoc#[Wicket viewer], the `ToDoItemBulkUpdate` view model returned from the last action invoked will be displayed. Thereafter this view model can be used to perform a bulk update of the "enlisted" items.
-
-
-
-
-
-== Registering the Service
-
-Assuming that the `configuration-and-annotation` services installer is configured (implicit if using the
-`AppManifest` to xref:rg.adoc#_rg_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' core
-implementation of `Scratchpad` service is automatically registered and injected (it is annotated with `@DomainService`)
-so no further configuration is required.
-
-To use an alternative implementation, use
-xref:rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
-further in this xref:ug.adoc#_ug_how-tos_replacing-default-service-implementations["how to"] tip).
-
-
-
-
-
-== Related Services
-
-The xref:rgsvc.adoc#_rgsvc-api_manpage-ActionInteractionContext[`ActionInteractionContext`] service allows xref:rgant.adoc#_rgant-Action_invokeOn[bulk actions] to co-ordinate with each other.
-
-The xref:rgsvc.adoc#_rgsvc-api_manpage-QueryResultsCache[`QueryResultsCache`] is useful for caching the results of expensive method calls.
http://git-wip-us.apache.org/repos/asf/isis/blob/88993cf3/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_manpage-SudoService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_manpage-SudoService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_manpage-SudoService.adoc
deleted file mode 100644
index c2529b7..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_manpage-SudoService.adoc
+++ /dev/null
@@ -1,69 +0,0 @@
-[[_rgsvc-api_manpage-SudoService]]
-= `SudoService`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-
-The `SudoService` allows the current user reported by the `DomainObjectContainer` to be temporarily changed to some
-other user. This is useful both for xref:ugtst.adoc#_ugtst_integ-test-support[integration testing] (eg if testing a workflow system whereby objects are moved from one user to another) and while running xref:ugtst.adoc#_ugtst_fixture-scripts[fixture scripts] (eg setting up objects that would normally require several users to have acted upon the objects).
-
-
-== API & Implementation
-
-The API provided by the service is:
-
-[source,java]
-----
-public interface SudoService {
- @Programmatic
- void sudo(String username, final Runnable runnable);
- @Programmatic
- <T> T sudo(String username, final Callable<T> callable);
- @Programmatic
- void sudo(String username, List<String> roles, final Runnable runnable);
- @Programmatic
- <T> T sudo(String username, List<String> roles, final Callable<T> callable);
-}
-----
-
-which will run the provided block of code (a `Runnable` or a `Callable`) in a way such that calls to
-`DomainObjectContainer#getUser()` will return the specified user (and roles, if specified)
-
-The core framework provides a default implementation of this service (`o.a.i.core.runtime.services.sudo.SudoServiceDefault`).
-
-
-
-
-== Usage
-
-A good example can be found in the (non-ASF) http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp] which uses the `SudoService` in a fixture script to set up `ToDoItem` objects:
-
-[source,java]
-----
-protected void execute(final ExecutionContext ec) {
- ...
- sudoService.sudo(getUsername(),
- new Runnable() {
- @Override
- public void run() {
- wrap(toDoItem).completed();
- }
- });
- ...
-}
-----
-
-
-
-== Registering the Service
-
-Assuming that the `configuration-and-annotation` services installer is configured (implicit if using the
-`AppManifest` to xref:rg.adoc#_rg_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' core
-implementation of `SudoService` service is automatically registered and injected (it is annotated with
-`@DomainService`) so no further configuration is required.
-
-To use an alternative implementation, use
-xref:rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
-further in this xref:ug.adoc#_ug_how-tos_replacing-default-service-implementations["how to"] tip).
http://git-wip-us.apache.org/repos/asf/isis/blob/88993cf3/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_manpage-WrapperFactory.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_manpage-WrapperFactory.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_manpage-WrapperFactory.adoc
deleted file mode 100644
index 44a609a..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_manpage-WrapperFactory.adoc
+++ /dev/null
@@ -1,162 +0,0 @@
-[[_rgsvc-api_manpage-WrapperFactory]]
-= `WrapperFactory`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-
-
-The `WrapperFactory` provides the ability to enforce business rules for programmatic interactions between domain objects. If there is a (lack-of-) trust boundary between the caller and callee -- eg if they reside in different modules -- then the wrapper factory is a useful mechanism to ensure that any business constraints defined by te callee are honoured.
-
-For example, if the calling object attempts to modify an unmodifiable property on the target object, then an exception will be thrown. Said another way: interactions are performed "as if" they are through the viewer.
-
-[NOTE]
-====
-For a discussion of the use of the `WrapperFactory` within integration tests (the primary or at least original use case for this service) can be found xref:ugtst.adoc#_ugtst_integ-test-support_wrapper-factory[here]
-====
-
-This capability goes beyond enforcing the (imperative) constraints within the `hideXxx()`, `disableXxx()` and `validateXxx()` supporting methods; it also enforces (declarative) constraints such as those represented by annotations, eg `@MaxLength` or `@Regex`.
-
-This capability is frequently used within xref:ugtst.adoc#_ugtst_integ-test-support[integration tests], but can also be used in production code. (There are analogies that can be drawn here with the way that JEE beans can interact through an EJB local interface).
-
-
-
-
-== API
-
-The API provided by the service is:
-
-[source,java]
-----
-public interface WrapperFactory {
- @Programmatic
- <T> T wrap(T domainObject); // <1>
- @Programmatic
- <T> T unwrap(T possibleWrappedDomainObject); // <2>
- @Programmatic
- <T> boolean isWrapper(T possibleWrappedDomainObject); // <3>
-
- public static enum ExecutionMode { // <4>
- EXECUTE(true,true),
- SKIP_RULES(false, true), // <5>
- NO_EXECUTE(true, false); // <6>
- }
- @Programmatic
- <T> T wrap(T domainObject, ExecutionMode mode); // <7>
- @Programmatic
- <T> T wrapNoExecute(T domainObject); // <8>
- @Programmatic
- <T> T wrapSkipRules(T domainObject); // <9>
- ...
- }
-----
-<1> wraps the underlying domain object. If it is already wrapped, returns the object back unchanged.
-<2> Obtains the underlying domain object, if wrapped. If the object is not wrapped, returns back unchanged.
-<3> whether the supplied object has been wrapped.
-<4> enumerates how the wrapper interacts with the underlying domain object.
-<5> validate all business rules and then execute.
-<6> skip all business rules and then execute (including creating xref:rgant.adoc#_rgant-Action_command[command]s and firing pre- and post-execute xref:rgant.adoc#_rgant-Action_domainEvent[domain event]s).
-<7> validate all business rules (including those from xref:rgant.adoc#_rgant-Action_domainEvent[domain event]s) but do not execute.
-<8> convenience method to invoke `wrap(...)` with `ExecuteMode#NO_EXECUTE` (make this feature more discoverable)
-<9> convenience method to invoke `wrap(...)` with `ExecuteMode#SKIP_RULES` (make this feature more discoverable)
-
-
-
-The service works by returning a "wrapper" around a supplied domain object (a link:http://www.javassist.org[javassist] proxy), and it is this wrapper that ensures that the hide/disable/validate rules implies by the Apache Isis programming model are enforced. The wrapper can be interacted with as follows:
-
-* a `get...()` method for properties or collections
-* a `set...()` method for properties
-* an `addTo...()` or `removeFrom...()` method for collections
-* any action
-
-Calling any of the above methods may result in a (subclass of) `InteractionException` if the object disallows it. For example, if a property is annotated with `@Hidden` then a `HiddenException` will be thrown. Similarly if an action has a `validateXxx()` method and the supplied arguments are invalid then an `InvalidException` will be thrown.
-
-In addition, the following methods may also be called:
-
-* the xref:rg.adoc#_rg_methods_reserved_manpage-title[`title()`] and `toString()` methods
-* any xref:rg.adoc#_rg_methods_prefixes_manpage-default[`default...()`], xref:rg.adoc#_rg_methods_prefixes_manpage-choices[`choices...()`] or xref:rg.adoc#_rg_methods_prefixes_manpage-autoComplete[`autoComplete...()`] methods
-
-An exception will be thrown if any other methods are thrown.
-
-
-
-
-
-== Usage
-
-The caller will typically obtain the target object (eg from some repository) and then use the injected `WrapperFactory` to wrap it before interacting with it.
-
-For example:
-
-[source,java]
-----
-public class CustomerAgent {
- @Action
- public void refundOrder(final Order order) {
- final Order wrappedOrder = wrapperFactory.wrap(order);
- try {
- wrappedOrder.refund();
- } catch(InteractionException ex) { // <1>
- container.raiseError(ex.getMessage()); // <2>
- return;
- }
- }
- ...
- @Inject
- WrapperFactory wrapperFactory;
- @Inject
- DomainObjectContainer container;
-}
-----
-<1> if any constraints on the `Order`'s `refund()` action would be violated, then ...
-<2> ... these will be trapped and raised to the user as a warning.
-
-[NOTE]
-====
-It ought to be possible to implement an xref:rgsvc.adoc#_rgsvc-spi_manpage-ExceptionRecognizer[`ExceptionRecognizer`]s that would allow the above boilerplate to be removed. This recognizer service would recognize the `InteractionException` and convert to a suitable message.
-
-At the time of writing Apache Isis does not provide an out-of-the-box implementation of such an `ExceptionRecognizer`; but it should be simple enough to write one…
-====
-
-
-
-
-== Listener API
-
-The `WrapperFactory` also provides a listener API to allow other services to listen in on interactions.
-
-[source,java]
-----
-public interface WrapperFactory {
- ...
- @Programmatic
- List<InteractionListener> getListeners(); // <1>
- @Programmatic
- public boolean addInteractionListener(InteractionListener listener); // <2>
- @Programmatic
- public boolean removeInteractionListener(InteractionListener listener); // <3>
- @Programmatic
- public void notifyListeners(InteractionEvent ev); // <4>
-}
-----
-<1> all ``InteractionListener``s that have been registered.
-<2> registers an `InteractionListener`, to be notified of interactions on all wrappers. The listener will be notified of interactions even on wrappers created before the listener was installed. (From an implementation perspective this is because the wrappers delegate back to the container to fire the events).
-<3> remove an `InteractionListener`, to no longer be notified of interactions on wrappers.
-<4> used by the framework itself
-
-The original intent of this API was to enable test transcripts to be captured (in a BDD-like fashion) from integration tests. No such feature has yet been implemented however. Also, the capabilities have by and large been superceded by Apache Isis' support for domain events. We may therefore deprecate this API in the future.
-
-
-
-
-== Registering the Service
-
-Assuming that the `configuration-and-annotation` services installer is configured (implicit if using the
-`AppManifest` to xref:rg.adoc#_rg_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' core
-implementation of `WrapperFactory` service is automatically registered and injected (it is annotated with
-`@DomainService`) so no further configuration is required.
-
-To use an alternative implementation, use
-xref:rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
-further in this xref:ug.adoc#_ug_how-tos_replacing-default-service-implementations["how to"] tip).