[isis] branch master updated: ISIS-2158: rest-client: polishing the API + java-doc

[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 a06784d  ISIS-2158: rest-client: polishing the API + java-doc
a06784d is described below

commit a06784d6beed8204f22a2d10b6ae71e44e1d2106
Author: Andi Huber <ah...@apache.org>
AuthorDate: Fri Jan 31 08:18:31 2020 +0100

    ISIS-2158: rest-client: polishing the API + java-doc
---
 .../isis/extensions/restclient/ResponseDigest.java | 41 ++++++++++++++++++----
 1 file changed, 35 insertions(+), 6 deletions(-)

diff --git a/mappings/restclient/api/src/main/java/org/apache/isis/extensions/restclient/ResponseDigest.java b/mappings/restclient/api/src/main/java/org/apache/isis/extensions/restclient/ResponseDigest.java
index f7dbba8..6f65b49d 100644
--- a/mappings/restclient/api/src/main/java/org/apache/isis/extensions/restclient/ResponseDigest.java
+++ b/mappings/restclient/api/src/main/java/org/apache/isis/extensions/restclient/ResponseDigest.java
@@ -24,9 +24,11 @@ import java.nio.charset.StandardCharsets;
 import java.util.ArrayList;
 import java.util.List;
 import java.util.NoSuchElementException;
+import java.util.Optional;
 import java.util.concurrent.Future;
 import java.util.function.Function;
 
+import javax.annotation.Nullable;
 import javax.ws.rs.core.GenericType;
 import javax.ws.rs.core.Response;
 import javax.ws.rs.core.Response.Status.Family;
@@ -110,31 +112,58 @@ public class ResponseDigest<T> {
         this.genericType = genericType;
     }
 
+    /**
+     * @return whether the REST endpoint replied with a success status code.
+     */
     public boolean isSuccess() {
         return !isFailure();
     }
 
+    /**
+     * @return whether the REST endpoint replied with a failure status code.
+     */
     public boolean isFailure() {
         return failureCause!=null;
     }
-
+    
+    /**
+     * @return (non-null), optionally the result if cardinality is exactly ONE
+     */
+    public Optional<T> getEntity(){
+        return getEntities().getSingleton();
+    }
+    
+    /**
+     * @return (non-null), the entities replied by the REST endpoint supporting any cardinality ZERO, ONE or more. 
+     */
     public Can<T> getEntities(){
         return entities;
     }
 
-    public Exception getFailureCause(){
+    /**
+     * @return (nullable), the failure case (if any), when the REST endpoint replied with a failure status code 
+     */
+    public @Nullable Exception getFailureCause(){
         return failureCause;
     }
 
-    public Can<T> ifSuccessGetOrElseMap(Function<Exception, Can<T>> failureMapper) {
+    /**
+     * @param failureMapper - fallback, to calculate a result from given failure exception 
+     * @return the result if cardinality is exactly ONE, otherwise the result of applying the failure to the {@code failureMapper} 
+     */
+    public T singletonOrElseMapFailure(Function<Exception, T> failureMapper) {
         return isSuccess() 
-                ? getEntities()
+                ? getEntity().orElseGet(()->failureMapper.apply(new NoSuchElementException()))
                         : failureMapper.apply(getFailureCause());
     }
 
-    public <X> X ifSuccessMapOrElseMap(Function<Can<T>, X> successMapper, Function<Exception, X> failureMapper) {
+    /**
+     * @param failureMapper - fallback, to calculate a result from given failure exception
+     * @return the result of any cardinality, otherwise the result of applying the failure to the {@code failureMapper} 
+     */
+    public Can<T> multipleOrElseMapFailure(Function<Exception, Can<T>> failureMapper) {
         return isSuccess() 
-                ? successMapper.apply(getEntities())
+                ? getEntities()
                         : failureMapper.apply(getFailureCause());
     }