This is an automated email from the ASF dual-hosted git repository.
ahuber pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/isis.git
The following commit(s) were added to refs/heads/master by this push:
new e61456cc7e ISIS-3293: new revised java-doc for ViewModel
e61456cc7e is described below
commit e61456cc7eaddc289a7f8a6915a85916ea22ea3e
Author: Andi Huber <[email protected]>
AuthorDate: Thu Nov 24 11:24:50 2022 +0100
ISIS-3293: new revised java-doc for ViewModel
---
.../java/org/apache/causeway/applib/ViewModel.java | 37 ++++++++++++++++++----
1 file changed, 30 insertions(+), 7 deletions(-)
diff --git a/api/applib/src/main/java/org/apache/causeway/applib/ViewModel.java
b/api/applib/src/main/java/org/apache/causeway/applib/ViewModel.java
index aa2eac68da..8b1bd3bd83 100644
--- a/api/applib/src/main/java/org/apache/causeway/applib/ViewModel.java
+++ b/api/applib/src/main/java/org/apache/causeway/applib/ViewModel.java
@@ -18,22 +18,45 @@
*/
package org.apache.causeway.applib;
+import java.util.NoSuchElementException;
+
import org.apache.causeway.applib.annotation.Programmatic;
+import org.apache.causeway.applib.services.factory.FactoryService;
+import org.apache.causeway.applib.services.inject.ServiceInjector;
+import org.apache.causeway.applib.services.registry.ServiceRegistry;
/**
- * Indicates that an object belongs to the UI/application layer, and is
intended to be used as a view model.
+ * Indicates that an object belongs to the UI/application layer and is
intended to be used as a view-model.
+ * <p>
+ * Instances of {@link ViewModel} must include (exactly) one public
constructor.
+ * <p>
+ * Contract:
+ * <ul>
+ * <li>there is a single public constructor</li>
+ * <li>it may have arbitrary many arguments of arbitrary type</li>
+ * <li>first {@link String} argument found is passed in the view-model's
memento</li>
+ * <li>any other arguments are resolved via the {@link ServiceRegistry} -
+ * if no <i>Bean</i> can be found a {@link NoSuchElementException} is
thrown</li>
+ * <li>@Inject or @Autowired annotations are not required on the
constructor</li>
+ * <li>there is no support for Spring programming model specific annotations
on constructor arguments (perhaps future work)</li>
+ * </ul>
+ * Naturally this also allows for the idiom of passing in the {@link
ServiceInjector} as an argument
+ * and programmatically resolve any field-style injection points via {@link
ServiceInjector#injectServicesInto(Object)},
+ * that is, if already required during <i>construction</i>.
+ * <p>
+ * After a view-model got new-ed up by the framework (or programmatically via
the {@link FactoryService}),
+ * {@link ServiceInjector#injectServicesInto(Object)} is called on the
viewmodel instance,
+ * regardless of what happened during <i>construction</i>.
*
- * @since 1.x {@index}
+ * @since 1.x - revised for 2.0 {@index}
*/
public interface ViewModel {
/**
- * Obtain a memento of the view model.
+ * Obtain a memento of the view-model. (Optional)
* <p>
- * Instances of {@link ViewModel} must include a public single {@link
String} argument constructor,
- * that recreates an instance from a memento string.
- * This constructor is not required to resolve injection points or fire
domain events,
- * instead this responsibility is encapsulated with the framework.
+ * Captures the state of this view-model as {@link String},
+ * which can be passed in to this view-model's constructor for later
re-construction.
*/
@Programmatic
String viewModelMemento();
