[isis] branch master updated: ISIS-2158: reinstate deprecated FactoryService.instantiate

[ah...@apache.org]

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 294d488  ISIS-2158: reinstate deprecated FactoryService.instantiate
294d488 is described below

commit 294d488168fe7dd6dd10e6138dc863a89d533427
Author: Andi Huber <ah...@apache.org>
AuthorDate: Fri Jan 24 11:33:23 2020 +0100

    ISIS-2158: reinstate deprecated FactoryService.instantiate
    
    - for graceful backward compatibility
---
 .../applib/services/factory/FactoryService.java    | 36 ++++++++++++++++++++++
 1 file changed, 36 insertions(+)

diff --git a/api/applib/src/main/java/org/apache/isis/applib/services/factory/FactoryService.java b/api/applib/src/main/java/org/apache/isis/applib/services/factory/FactoryService.java
index fab230d..06c4ac1 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/services/factory/FactoryService.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/services/factory/FactoryService.java
@@ -117,5 +117,41 @@ public interface FactoryService {
      */
     <T> T create(Class<T> domainClass);
 
+    // -- DEPRECATIONS
 
+    /**
+     * Creates a new instance of the specified class, but does not persist it.
+     *
+     * <p>
+     * It is recommended that the object be initially instantiated using
+     * this method, though the framework will also handle the case when
+     * the object is simply <i>new()</i>ed up.  The benefits of using
+     * {@link #instantiate(Class)} are:
+     * </p>
+     *
+     * <ul>
+     * <li>any services will be injected into the object immediately
+     *     (otherwise they will not be injected until the framework
+     *     becomes aware of the object, typically when it is
+     *     {@link RepositoryService#persist(Object) persist}ed</li>
+     * <li>the default value for any properties (usually as specified by
+     *     <tt>default<i>Xxx</i>()</tt> supporting methods) will (since 2.0) be
+     *     used</li>
+     * <li>the <tt>created()</tt> callback will not be called.
+     * </ul>
+     *
+     * <p>
+     * The corollary is: if your code never uses <tt>default<i>Xxx</i>()</tt>
+     * supporting methods or the <tt>created()</tt> callback, then you can
+     * alternatively just <i>new()</i> up the object rather than call this
+     * method.
+     * </p>
+     * @deprecated with semantic changes since 2.0 previous behavior is no longer guaranteed, 
+     * instead consider use of {@link #getOrCreate(Class)} if applicable
+     */
+    @Deprecated
+    default <T> T instantiate(Class<T> domainClass) {
+        return getOrCreate(domainClass);
+    }
+    
 }