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/09/24 10:37:20 UTC
svn commit: r1627254 - in /isis/site/trunk/content/reference/services:
memento-service.md publishing-service.md
Author: danhaywood
Date: Wed Sep 24 08:37:20 2014
New Revision: 1627254
URL: http://svn.apache.org/r1627254
Log:
updates to MementoService and PublishingService
Modified:
isis/site/trunk/content/reference/services/memento-service.md
isis/site/trunk/content/reference/services/publishing-service.md
Modified: isis/site/trunk/content/reference/services/memento-service.md
URL: http://svn.apache.org/viewvc/isis/site/trunk/content/reference/services/memento-service.md?rev=1627254&r1=1627253&r2=1627254&view=diff
==============================================================================
--- isis/site/trunk/content/reference/services/memento-service.md (original)
+++ isis/site/trunk/content/reference/services/memento-service.md Wed Sep 24 08:37:20 2014
@@ -51,11 +51,21 @@ In the case of the default implementatio
If using another implementation, the `canSet(...)` method can be used to check if the candidate object's type is supported.
-###Usage within the framework
+###Usage
-The memento service is used 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.
+To use in your code, simply declare the service and annotate with `@javax.inject.Inject`. For example:
+
+<pre>
+import org.apache.isis.applib.services.memento.MementoService;
+
+public class MyEntity {
+ javax.inject.Inject
+ private MementoService mementoService;
+}
+</pre>
+
###Implementations
The core framework provides a default implementation of this API:
@@ -70,14 +80,17 @@ In fact, the `MementoServiceDefault` imp
However, you are of course free to write some other implementation of `MementoService`, perhaps based on `MementoServiceDefault` code if you wish.
-### Register the Service
+### Related Services
-The service is registered, like any other, in `isis.properties`:
+The memento service is used 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.
+
+
+
+### Register the Service
- isis.services=...,\
- org.apache.isis.core.runtime.services.memento.MementoServiceDefault,\
- ...
+As of 1.6.0, the `MementoServiceDefault` service is automatically registered and available for injection (it is annotated with `@DomainService`).
+Prior to 1.6.0, it was necessary to register the service in `isis.properties`.
Modified: isis/site/trunk/content/reference/services/publishing-service.md
URL: http://svn.apache.org/viewvc/isis/site/trunk/content/reference/services/publishing-service.md?rev=1627254&r1=1627253&r2=1627254&view=diff
==============================================================================
--- isis/site/trunk/content/reference/services/publishing-service.md (original)
+++ isis/site/trunk/content/reference/services/publishing-service.md Wed Sep 24 08:37:20 2014
@@ -58,21 +58,27 @@ Typically implementations will use the i
public Object serialize(EventMetadata metadata, EventPayload payload);
}
-The serialized form returned by `EventSerializer` will typically be something like JSON, XML or a string. The signature of `serialize(...)` returns an object
-Although not necessary to implement `EventSerializer`, typically one should also for maximum flexibility, but its important to make sure that the `PublishingService` is able to handle the serialized form. Strings are a good
-lowest common denominator, but in some cases are type-safe equivalent, such as a
+The serialized form returned by `EventSerializer` must be in a form that the `PublishingService` implementation is able
+to handle. Strings are a good lowest common denominator, but (if custom implementations of both `EventSerializer` and
+`PublishingService` were in use) then it might also be some other type, for example an
`org.w3c.dom.Document` or an `org.json.JSONObject` might be returned instead.
### Fine-tuning the payload
-The `EventPayload` that is serialized identifies the object(s) being interacted with or changed, and in the case of the action invocation provides details of the action arguments and result (if any) of that action. However, the payload does not include the new state of these objects. It is therefore the responsibility of the subscriber to call back to Isis to determine any information that has not been published.
+The `EventPayload` that is serialized identifies the object(s) being interacted with or changed, and in the case of the
+action invocation provides details of the action arguments and result (if any) of that action. However, the payload
+does not (by default) include the new state of these objects. It is therefore the responsibility of the subscriber to
+call back to Isis to determine any information that has not been published.
-Doing this is comparatively straightforward if using the Restful Object serializer and Restful Objects viewer; the JSON provided includes hrefs to the objects.
+Doing this is comparatively straightforward if using the Restful Object serializer and Restful Objects viewer; the
+JSON provided includes hrefs to the objects.
-In some circumstances, however, it may make more sense to eagerly "push" information about the change to the subscriber by including that state within the payload.
+In some circumstances, then, it may make more sense to eagerly "push" information about the change to the subscriber
+by including that state within the payload.
-To accomplish this, an implementation of a "`PayloadFactory`" must be specified in the annotation. For actions, implement `@PublishedAction.PayloadFactory`:
+To accomplish this, an implementation of a "`PayloadFactory`" must be specified in the annotation. For actions,
+implement `@PublishedAction.PayloadFactory`:
public @interface PublishedAction {
public interface PayloadFactory {
@@ -84,16 +90,29 @@ To accomplish this, an implementation of
Class<? extends PayloadFactory> value() default PayloadFactory.class;
}
+The `EventPayloadForActionInvocation` abstract class (in the Isis applib) can optionally be used as the base class for
+the object instance returned from `payLoadFor(...)`.
+
For objects, the interface to implement is `@PublishedObject.PayloadFactory`:
public @interface PublishedObject {
+
+ public enum ChangeKind {
+ CREATE,
+ UPDATE,
+ DELETE
+ }
+
public interface PayloadFactory {
@Programmatic
- public EventPayload payloadFor(Object changed);
+ public EventPayload payloadFor(Object changedObject, ChangeKind kind);
}
Class<? extends PayloadFactory> value() default PayloadFactory.class;
}
+Similarly, the `EventPayloadForObjectChanged` abstract class may be used as the base class for the object returned from
+`payLoadFor(...)`.
+
For example, the following will eagerly include the `ToDoItem`'s `description` property whenever it is changed:
@PublishedObject(ToDoItemPayloadFactory.class)
@@ -105,7 +124,7 @@ where `ToDoItemPayloadFactory` is define
public class ToDoItemChangedPayloadFactory implements PayloadFactory {
public static class ToDoItemPayload
- extends EventPayloadForChangedObject<ToDoItem> {
+ extends EventPayloadForObjectChanged<ToDoItem> {
public ToDoItemPayload(ToDoItem changed) {
super(changed);
@@ -116,7 +135,7 @@ where `ToDoItemPayloadFactory` is define
}
}
@Override
- public EventPayload payloadFor(Object changedObject) {
+ public EventPayload payloadFor(Object changedObject, ChangeKind kind) {
return new ToDoItemPayload((ToDoItem) changedObject);
}
}