Fixing CallChain to be easier to use for consistent pattern to use

src/main/java/software/amazon/cloudformation/LambdaWrapper.java

@@ -62,6 +62,7 @@
 import software.amazon.cloudformation.proxy.CallbackAdapter;
 import software.amazon.cloudformation.proxy.CloudFormationCallbackAdapter;
 import software.amazon.cloudformation.proxy.Credentials;
+import software.amazon.cloudformation.proxy.DelayFactory;
 import software.amazon.cloudformation.proxy.HandlerErrorCode;
 import software.amazon.cloudformation.proxy.HandlerRequest;
 import software.amazon.cloudformation.proxy.LoggerProxy;
@@ -126,7 +127,7 @@ protected LambdaWrapper() {
  this.typeReference = getTypeReference();
  }
 
- /**
+ /*
  * This .ctor provided for testing
  */
  public LambdaWrapper(final CallbackAdapter<ResourceT> callbackAdapter,
@@ -385,7 +386,8 @@ public void handleRequest(final InputStream inputStream, final OutputStream outp
  if (request.getRequestData().getCallerCredentials() != null) {
  awsClientProxy = new AmazonWebServicesClientProxy(requestContext == null, this.loggerProxy,
  request.getRequestData().getCallerCredentials(),
- () -> (long) context.getRemainingTimeInMillis());
+ () -> (long) context.getRemainingTimeInMillis(),
+ DelayFactory.CONSTANT_DEFAULT_DELAY_FACTORY);
  }
 
  boolean computeLocally = true;
@@ -600,14 +602,24 @@ protected abstract ResourceHandlerRequest<ResourceT> transform(HandlerRequest<Re
 
  /**
  * Implemented by the handler package as the key entry point.
+ *
+ * @param proxy Amazon webservice proxy to inject credentials correctly.
+ * @param request incoming request for the call
+ * @param action which action to take {@link Action#CREATE},
+ * {@link Action#DELETE}, {@link Action#READ} {@link Action#LIST} or
+ * {@link Action#UPDATE}
+ * @param callbackContext the callback context to handle reentrant calls
+ * @return progress event indicating success, in progress with delay callback or
+ * failed state
+ * @throws Exception propagate any unexpected errors
  */
  public abstract ProgressEvent<ResourceT, CallbackT> invokeHandler(AmazonWebServicesClientProxy proxy,
  ResourceHandlerRequest<ResourceT> request,
  Action action,
  CallbackT callbackContext)
  throws Exception;
 
- /**
+ /*
  * null-safe exception metrics delivery
  */
  private void publishExceptionMetric(final Action action, final Throwable ex, final HandlerErrorCode handlerErrorCode) {

src/main/java/software/amazon/cloudformation/injection/CredentialsProvider.java

@@ -20,12 +20,14 @@
 public interface CredentialsProvider {
 
  /**
- * Return the current set of credentials for initialising AWS SDK Clients
+ * @return the current set of credentials for initialising AWS SDK Clients
  */
  AwsSessionCredentials get();
 
  /**
  * Inject a new set of credentials (passed through from caller)
+ *
+ * @param credentials, incoming credentials for the call that is being made
  */
  void setCredentials(Credentials credentials);
 }

src/main/java/software/amazon/cloudformation/proxy/CallChain.java

@@ -31,7 +31,7 @@
  *
  * <ol>
  * <li>{@link CallChain#initiate(String, ProxyClient, Object, StdCallbackContext)}
- * <li>{@link RequestMaker#request(Function)}
+ * <li>{@link RequestMaker#translate(Function)}
  * <li>{@link Caller#call(BiFunction)}
  * <li>{@link Completed#done(Function)}
  * </ol>
@@ -40,6 +40,79 @@
  */
 public interface CallChain {
 
+ /**
+ * Provides an API initiator interface that works for all API calls that need
+ * conversion, retry-backoff strategy, common exception handling and more
+ * against desired state of the resource and callback context. This needs to be
+ * instantiated once with the client, model and callback context and used. It
+ * takes a reference to the desired state model, so any changes made on the
+ * model object will be reflected here. The model and callback can accessed from
+ * the instantiator instance
+ *
+ * @param <ClientT> the AWS Service client.
+ * @param <ModelT> the model object being worked on
+ * @param <CallbackT> the callback context
+ */
+ interface Initiator<ClientT, ModelT, CallbackT extends StdCallbackContext> {
+ /**
+ * Each service call must be first initiated. Every call is provided a separate
+ * name called call graph. This is essential from both a tracing perspective as
+ * well as {@link StdCallbackContext} automated replay capabilities.
+ *
+ * @param callGraph, the name of the service operation this call graph is about.
+ * @return Provides the next logical set in the fluent API.
+ */
+ RequestMaker<ClientT, ModelT, CallbackT> initiate(String callGraph);
+
+ /**
+ * @return the model associated with the API initiator. Can not be null
+ */
+ ModelT getResourceModel();
+
+ /**
+ * @return the callback context associated with API initiator, Can not be null
+ */
+ CallbackT getCallbackContext();
+
+ /**
+ * Can rebind a new model to the call chain while retaining the client and
+ * callback context
+ *
+ * @param model, the new model for the callchain initiation
+ * @param <NewModelT>, this actual model type
+ * @return new {@link Initiator} that now has the new model associated with it
+ */
+ <NewModelT> Initiator<ClientT, NewModelT, CallbackT> rebindModel(NewModelT model);
+
+ /**
+ * Can rebind a new callback context for a call chain while retaining the model
+ * and client
+ *
+ * @param callback the new callback context
+ * @param <NewCallbackT> new callback context type
+ * @return new {@link Initiator} that now has the new callback associated with
+ * it
+ */
+ <NewCallbackT extends StdCallbackContext> Initiator<ClientT, ModelT, NewCallbackT> rebindCallback(NewCallbackT callback);
+ }
+
+ /**
+ * factory method can created an {@link Initiator}
+ *
+ * @param client AWS Service Client. Recommend using Sync client as the
+ * framework handles interleaving as needed.
+ * @param model the resource desired state model, usually
+ * @param context callback context that tracks all outbound API calls
+ * @param <ClientT> Actual client e.g. KinesisClient.
+ * @param <ModelT> The type (POJO) of Resource model.
+ * @param <CallbackT>, callback context the extends {@link StdCallbackContext}
+ *
+ * @return an instance of the {@link Initiator}
+ */
+ <ClientT, ModelT, CallbackT extends StdCallbackContext>
+ Initiator<ClientT, ModelT, CallbackT>
+ newInitiator(ProxyClient<ClientT> client, ModelT model, CallbackT context);
+
  /**
  * Each service call must be first initiated. Every call is provided a separate
  * name called call graph. This is eseential from both a tracing perspective as
@@ -71,32 +144,54 @@ public interface CallChain {
  */
  interface RequestMaker<ClientT, ModelT, CallbackT extends StdCallbackContext> {
  /**
+ * use {@link #translate(Function)}
+ *
  * Take a reference to the tranlater that take the resource model POJO as input
  * and provide a request object as needed to make the Service call.
  *
  * @param maker, provide a functional transform from model to request object.
  * @param <RequestT>, the web service request created
  * @return returns the next step, to actually call the service.
  */
- <RequestT> Caller<RequestT, ClientT, ModelT, CallbackT> request(Function<ModelT, RequestT> maker);
+ @Deprecated
+ default <RequestT> Caller<RequestT, ClientT, ModelT, CallbackT> request(Function<ModelT, RequestT> maker) {
+ return translate(maker);
+ }
+
+ /**
+ * Take a reference to the tranlater that take the resource model POJO as input
+ * and provide a request object as needed to make the Service call.
+ *
+ * @param maker, provide a functional transform from model to request object.
+ * @param <RequestT>, the web service request created
+ * @return returns the next step, to actually call the service.
+ */
+ <RequestT> Caller<RequestT, ClientT, ModelT, CallbackT> translate(Function<ModelT, RequestT> maker);
  }
 
  /**
  * This Encapsulates the actual Call to the service that is being made via
  * caller. This allow for the proxy to intercept and wrap the caller in cases of
  * replay and provide the memoized response back
  *
- * @param <RequestT>
- * @param <ClientT>
- * @param <ModelT>
- * @param <CallbackT>
+ * @param <RequestT>, the AWS serivce request we are making
+ * @param <ClientT>, the web service client to make the call
+ * @param <ModelT>, the current model we are using
+ * @param <CallbackT>, the callback context for handling all AWS service request
+ * responses
  */
  interface Caller<RequestT, ClientT, ModelT, CallbackT extends StdCallbackContext> {
  <ResponseT>
  Stabilizer<RequestT, ResponseT, ClientT, ModelT, CallbackT>
  call(BiFunction<RequestT, ProxyClient<ClientT>, ResponseT> caller);
 
- Caller<RequestT, ClientT, ModelT, CallbackT> retry(Delay delay);
+ @Deprecated
+ default Caller<RequestT, ClientT, ModelT, CallbackT> retry(Delay delay) {
+ return backoff(delay);
+ }
+
+ Caller<RequestT, ClientT, ModelT, CallbackT> backoff(Delay delay);
+
  }
 
  /**
@@ -154,8 +249,39 @@ interface Exceptional<RequestT, ResponseT, ClientT, ModelT, CallbackT extends St
  * @return true of you want to attempt another retry of the operation. false to
  * indicate propagate error/fault.
  */
+ @Deprecated
+ default Completed<RequestT, ResponseT, ClientT, ModelT, CallbackT>
+ exceptFilter(Callback<? super RequestT, Exception, ClientT, ModelT, CallbackT, Boolean> handler) {
+ return retryErrorFilter(handler);
+ }
+
+ /**
+ * @param handler, a predicate lambda expression that takes the web request,
+ * exception, client, model and context to determine to retry the
+ * exception thrown by the service or fail operation. This is the
+ * simpler model then {@link #handleError(ExceptionPropagate)} for
+ * most common retry scenarios If we need more control over the
+ * outcome, then use {@link #handleError(ExceptionPropagate)}
+ * @return true of you want to attempt another retry of the operation. false to
+ * indicate propagate error/fault.
+ */
  Completed<RequestT, ResponseT, ClientT, ModelT, CallbackT>
- exceptFilter(Callback<? super RequestT, Exception, ClientT, ModelT, CallbackT, Boolean> handler);
+ retryErrorFilter(Callback<? super RequestT, Exception, ClientT, ModelT, CallbackT, Boolean> handler);
+
+ /**
+ * @param handler, a lambda expression that takes the web request, response,
+ * client, model and context returns a successful or failed
+ * {@link ProgressEvent} back or can rethrow service exception to
+ * propagate errors. If handler needs to retry the exception, the it
+ * will throw a
+ * {@link software.amazon.awssdk.core.exception.RetryableException}
+ * @return a ProgressEvent for the model
+ */
+ @Deprecated
+ default Completed<RequestT, ResponseT, ClientT, ModelT, CallbackT> exceptHandler(ExceptionPropagate<? super RequestT,
+ Exception, ClientT, ModelT, CallbackT, ProgressEvent<ModelT, CallbackT>> handler) {
+ return handleError(handler);
+ }
 
  /**
  * @param handler, a lambda expression that take the web request, response,
@@ -164,8 +290,26 @@ interface Exceptional<RequestT, ResponseT, ClientT, ModelT, CallbackT extends St
  * @return If status is {@link OperationStatus#IN_PROGRESS} we will attempt
  * another retry. Otherwise failure is propagated.
  */
- Completed<RequestT, ResponseT, ClientT, ModelT, CallbackT> exceptHandler(Callback<? super RequestT, Exception, ClientT,
- ModelT, CallbackT, ProgressEvent<ModelT, CallbackT>> handler);
+ Completed<RequestT, ResponseT, ClientT, ModelT, CallbackT> handleError(ExceptionPropagate<? super RequestT, Exception,
+ ClientT, ModelT, CallbackT, ProgressEvent<ModelT, CallbackT>> handler);
+ }
+
+ /**
+ * When implementing this interface, developers can either propagate the
+ * exception as is. If the exception can be retried, throw
+ * {@link software.amazon.awssdk.core.exception.RetryableException}
+ *
+ * @param <RequestT> the API request object
+ * @param <E> the exception that is thrown by the API
+ * @param <ClientT> the service client
+ * @param <ModelT> current desired state resource model
+ * @param <CallbackT> current callback context
+ * @param <ReturnT> result object
+ */
+ @FunctionalInterface
+ interface ExceptionPropagate<RequestT, E extends Exception, ClientT, ModelT, CallbackT extends StdCallbackContext, ReturnT> {
+ ReturnT invoke(RequestT request, E exception, ProxyClient<ClientT> client, ModelT model, CallbackT context)
+ throws Exception;
  }
 
  /**
@@ -242,24 +386,27 @@ interface Completed<RequestT, ResponseT, ClientT, ModelT, CallbackT extends StdC
  done(Callback<RequestT, ResponseT, ClientT, ModelT, CallbackT, ProgressEvent<ModelT, CallbackT>> callback);
 
  /**
- * Helper function that provides a {@link OperationStatus#SUCCESS} status when
- * the callchain is done
+ * @return {@link ProgressEvent} Helper function that provides a
+ *  {@link OperationStatus#SUCCESS} status when the callchain is done
  */
  default ProgressEvent<ModelT, CallbackT> success() {
  return done((request, response, client, model, context) -> ProgressEvent.success(model, context));
  }
 
  /**
- * Helper function that provides a {@link OperationStatus#IN_PROGRESS} status
- * when the callchain is done
+ * @return {@link ProgressEvent} Helper function that provides a
+ *  {@link OperationStatus#IN_PROGRESS} status when the callchain is done
  */
  default ProgressEvent<ModelT, CallbackT> progress() {
  return progress(0);
  }
 
  /**
- * Helper function that provides a {@link OperationStatus#IN_PROGRESS} status
- * when the callchain is done
+ * @param callbackDelay the number of seconds to delay before calling back into
+ * this externally
+ * @return {@link ProgressEvent} Helper function that provides a
+ * {@link OperationStatus#IN_PROGRESS} status when the callchain is done
+ * with callback delay
  */
  default ProgressEvent<ModelT, CallbackT> progress(int callbackDelay) {
  return done((request, response, client, model, context) -> ProgressEvent.defaultInProgressHandler(context,

src/main/java/software/amazon/cloudformation/proxy/CallbackAdapter.java

@@ -33,7 +33,8 @@ public interface CallbackAdapter<T> {
  *
  * @param bearerToken unique identifier for this provisioning operation
  * @param errorCode (optional) error code in case of fault
- * @param operationStatus current status of provisioning operation
+ * @param operationStatus new status of provisioning operation
+ * @param currentOperationStatus current status of provisioning operation
  * @param resourceModel the current state of the provisioned resource
  * @param statusMessage (optional) progress status which may be shown to end
  * user

src/main/java/software/amazon/cloudformation/proxy/Delay.java

@@ -47,10 +47,8 @@ public interface Delay {
  * values
  *
  * @param attempt, starts with 1
- * @return the next amount to stabilize for. return -1 to indicate delay is
- * complete
- * @return the next amount to stabilize for. returns {@link Duration#ZERO} to
- * indicate delay is complete
+ * @return the next amount to wait for or {@link Duration#ZERO} to indicate
+ * delay is complete
  */
  Duration nextDelay(int attempt);
 

src/main/java/software/amazon/cloudformation/proxy/DelayFactory.java

@@ -0,0 +1,28 @@
+/*
+* Copyright 2010-2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+*
+* Licensed under the Apache License, Version 2.0 (the "License").
+* You may not use this file except in compliance with the License.
+* A copy of the License is located at
+*
+* http://aws.amazon.com/apache2.0
+*
+* or in the "license" file accompanying this file. This file is distributed
+* on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
+* express or implied. See the License for the specific language governing
+* permissions and limitations under the License.
+*/
+package software.amazon.cloudformation.proxy;
+
+import java.time.Duration;
+import software.amazon.cloudformation.proxy.delay.Constant;
+
+@FunctionalInterface
+public interface DelayFactory {
+ DelayFactory CONSTANT_DEFAULT_DELAY_FACTORY = (apiCall, incoming) -> incoming != null
+ ? incoming
+ : Constant.of().delay(Duration.ofSeconds(5)).timeout(Duration.ofMinutes(20)).build();
+
+ Delay getDelay(String apiCall, Delay provided);
+
+}