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 <ahu...@apache.org> 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();