Implement waitForCompletionOrCreateCheckStatusResponse (microsoft#115)

* implement waitForCompletionOrCreateCheckStatusResponse

* update CHANGELOG

* remove comments

* correct PR link in CHANGELOG

* add javadoc

* fix javadoc

Author: kaibocai

CHANGELOG.md

@@ -3,6 +3,7 @@
 ### Updates
 * Support Suspend and Resume Client APIs ([#104](https://github.com/microsoft/durabletask-java/issues/104))
 * Fix the potential NPE issue of `DurableTaskClient terminate` method ([#104](https://github.com/microsoft/durabletask-java/issues/104))
+* Add waitForCompletionOrCreateCheckStatusResponse client API ([#115](https://github.com/microsoft/durabletask-java/pull/115))
 
 
 ## v1.0.0

azurefunctions/src/main/java/com/microsoft/durabletask/azurefunctions/DurableClientContext.java

@@ -9,12 +9,16 @@
 import com.microsoft.azure.functions.HttpStatus;
 import com.microsoft.durabletask.DurableTaskClient;
 import com.microsoft.durabletask.DurableTaskGrpcClientBuilder;
+import com.microsoft.durabletask.OrchestrationMetadata;
+import com.microsoft.durabletask.OrchestrationRuntimeStatus;
 
 import java.io.UnsupportedEncodingException;
 import java.net.MalformedURLException;
 import java.net.URL;
 import java.net.URLEncoder;
 import java.nio.charset.StandardCharsets;
+import java.time.Duration;
+import java.util.concurrent.TimeoutException;
 
 /**
  * The binding value type for the {@literal @}DurableClientInput parameter.
@@ -24,6 +28,7 @@ public class DurableClientContext {
     private String rpcBaseUrl;
     private String taskHubName;
     private String requiredQueryStringParameters;
+    private DurableTaskClient client;
 
     /**
      * Gets the name of the client binding's task hub.
@@ -51,9 +56,55 @@ public DurableTaskClient getClient() {
             throw new IllegalStateException("The client context RPC base URL was invalid!", ex);
         }
 
-        return new DurableTaskGrpcClientBuilder().port(rpcURL.getPort()).build();
+        this.client = new DurableTaskGrpcClientBuilder().port(rpcURL.getPort()).build();
+        return this.client;
     }
 
+    /**
+     * Creates an HTTP response which either contains a payload of management URLs for a non-completed instance
+     * or contains the payload containing the output of the completed orchestration.
+     * <p>
+     * If the orchestration instance completes within the specified timeout, then the HTTP response payload will
+     * contains the output of the orchestration instance formatted as JSON. However, if the orchestration does not
+     * complete within the specified timeout, then the HTTP response will be identical to that of the
+     * {@link #createCheckStatusResponse(HttpRequestMessage, String)} API.
+     * </p>
+     * @param request the HTTP request that triggered the current function
+     * @param instanceId the unique ID of the instance to check
+     * @param timeout total allowed timeout for output from the durable function
+     * @return an HTTP response which may include a 202 and location header or a 200 with the durable function output in the response body
+     */
+    public HttpResponseMessage waitForCompletionOrCreateCheckStatusResponse(
+            HttpRequestMessage<?> request,
+            String instanceId,
+            Duration timeout) {
+        if (this.client == null) {
+            this.client = getClient();
+        }
+        OrchestrationMetadata orchestration;
+        try {
+            orchestration = this.client.waitForInstanceCompletion(instanceId, timeout, true);
+            return request.createResponseBuilder(HttpStatus.ACCEPTED)
+                    .header("Content-Type", "application/json")
+                    .body(orchestration.getSerializedOutput())
+                    .build();
+        } catch (TimeoutException e) {
+            return createCheckStatusResponse(request, instanceId);
+        }
+    }
+
+    /**
+     * Creates an HTTP response that is useful for checking the status of the specified instance.
+     * <p>
+     * The payload of the returned
+     * @see <a href="https://learn.microsoft.com/java/api/com.microsoft.azure.functions.httpresponsemessage">HttpResponseMessage</a>
+     * contains HTTP API URLs that can be used to query the status of the orchestration, raise events to the orchestration, or
+     * terminate the orchestration.
+     * </p>
+     * @param request the HTTP request that triggered the current orchestration instance
+     * @param instanceId the ID of the orchestration instance to check
+     * @return an HTTP 202 response with a Location header and a payload containing instance control URLs
+     */
     public HttpResponseMessage createCheckStatusResponse(HttpRequestMessage<?> request, String instanceId) {
         // TODO: To better support scenarios involving proxies or application gateways, this
         //       code should take the X-Forwarded-Host, X-Forwarded-Proto, and Forwarded HTTP