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 12:47:30 UTC
isis git commit: ISIS-1133: @HomePage, @Facets, @Inject.
Repository: isis
Updated Branches:
refs/heads/ISIS-1133 77e527216 -> acba489f6
ISIS-1133: @HomePage, @Facets, @Inject.
Project: http://git-wip-us.apache.org/repos/asf/isis/repo
Commit: http://git-wip-us.apache.org/repos/asf/isis/commit/acba489f
Tree: http://git-wip-us.apache.org/repos/asf/isis/tree/acba489f
Diff: http://git-wip-us.apache.org/repos/asf/isis/diff/acba489f
Branch: refs/heads/ISIS-1133
Commit: acba489f60abd349d076ec4990829f32b9a53b75
Parents: 77e5272
Author: Dan Haywood <da...@haywood-associates.co.uk>
Authored: Thu Jun 4 11:47:23 2015 +0100
Committer: Dan Haywood <da...@haywood-associates.co.uk>
Committed: Thu Jun 4 11:47:23 2015 +0100
----------------------------------------------------------------------
...ug_reference-annotations_manpage-Facets.adoc | 12 +--
..._reference-annotations_manpage-HomePage.adoc | 46 +++++++--
...ug_reference-annotations_manpage-Inject.adoc | 103 ++++++++++++++++++-
.../reference-annotations/HomePage/HomePage.png | Bin 0 -> 134848 bytes
4 files changed, 146 insertions(+), 15 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/isis/blob/acba489f/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Facets.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Facets.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Facets.adoc
index bd0be60..7c8513b 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Facets.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Facets.adoc
@@ -4,14 +4,12 @@
:_basedir: ../
:_imagesdir: images/
-IMPORTANT: TODO
-The `@Facets` annotation specifies `FacetFactory` implementations and so can be used to run install arbitrary `Facet`s for a type. Generally this is not needed, but can be useful for overriding a custom programming model where a `FacetFactory` is not typically included.
+The `@Facets` annotation allows `FacetFactory` implementations and so can be used to run install arbitrary `Facet`s for a type. Generally this is not needed, but can be useful for overriding a custom programming model where a `FacetFactory` is not typically included.
-For example:
-
-[source,java]
-----
-----
+[NOTE]
+====
+`FacetFactory` is an important internal API that is used by Isis to
+====
http://git-wip-us.apache.org/repos/asf/isis/blob/acba489f/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-HomePage.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-HomePage.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-HomePage.adoc
index 05efbdf..90ae639 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-HomePage.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-HomePage.adoc
@@ -4,17 +4,49 @@
:_basedir: ../
:_imagesdir: images/
-IMPORTANT: TODO
+The `@HomePage` annotation allows a _single_ (no-arg, query-only) action on a _single_ domain service to be nominated as the action to invoke for the default home page. This often returns a view model that acts as some sort of dashboard, presenting key information and makeing the most commonly used actions easy to invoke.
+For example, the (non-ASF) http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp] uses `@HomePage` to return a dashboard of todo items to complete:
-[NOTE]
-====
-Currently only by the xref:_ug_wicket-viewer[Wicket Viewer].
-====
+image::{_imagesdir}reference-annotations/HomePage/HomePage.png[width="800px",link="{_imagesdir}reference-annotations/HomePage/HomePage.png"]
-The `@HomePage` annotation should be applied to a single (no-arg) action on a domain service, and the results used as the contents for the home page.
+The corresponding code is:
+
+[source,java]
+----
+@DomainService(nature = NatureOfService.DOMAIN)
+public class ToDoAppDashboardService {
+ @Action(
+ semantics = SemanticsOf.SAFE
+ )
+ @HomePage
+ public ToDoAppDashboard lookup() {
+ return container.injectServicesInto(new ToDoAppDashboard());
+ }
+ @Inject
+ private DomainObjectContainer container;
+}
+----
+
+where `ToDoAppDashboard` is:
+
+[source,java]
+----
+@DomainObject(nature = Nature.VIEW_MODEL)
+public class ToDoAppDashboard {
+ public String title() { return "Dashboard"; }
+
+ public List<ToDoItem> getNotYetComplete() { ... }
+ public List<ToDoItem> getComplete() { ... }
+
+ public Blob exportToWordDoc() { ... } // <1>
+}
+----
+<1> associated using xref:_ug_wicket-viewer_layout_dynamic-object-layout[dynamic layouts] with the `notYetComplete` collection.
+
+The other two actions shown in the above screenshot -- `exportAsXml` and `downloadLayout` -- are actually contributed to the `ToDoAppDashboard` through various domain services, as is the `downloadLayout` action.
+
-Typically this action would return a xref:_ug_more-advanced_view-models[View Model] representing a dashboard from which the user can navigate to commonly used objects and invoked actions. But it could also simply invoke an action that returns an entity (eg representing the currently logged-on user) or a list of objects.
http://git-wip-us.apache.org/repos/asf/isis/blob/acba489f/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Inject.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Inject.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Inject.adoc
index e83134c..4b5c70a 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Inject.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Inject.adoc
@@ -4,6 +4,107 @@
:_basedir: ../
:_imagesdir: images/
-IMPORTANT: TODO
+Apache Isis automatically injects domain services into other domain services and also into domain objects and view models. In fact, it also injects domain services into xref:_ug_testing_integ-test-support[integration tests] and xref:_ug_testing_fixture-scripts[fixture scripts].
+
+[NOTE]
+====
+One omission: Isis (currently) does not inject services into `o.a.i.applib.spec.Specification` instances (as used by xref:_ug_reference-annotations_manpage-Property_mustSatisfy[`@Property#mustSatisfy()`] and xref:_ug_reference-annotations_manpage-Parameter_mustSatisfy[`@Parameter#mustSatisfy()`] annotations.
+====
+
+Isis supports several syntaxes for injecting domain services. The simplest uses the `@javax.inject.Inject` annotation on the field, as defined in link:https://jcp.org/en/jsr/detail?id=330[JSR-330].
+
+For example:
+
+[source,java]
+----
+public class Customer {
+ public List<Order> findRecentOrders() { // <1>
+ return orders.recentOrdersFor(this);
+ }
+ @javax.inject.Inject
+ OrderRepository orders; // <2>
+}
+----
+<1> an alternative implementation would be to implement `findRecentOrders()` as a xref:_ug_how-tos_contributed-members[contributed action].
+<2> we recommend default (rather than `private`) visibility so that unit tests can easily mock out the service
+
+
+
+== Alternative syntaxes
+
+Isis also supports setter-based injection:
+
+[source,java]
+----
+public class Customer {
+ ...
+ public void setOrderRepository(OrderRepository orderRepository) { ... }
+}
+----
+
+and also supports an additional syntax of using `inject...` as the prefix:
+
+[source,java]
+----
+public class Customer {
+ ...
+ public void injectOrderRepository(OrderRepository orderRepository) { ... }
+}
+----
+
+Generally we recommend using `@javax.inject.Inject`; it involves less code, and is more immediately familiar to most Java developers.
+
+
+
+== Manually injecting services
+
+Isis performs dependency injection when domain entities are recreated. It will also perform dependency injection if an object is created through the `DomainObjectContainer`.
+
+For example, to create a new (transient) domain object, the idiom is:
+
+[source,java]
+----
+Customer cust = container.newTransientInstance(Customer.class); <1>
+// initialize state of "cust"
+container.persist(cust);
+----
+<1> where `container` is an instance of xref:_ug_reference-services-api_manpage-DomainObjectContainer[`DomainObjectContainer`].
+
+View models are created similarly:
+
+[source,java]
+----
+ToDoAppDashboard dashboard = container.newViewModelInstance(ToDoAppDashboard.class);
+----
+
+
+If you prefer, though, you can simply instantiate domain objects using "new" and then inject domain services manually:
+
+
+[source,java]
+----
+Customer cust = new Customer();
+container.injectServicesInto(cust);
+// initialize state of "cust"
+container.persist(cust);
+----
+
+
+or if you prefer:
+
+[source,java]
+----
+Customer cust = container.injectServicesInto(new Customer());
+// initialize state of "cust"
+container.persist(cust);
+----
+
+
+[NOTE]
+====
+There is one subtle difference between using `DomainObjectContainer#newTransientInstance(...)` and `DomainObjectContainer#injectServicesInto(...)`, in that with the former Isis will automatically initialize all fields to their default values.
+
+This isn't a particular useful feature (and indeed can sometimes be rather confusing) so you may well wish to standardize on using `injectServicesInto(...)` throughout.
+====
http://git-wip-us.apache.org/repos/asf/isis/blob/acba489f/adocs/documentation/src/main/asciidoc/user-guide/images/reference-annotations/HomePage/HomePage.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/reference-annotations/HomePage/HomePage.png b/adocs/documentation/src/main/asciidoc/user-guide/images/reference-annotations/HomePage/HomePage.png
new file mode 100644
index 0000000..59880f4
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/user-guide/images/reference-annotations/HomePage/HomePage.png differ