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 2014/02/06 11:05:23 UTC
svn commit: r1565141 - in /isis/site/trunk/content: ./
applib-guide/reference/ applib-guide/reference/recognized-annotations/
core/services/
Author: danhaywood
Date: Thu Feb 6 10:05:22 2014
New Revision: 1565141
URL: http://svn.apache.org/r1565141
Log:
stuff on services
Added:
isis/site/trunk/content/applib-guide/reference/ViewModel.md
isis/site/trunk/content/applib-guide/reference/recognized-annotations/Command.md
isis/site/trunk/content/core/services/background-service.md
isis/site/trunk/content/core/services/command-context.md
isis/site/trunk/content/core/services/memento-service.md
Modified:
isis/site/trunk/content/applib-guide/reference/about.md
isis/site/trunk/content/applib-guide/reference/recognized-annotations/ViewModel.md
isis/site/trunk/content/applib-guide/reference/recognized-annotations/about.md
isis/site/trunk/content/core/services/about.md
isis/site/trunk/content/core/services/auditing-service.md
isis/site/trunk/content/core/services/bookmark-service.md
isis/site/trunk/content/core/services/bulk-interaction.md
isis/site/trunk/content/core/services/query-results-cache.md
isis/site/trunk/content/core/services/scratchpad.md
isis/site/trunk/content/documentation.md
Added: isis/site/trunk/content/applib-guide/reference/ViewModel.md
URL: http://svn.apache.org/viewvc/isis/site/trunk/content/applib-guide/reference/ViewModel.md?rev=1565141&view=auto
==============================================================================
--- isis/site/trunk/content/applib-guide/reference/ViewModel.md (added)
+++ isis/site/trunk/content/applib-guide/reference/ViewModel.md Thu Feb 6 10:05:22 2014
@@ -0,0 +1,35 @@
+Title: ViewModel interface
+----------
+
+Indicates that a domain object is intended to be used as a view model.
+
+### API
+
+ public interface ViewModel {
+
+ @Hidden
+ public String viewModelMemento();
+
+ @Hidden
+ public void viewModelInit(String memento);
+ }
+
+Where:
+
+* `viewModelMemento()`
+
+ is called by the framework, to obtain a memento of the view model. Typically this will be the identifier of a backing domain entity, but it could also be an arbitrary string, for example a bunch of JSON.
+
+* `viewModelInit()`
+
+ is called by the framework so that the view model may recreate its state in a subsequent call (using the memento that the framework obtained from `viewModelMemento()`
+
+### Usage
+
+Used in the example [todo app](https://github.com/apache/isis/tree/quickstart_wicket_restful_jdo-archetype-1.3.1-RC1/example/application/quickstart_wicket_restful_jdo/dom/src/main/java/app), for example the [ToDoAppDashboard](https://github.com/apache/isis/blob/quickstart_wicket_restful_jdo-archetype-1.3.1-RC1/example/application/quickstart_wicket_restful_jdo/dom/src/main/java/app/ToDoAppDashboard.java) that is rendered on the home page.
+
+
+### Related Services
+
+The [MementoService](../../core/services/memento-service.html) provides a convenient mechanism for view models to build up and parse memento strings (for the implementation of the `viewModelMemento()` and `viewModelInit()` methods.
+
\ No newline at end of file
Modified: isis/site/trunk/content/applib-guide/reference/about.md
URL: http://svn.apache.org/viewvc/isis/site/trunk/content/applib-guide/reference/about.md?rev=1565141&r1=1565140&r2=1565141&view=diff
==============================================================================
--- isis/site/trunk/content/applib-guide/reference/about.md (original)
+++ isis/site/trunk/content/applib-guide/reference/about.md Thu Feb 6 10:05:22 2014
@@ -6,6 +6,8 @@ Title: Programming Model Reference
* [DomainObjectContainer interface](./DomainObjectContainer.html)
+* [ViewModel interface](./ViewModel.html)
+
* [Security](./Security.html)
* [Applib Utility Classes](./Utility.html)
Added: isis/site/trunk/content/applib-guide/reference/recognized-annotations/Command.md
URL: http://svn.apache.org/viewvc/isis/site/trunk/content/applib-guide/reference/recognized-annotations/Command.md?rev=1565141&view=auto
==============================================================================
--- isis/site/trunk/content/applib-guide/reference/recognized-annotations/Command.md (added)
+++ isis/site/trunk/content/applib-guide/reference/recognized-annotations/Command.md Thu Feb 6 10:05:22 2014
@@ -0,0 +1,4 @@
+@Command
+----------
+
+> this is a stub
Modified: isis/site/trunk/content/applib-guide/reference/recognized-annotations/ViewModel.md
URL: http://svn.apache.org/viewvc/isis/site/trunk/content/applib-guide/reference/recognized-annotations/ViewModel.md?rev=1565141&r1=1565140&r2=1565141&view=diff
==============================================================================
--- isis/site/trunk/content/applib-guide/reference/recognized-annotations/ViewModel.md (original)
+++ isis/site/trunk/content/applib-guide/reference/recognized-annotations/ViewModel.md Thu Feb 6 10:05:22 2014
@@ -1,6 +1,7 @@
@ViewModel
----------
+x
> **Support**
>
> * Not yet supported by any viewers
Modified: isis/site/trunk/content/applib-guide/reference/recognized-annotations/about.md
URL: http://svn.apache.org/viewvc/isis/site/trunk/content/applib-guide/reference/recognized-annotations/about.md?rev=1565141&r1=1565140&r2=1565141&view=diff
==============================================================================
--- isis/site/trunk/content/applib-guide/reference/recognized-annotations/about.md (original)
+++ isis/site/trunk/content/applib-guide/reference/recognized-annotations/about.md Thu Feb 6 10:05:22 2014
@@ -8,6 +8,7 @@ Recognized Annotations
* [AutoComplete](./AutoComplete.html)
* [Bounded](./Bounded.html)
* [Bulk](./Bulk.html)
+* [Command](./Command.html)
* [Debug](./Debug.html)
* [Defaulted](./Defaulted.html)
* [DescribedAs](./DescribedAs.html)
@@ -50,4 +51,3 @@ Recognized Annotations
* [TypeOf](./TypeOf.html)
* [TypicalLength](./TypicalLength.html)
* [Value](./Value.html)
-* [ViewModel](./ViewModel.html)
Modified: isis/site/trunk/content/core/services/about.md
URL: http://svn.apache.org/viewvc/isis/site/trunk/content/core/services/about.md?rev=1565141&r1=1565140&r2=1565141&view=diff
==============================================================================
--- isis/site/trunk/content/core/services/about.md (original)
+++ isis/site/trunk/content/core/services/about.md Thu Feb 6 10:05:22 2014
@@ -1,19 +1,33 @@
Title: Applib Services
-### Singleton service APIs
+bookmark/memento services:
-* [Clock, Fixtures, etc](../../applib-guide/supporting-features/about.html)
-* [Auditing Service](./auditing-service.html)
* [Bookmark Service](./bookmark-service.html)
-* [Developer Utilities Service](./developer-utilities-service.html)
-* [Exception Recognizers](./exception-recognizers.html)
+* [Memento Service](./memento-service.html) [1.4.0-SNAPSHOT]
+* [XmlSnapshot Service](./xmlsnapshot-service.html)
+
+profiling/background execution:
+
+* [Command Context / Command Service](./command-context.html) [1.4.0-SNAPSHOT, stub]
+* [Background Service / Background Command Service](./background-service.html) [1.4.0-SNAPSHOT, stub]
+
+publishing/auditing:
+
+* [Auditing Service](./auditing-service.html)
* [Publishing Service](./publishing-service.html)
-* [Settings Services](./settings-services.html)
-### @RequestScoped service APIs [1.4.0-SNAPSHOT]
+performance tuning/co-ordination:
* [QueryResultsCache](./query-results-cache.html) [1.4.0-SNAPSHOT]
* [Scratchpad](./scratchpad.html) [1.4.0-SNAPSHOT]
-* [Bulk Interaction](./bulk-interaction.html) [1.4.0-SNAPSHOT]
+* [Bulk Interaction](./bulk-interaction.html) [1.4.0-SNAPSHOT, stub]
+
+other:
+
+* [Settings Services](./settings-services.html)
+* [Exception Recognizers](./exception-recognizers.html)
+* [Clock, Fixtures, etc](../../applib-guide/supporting-features/about.html)
+* [Developer Utilities Service](./developer-utilities-service.html)
+
Modified: isis/site/trunk/content/core/services/auditing-service.md
URL: http://svn.apache.org/viewvc/isis/site/trunk/content/core/services/auditing-service.md?rev=1565141&r1=1565140&r2=1565141&view=diff
==============================================================================
--- isis/site/trunk/content/core/services/auditing-service.md (original)
+++ isis/site/trunk/content/core/services/auditing-service.md Thu Feb 6 10:05:22 2014
@@ -2,51 +2,57 @@ Title: Auditing Service
The auditing service provides a simple mechanism to capture changes to data. It is called for each property that has changed on any domain object, as a set of pre- and post-values.
-### API
+### API [1.4.0-SNAPSHOT]
The API for the service is:
- public interface AuditingService2 {
+ public interface AuditingService3 {
- @Hidden
+ @Programmatic
public void audit(
- String user, long currentTimestampEpoch,
- String objectType, String identifier,
- String propertyId,
- String preValue, String postValue);
+ final UUID transactionId, String targetClassName, final Bookmark target,
+ String memberIdentifier, final String propertyName,
+ final String preValue, final String postValue,
+ final String user, final java.sql.Timestamp timestamp);
}
-> Note that the original API for this service was called `AuditingService`. This original API has been deprecated because it accidentally omitted the `propertyId` parameter.
+> **BREAKING CHANGE!!!** The previous APIs for this service (`AuditingService` and `AuditingService2`) have been removed. The new API is a superset of these previous APIs. The change was made so that the auditing service would be consistent with the related [Publishing](./publishing-service.html) and the [Command Context](./command-context.html) services.
-### Register the Service
-
-To use, simply register your service implementation as you would any other service, in `isis.properties`:
+### API [1.3.0]
-Register like any other service in `isis.properties`:
+The API for the service is:
-<pre>
-isis.services=<i>...other services...</i>,\
- com.mycompany.myapp.isis.MyAuditingService,\
- ...
-</pre>
+ public interface AuditingService2 {
+
+ @Hidden
+ public void audit(
+ String user, long currentTimestampEpoch,
+ String objectType, String identifier,
+ String propertyId,
+ String preValue, String postValue);
+ }
+> Note that the original API for this service was called `AuditingService`. This original API has been deprecated because it accidentally omitted the `propertyId` parameter.
-### Existing Implementations
+### Implementations
A simple implementation of the service that writes to stderr, is available, useful for debugging:
-<pre>
-isis.services=<i>...other services...</i>,\
- org.apache.isis.applib.services.audit.AuditingService2$Stderr,\
- ...
-</pre>
+* `org.apache.isis.applib.services.audit.AuditingService3$Stderr` [1.4.0-SNAPSHOT]
+* `org.apache.isis.applib.services.audit.AuditingService2$Stderr` [1.3.0]
+An alternative implementation, that persists audit records to a database, is the [JDO Publishing Service](../../components/objectstores/jdo/publishing-service-jdo.html). This implementation is only supported when the the [JDO objectstore](../../components/objectstores/jdo/about.html) is configured.
-### Limitations
-This service is currently only supported when the the [JDO objectstore](../../components/objectstores/jdo/about.html) is configured.
+### Register the Service
+
+Register like any other service in `isis.properties`:
+
+ isis.services=...,\
+ com.mycompany.myapp.isis.SomeAuditingService,\
+ ...
-### Alternatives
+### Related Services
-A similar service that you may prefer to use is the [Publishing Service](publishing-service.html). While a little more complex, it is also considerably more flexible.
+A similar service that you may want to use alongside or instead of the auditing service is the [Publishing Service](publishing-service.html).
Added: isis/site/trunk/content/core/services/background-service.md
URL: http://svn.apache.org/viewvc/isis/site/trunk/content/core/services/background-service.md?rev=1565141&view=auto
==============================================================================
--- isis/site/trunk/content/core/services/background-service.md (added)
+++ isis/site/trunk/content/core/services/background-service.md Thu Feb 6 10:05:22 2014
@@ -0,0 +1,17 @@
+Title: Background Service [1.4.0-SNAPSHOT]
+
+> this is a stub, for `BackgroundService` and `BackgroundCommandService`
+
+### API
+
+
+### Implementation
+
+
+### Usage
+
+
+### Registering the Services
+
+
+### Related Services
Modified: isis/site/trunk/content/core/services/bookmark-service.md
URL: http://svn.apache.org/viewvc/isis/site/trunk/content/core/services/bookmark-service.md?rev=1565141&r1=1565140&r2=1565141&view=diff
==============================================================================
--- isis/site/trunk/content/core/services/bookmark-service.md (original)
+++ isis/site/trunk/content/core/services/bookmark-service.md Thu Feb 6 10:05:22 2014
@@ -2,32 +2,47 @@ Title: Bookmark Service
The `BookmarkService` provides the ability to obtain a serializable `org.apache.isis.applib.bookmarks.Bookmark` for any (persisted) domain object, and to lookup domain objects given a `Bookmark`.
+This is a good way of storing a reference to an arbitrary object (a polymorphic relationship). The downside is that there is no way for the objectstore (eg JDO objectstore) to enforce any kind of referental integrity.
+
+
+###API
+
The API defined by `BookmarkService` is:
-<pre>
- @Named("Bookmarks")
- public interface BookmarkService {
-
- @NotInServiceMenu
- Object lookup(BookmarkHolder bookmarkHolder);
-
- @Hidden
- Object lookup(Bookmark bookmark);
-
- @Hidden
- Bookmark bookmarkFor(Object domainObject);
- }
-</pre>
+ @Named("Bookmarks")
+ public interface BookmarkService {
+
+ @NotInServiceMenu
+ Object lookup(BookmarkHolder bookmarkHolder);
+
+ @Hidden
+ Object lookup(Bookmark bookmark);
+
+ @Hidden
+ Bookmark bookmarkFor(Object domainObject);
+ }
If a domain class implements the `org.apache.isis.applib.bookmarks.BookmarkHolder` interface then the `BookmarkService` will appear as a contributed action. Otherwise the service is hidden from view, intended to be injected into domain objects as a supporting domain service.
+###Usage within the framework
+
+Bookmarks are used [1.4.0-SNAPSHOT onwards] by the [BackgroundCommandService](./background-service.html), which uses a bookmark to capture the target object on which an action will be invoked subsequently.
+
+Bookmarks are also used by the [PublishingService](./publishing-service.html) and the [AuditingService](./auditing-service.html).
+
+
+###Implementations
+
+The core framework provides a default implementation of this API:
+
+* `org.apache.isis.core.metamodel.services.bookmarks.BookmarkServiceDefault`
+
+
### Register the Service
-An implementation of this service is provided by Isis core. Register this service like any other service, in `isis.properties`:
+Register this service like any other service, in `isis.properties`, eg:
-<pre>
-isis.services=<i>...other services...</i>,\
- org.apache.isis.core.metamodel.services.bookmarks.BookmarkServiceDefault,\
- ...
-</pre>
+ isis.services=...,\
+ org.apache.isis.core.metamodel.services.bookmarks.BookmarkServiceDefault,\
+ ...
Modified: isis/site/trunk/content/core/services/bulk-interaction.md
URL: http://svn.apache.org/viewvc/isis/site/trunk/content/core/services/bulk-interaction.md?rev=1565141&r1=1565140&r2=1565141&view=diff
==============================================================================
--- isis/site/trunk/content/core/services/bulk-interaction.md (original)
+++ isis/site/trunk/content/core/services/bulk-interaction.md Thu Feb 6 10:05:22 2014
@@ -2,3 +2,17 @@ Title: Bulk Interaction [1.4.0-SNAPSHOT]
> this is a stub, see [ISIS-655](https://issues.apache.org/jira/browse/ISIS-655)
+### API
+
+
+### Usage
+
+
+### Implementation
+
+
+### Registering the Service
+
+
+### Related Services
+
Added: isis/site/trunk/content/core/services/command-context.md
URL: http://svn.apache.org/viewvc/isis/site/trunk/content/core/services/command-context.md?rev=1565141&view=auto
==============================================================================
--- isis/site/trunk/content/core/services/command-context.md (added)
+++ isis/site/trunk/content/core/services/command-context.md Thu Feb 6 10:05:22 2014
@@ -0,0 +1,20 @@
+Title: CommandContext and CommandService [1.4.0-SNAPSHOT]
+
+> this is a stub for `CommandContext` and `CommandService` services
+
+### API
+
+
+### Implementation
+
+
+### Usage
+
+
+### Registering the Services
+
+
+
+### Related Services
+
+
Added: isis/site/trunk/content/core/services/memento-service.md
URL: http://svn.apache.org/viewvc/isis/site/trunk/content/core/services/memento-service.md?rev=1565141&view=auto
==============================================================================
--- isis/site/trunk/content/core/services/memento-service.md (added)
+++ isis/site/trunk/content/core/services/memento-service.md Thu Feb 6 10:05:22 2014
@@ -0,0 +1,83 @@
+Title: Memento Service [1.4.0-SNAPSHOT]
+
+The `MementoService` was originally introduced to simplify the implementation of [ViewModel](../../applib-guide/reference/ViewModel.html)s, which are required to return a 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 [BackgroundService](./background-service.html) for capture the state of action invocations so that they can be executed by a background process.
+
+
+###API
+
+The API defined by `MementoService` is:
+
+ 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 types of objects that are supported by the `MementoService` are implementation-specific, but would typically include all the usual value types as well as 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:
+
+* `String`
+* `boolean, `Boolean`
+* `byte`, `Byte`
+* `short`, `Short`
+* `int`, `Integer`
+* `long`, `Long`
+* `float`, `Float`
+* `double`, `Double`
+* `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 within the framework
+
+The memento service is used [1.4.0-SNAPSHOT onwards] by the [CommandContext](./command-context.html) service and also [BackgroundCommandService](./background-service.html). These both use a memento to capture a representation of an action invocation.
+
+
+###Implementations
+
+The core framework provides a default implementation of this API:
+
+* `org.apache.isis.core.runtime.services.memento.MementoServiceDefault`
+
+Because the string representation of the `Memento` must be URL-safe, the default implementation returns a base-64 URL encoded representation of the underlying format (an XML string).
+
+
+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.
+
+
+### Register the Service
+
+Register this service like any other service, in `isis.properties`, eg:
+
+ isis.services=...,\
+ org.apache.isis.core.runtime.services.memento.MementoServiceDefault,\
+ ...
+
+
+
+
Modified: isis/site/trunk/content/core/services/query-results-cache.md
URL: http://svn.apache.org/viewvc/isis/site/trunk/content/core/services/query-results-cache.md?rev=1565141&r1=1565140&r2=1565141&view=diff
==============================================================================
--- isis/site/trunk/content/core/services/query-results-cache.md (original)
+++ isis/site/trunk/content/core/services/query-results-cache.md Thu Feb 6 10:05:22 2014
@@ -1,4 +1,105 @@
Title: Query Results Cache [1.4.0-SNAPSHOT]
-> this is a stub, see [ISIS-654](https://issues.apache.org/jira/browse/ISIS-654)
+The purpose of the `QueryResultsCache` is to improve response times to the user, by providing a short-term ([request-scoped](../../applib-guide/domain-services/how-to-09-020-How-to-write-a-typical-domain-service.html)) 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 [subquery results cache](http://infocenter.sybase.com/help/index.jsp?topic=/com.sybase.dc20023_1251/html/optimizer/X43480.htm) and Oracle's [result_cache](http://www.dba-oracle.com/oracle11g/oracle_11g_result_cache_sql_hint.htm) hint.
+
+
+###API & Implementation
+
+The API defined by `QueryResultsCache` is:
+
+ @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) { ... }
+ this.result = result;
+ }
+ private T result;
+ public T getResult() {
+ return result;
+ }
+ }
+
+ // //////////////////////////////////////
+
+
+ public <T> T execute(
+ final Callable<T> callable,
+ final Class<?> callingClass, final String methodName, final Object... keys) { ... }
+
+ public <T> T execute(final Callable<T> callable, final Key cacheKey) { ... }
+
+ public <T> Value<T> get(
+ final Class<?> callingClass, final String methodName, final Object... keys) { ... }
+
+ public <T> Value<T> get(final Key cacheKey) { ... }
+
+ public <T> void put(final Key cacheKey, final T result) { ... }
+ }
+
+
+In fact, this is a concrete class:
+
+* `org.apache.isis.applib.services.queryresultscache.QueryResultsCache`
+
+
+### 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. The original implementation is:
+
+ public class TaxService {
+
+ public BigDecimal calculateTax(
+ final Taxable t, final TaxType tt, final LocalDate d) {
+ // query against DB using t, tt, d
+ // further expensive calculatoins
+ }
+ }
+
+We can imagine that this service might be called in a loop, eg 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:
+
+ public class TaxService {
+
+ public BigDecimal calculateTax(
+ final Taxable t, final TaxType tt, final LocalDate d) {
+ return queryResultsCache.execute(
+ new Callable<BigDecimal>(){
+ public BigDecimal call() throws Exception {
+ // query against DB using t, tt, d
+ // further expensive calculatoins
+ }
+ },
+ TaxService.class,
+ "calculateTax",
+ t, tt, d);
+ }
+ }
+
+where the callable is the original code, and the other parameters are 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.
+
+### Register the Service
+
+Register this service like any other service, in `isis.properties`, eg:
+
+ isis.services=...,\
+ org.apache.isis.applib.services.queryresultscache.QueryResultsCache,\
+ ...
+
+
+### Related Services
+
+The [ScratchPad](./scratchpad.html) 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 [@Bulk](../../applib-guide/reference/recognized-annotations/Bulk.html) annotation.
\ No newline at end of file
Modified: isis/site/trunk/content/core/services/scratchpad.md
URL: http://svn.apache.org/viewvc/isis/site/trunk/content/core/services/scratchpad.md?rev=1565141&r1=1565140&r2=1565141&view=diff
==============================================================================
--- isis/site/trunk/content/core/services/scratchpad.md (original)
+++ isis/site/trunk/content/core/services/scratchpad.md Thu Feb 6 10:05:22 2014
@@ -2,20 +2,24 @@ Title: Scratchpad [1.4.0-SNAPSHOT]
The Scratchpad service is a [request-scoped](../../applib-guide/domain-services/how-to-09-020-How-to-write-a-typical-domain-service.html) service to allow objects to exchange information even if they do not directly call each other.
+### API & Implementation
+
The API of `Scratchpad` service is:
@RequestScoped
public class Scratchpad {
-
public Object get(Object key) { ... }
-
public void put(Object key, Object value) { ... }
-
public void clear() { ... }
-
}
-... as you can see, it is just a wrapper around a `java.util.Map`.
+... as you can see, just a wrapper around a `java.util.Map`.
+
+In fact, this is a concrete class:
+
+* `org.apache.isis.applib.services.scratchpad.Scratchpad`
+
+### Usage
The most common use-case is for [Bulk](../../applib-guide/reference/recognized-annotations/Bulk.html) actions that [act upon multiple objects in a list](../../applib-guide/how-tos/how-to-01-065-How-to-add-an-action-to-be-called-on-every-object-in-a-list.html). The (same) `Scratchpad` service is injected into each of these objects, and they can use pass information.
@@ -72,3 +76,19 @@ The bulk action in the objects simply ad
}
If using the 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
+
+Register like any other service in `isis.properties`:
+
+ isis.services=...,\
+ com.mycompany.myapp.isis.SomeAuditingService,\
+ ...
+
+### Related Services
+
+The [Bulk.Interaction](./bulk-interaction.html) service allows [@Bulk](../../applib-guide/reference/recognized-annotations/Bulk.html) actions to co-ordinate with each other.
+
+The [QueryResultsCache](./query-results-cache.html) is useful for caching the results of expensive method calls.
+
Modified: isis/site/trunk/content/documentation.md
URL: http://svn.apache.org/viewvc/isis/site/trunk/content/documentation.md?rev=1565141&r1=1565140&r2=1565141&view=diff
==============================================================================
--- isis/site/trunk/content/documentation.md (original)
+++ isis/site/trunk/content/documentation.md Thu Feb 6 10:05:22 2014
@@ -169,7 +169,7 @@ For both:
* [Decoupling dependencies using contributions](./applib-guide/how-tos/how-to-01-062-How-to-decouple-dependencies-using-contributions.html)
* [Bulk actions, acting upon lists](./applib-guide/how-tos/how-to-01-065-How-to-add-an-action-to-be-called-on-every-object-in-a-list.html)
* [Bidirectional relationships](./applib-guide/how-tos/how-to-04-060-How-to-set-up-and-maintain-bidirectional-relationships.html)
-* [View models]()
+* [View models](./applib-guide/reference/ViewModel.html)
###Derived props/colls
@@ -265,22 +265,38 @@ For both:
{col-md-4
-### Singleton services
-* [Clock, Fixtures, etc](./applib-guide/supporting-features/about.html)
-* [Auditing Service](core/services/auditing-service.html)
+bookmark/memento services:
+
* [Bookmark Service](core/services/bookmark-service.html)
-* [Developer Utilities Service](core/services/developer-utilities-service.html)
-* [Exception Recognizers](core/services/exception-recognizers.html)
+* [Memento Service](core/services/memento-service.html) [1.4.0-SNAPSHOT, stub]
+* [XmlSnapshot Service](core/services/xmlsnapshot-service.html)
+
+profiling/background execution:
+
+* [Command Context/Service](core/services/command-context.html) [1.4.0-SNAPSHOT, stub]
+* [Background Service / Background Command Service](core/services/background-service.html) [1.4.0-SNAPSHOT, stub]
+SNAPSHOT, stub]
+
+publishing/auditing:
+
+* [Auditing Service](core/services/auditing-service.html)
* [Publishing Service](core/services/publishing-service.html)
-* [Settings Services](core/services/settings-services.html)
-### Request-scoped services
+performance tuning/co-ordination:
-* [Scratchpad](core/services/scratchpad.html) [1.4.0-SNAPSHOT]
* [QueryResultsCache](core/services/query-results-cache.html) [1.4.0-SNAPSHOT, stub]
+* [Scratchpad](core/services/scratchpad.html) [1.4.0-SNAPSHOT]
* [Bulk.Interaction](core/services/bulk-interaction.html) [1.4.0-SNAPSHOT, stub]
+other:
+
+* [Settings Services](core/services/settings-services.html)
+* [Exception Recognizers](core/services/exception-recognizers.html)
+* [Clock, Fixtures, etc](./applib-guide/supporting-features/about.html)
+* [Developer Utilities Service](core/services/developer-utilities-service.html)
+
+
}
{col-md-4