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/06/04 16:06:03 UTC
isis git commit: ISIS-1133: annotations now documented.
Repository: isis
Updated Branches:
refs/heads/ISIS-1133 4c99a344c -> eea1a3a85
ISIS-1133: annotations now documented.
Project: http://git-wip-us.apache.org/repos/asf/isis/repo
Commit: http://git-wip-us.apache.org/repos/asf/isis/commit/eea1a3a8
Tree: http://git-wip-us.apache.org/repos/asf/isis/tree/eea1a3a8
Diff: http://git-wip-us.apache.org/repos/asf/isis/diff/eea1a3a8
Branch: refs/heads/ISIS-1133
Commit: eea1a3a8527956eb6174eb06c31698afd5fb4886
Parents: 4c99a34
Author: Dan Haywood <da...@haywood-associates.co.uk>
Authored: Thu Jun 4 15:06:00 2015 +0100
Committer: Dan Haywood <da...@haywood-associates.co.uk>
Committed: Thu Jun 4 15:06:00 2015 +0100
----------------------------------------------------------------------
...rence-annotations_manpage-RequestScoped.adoc | 43 +++++++++++++++++++-
...reference-annotations_manpage-ViewModel.adoc | 13 ++----
2 files changed, 45 insertions(+), 11 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/isis/blob/eea1a3a8/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-RequestScoped.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-RequestScoped.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-RequestScoped.adoc
index 4a87320..b6b8312 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-RequestScoped.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-RequestScoped.adoc
@@ -4,8 +4,47 @@
:_basedir: ../
:_imagesdir: images/
-IMPORTANT: TODO
-as per `@javax.enterprise.context.RequestScoped`
+The `@javax.enterprise.context.RequestScoped` link:https://jcp.org/en/jsr/detail?id=299[JSR-299] CDI annotation is used to specify that a xref:_ug_reference-annotations_manpage-DomainService[domain service] should be request-scoped rather than a singleton.
+
+Although Isis does not (currently) leverage CDI, the semantics are the same as request-scoped service; a new instance is created for each HTTP request, reserved for the exclusive use of all objects interacted with during that request.
+
+One of the built-in domain services that uses this annotation is xref:_ug_reference-services-api_manpage-Scratchpad[`Scratchpad`], intended to allow the arbitrary sharing of data between objects. Here is the full source code of this service is:
+
+
+[source,java]
+----
+@DomainService(
+ nature = NatureOfService.DOMAIN
+)
+@RequestScoped
+public class Scratchpad {
+ private final Map<Object, Object> userData = Maps.newHashMap(); // <1>
+ @Programmatic
+ public Object get(Object key) {
+ return userData.get(key); // <2>
+ }
+ @Programmatic
+ public void put(Object key, Object value) {
+ userData.put(key, value); // <3>
+ }
+ @Programmatic
+ public void clear() {
+ userData.clear(); // <4>
+ }
+}
+----
+<1> Provides a mechanism for each object being acted upon to pass data to the next object.
+<2> Obtain user-data, as set by a previous object being acted upon.
+<3> Set user-data, for the use of a subsequent object being acted upon.
+<4> Clear any user data.
+
+
+The vast majority of domain services in Isis tend to be singletons (which requires no special annotation); but as you can see setting up request-scoped services is very straightforward.
+
+[NOTE]
+====
+Behind the covers Isis creates a (singleton) wrapper for the domain service; the individual request-scoped instances are held in a thread-local of this wrapper. One consequence of this implementation is that request-scoped methods should not be marked as `final`.
+====
http://git-wip-us.apache.org/repos/asf/isis/blob/eea1a3a8/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ViewModel.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ViewModel.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ViewModel.adoc
index 9b1bb06..9784f55 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ViewModel.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ViewModel.adoc
@@ -7,6 +7,7 @@
The `@ViewModel` annotation, applied to a class, is the simplest way to indicate that the class is a view model.
+
View models are not persisted to the database, instead their state is encoded within their identity (ultimately
represented in the URL). As such, view models are immutable.
@@ -16,20 +17,14 @@ For example:
----
@ViewModel
public class MyViewModel {
-
- public MyViewModel() {}
-
+ public MyViewModel() {} // <1>
...
-
}
----
+<1> must have a no-arg constructor for subsequent "recreation" by the framework.
-View models must have a no-arg constructor, but there are few other constraints.
-* if the view model has dependencies on domain services, then either:
-* instantiate using `DomainObjectContainer#newTransientInstance()` or
-* instantiate directly and then inject explicitly using `DomainObjectContainer#injectServicesInto(.)`
-* if the view model has no dependencies on domain services, then just instantiate directly
+To instantiate a view model, you can either instantiate directly using its constructor, or indirectly using `DomainObjectContainer#newTransientInstance()`. If you use the former, also programmatically call `DomainObjectContainer#injectServicesInto(...)` to ensure that any dependencies are injected into the service.
[TIP]