Address type erasure/reflection issue

This is a pretty broad rewrite, because the former approach cannot work.
TracingRequestHandler's type parameters erase to `Object` at runtime, which
defeats AWS's reflection-based automatic deserialization mechanism.

The new approach uses composition over inheritance: the user provides their
own event handler, using any mechanism AWS supports, and wraps their
business logic with our instrumentation. This allows reflection to work as
intended.

In addition, the TracingRequestStreamHandler class's doHandler method didn't
allow for IOException to be thrown, despite it being more or less inevitable.
`StreamLambdaTracing` addresses this issue, while mirroring the design of
`LambdaTracing`.

Author: Matt Whelan

README.md

@@ -11,9 +11,15 @@ Versioning will have the following format: {majorVersion}.{minorVersion}.{pointV
 
 ### How it Works
 
-The SDK provides `TracingRequestHandler` and `TracingRequestStreamHandler` interfaces that extend AWS' Lambda request handlers. When a Lambda function that is using an implementation of either tracing request handler is invoked, the handler will obtain the globally registered OpenTracing [Tracer](https://opentracing.io/docs/overview/tracers/) and create/start an OpenTracing [Span](https://opentracing.io/docs/overview/spans/) to capture timing information and `key:value` pairs ([Tags/Logs](https://opentracing.io/docs/overview/tags-logs-baggage/)) detailing the trace data.
+The SDK provides `LambdaTracing` and `StreamLambdaTracing` classes that instrument requests. When a Lambda function 
+that is using an implementation of either class is invoked, the handler will obtain the globally registered OpenTracing 
+[Tracer](https://opentracing.io/docs/overview/tracers/) and create/start an OpenTracing 
+[Span](https://opentracing.io/docs/overview/spans/) to capture timing information and `key:value` pairs 
+([Tags/Logs](https://opentracing.io/docs/overview/tags-logs-baggage/)) detailing the trace data.
+
+As part of the implementation the user's handler must call the `instrument` method, passing a callback that contains 
+the business logic for their handler.
 
-As part of the implementation the user must override the tracing handler's `doHandleRequest` method which is called by the handler interface's `handleRequest` method.
 
 ### Collected Span Tags/Logs
 
@@ -42,7 +48,7 @@ Below are a list of the collected exception attributes:
 You can add the dependency by adding the following to your `build.gradle` file:
 ```
 dependencies {
-    compile "com.newrelic.opentracing:java-aws-lambda:2.0.0"
+    implementation "com.newrelic.opentracing:java-aws-lambda:2.1.0"
 }
 ```
 
@@ -59,36 +65,29 @@ dependencies {
 package com.handler.example;
 
 import com.amazonaws.services.lambda.runtime.Context;
-import com.newrelic.opentracing.aws.TracingRequestHandler;
+import com.amazonaws.services.lambda.runtime.RequestHandler;
+import com.amazonaws.services.lambda.runtime.events.APIGatewayProxyRequestEvent;
+import com.amazonaws.services.lambda.runtime.events.APIGatewayProxyResponseEvent;
+import com.newrelic.opentracing.LambdaTracer;
+import com.newrelic.opentracing.aws.LambdaTracing;
 import io.opentracing.util.GlobalTracer;
 
 import java.util.Map;
 
-/**
- * Tracing request handler that creates a span on every invocation of a Lambda.
- *
- * @param Map<String, Object> The Lambda Function input
- * @param String The Lambda Function output
- */
-public class MyLambdaHandler implements TracingRequestHandler<Map<String, Object>, String> {
+public static class YourLambdaHandler implements RequestHandler<APIGatewayProxyRequestEvent, APIGatewayProxyResponseEvent> {
     static {
         // Obtain an instance of the OpenTracing Tracer of your choice
-        Tracer tracer = new CustomTracer(...);
+        Tracer tracer = LambdaTracer.INSTANCE;
         // Register your tracer as the Global Tracer
         GlobalTracer.registerIfAbsent(tracer);
     }
-
-    /**
-     * Method that handles the Lambda function request.
-     *
-     * @param input The Lambda Function input
-     * @param context The Lambda execution environment context object
-     * @return String The Lambda Function output
-     */
+ 
     @Override
-    public String doHandleRequest(Map<String, Object> input, Context context) {
-        // Your function logic here
-        return "Lambda Function output";
+    public APIGatewayProxyResponseEvent handleRequest(APIGatewayProxyRequestEvent apiGatewayProxyRequestEvent, Context context) {
+        return LambdaTracing.instrument(apiGatewayProxyRequestEvent, context, (event, ctx) -> {
+            // Your business logic here
+            return doSomethingWithTheEvent(event);
+        });
     }
 }
 ```

src/main/java/com/newrelic/opentracing/aws/LambdaTracing.java

@@ -0,0 +1,80 @@
+package com.newrelic.opentracing.aws;
+
+import com.amazonaws.services.lambda.runtime.Context;
+import io.opentracing.Scope;
+import io.opentracing.Span;
+import io.opentracing.SpanContext;
+import io.opentracing.Tracer;
+import io.opentracing.util.GlobalTracer;
+import java.util.concurrent.atomic.AtomicBoolean;
+import java.util.function.BiFunction;
+
+/**
+ * Trace calls to lambda functions, for arbitrary Input and Output types.
+ *
+ * <p>For flexibility, applications may extend this class to enhance the root span or handle novel
+ * invocation event types.
+ *
+ * @param <Input> The invocation payload type for your lambda function.
+ * @param <Output> The result type for your lambda function.
+ */
+public class LambdaTracing<Input, Output> {
+  protected static final AtomicBoolean isColdStart = new AtomicBoolean(true);
+
+  /**
+   * One-line instrumentation convenience method.
+   *
+   * @param input The invocation event
+   * @param context The invocation context
+   * @param realHandler The callback that implements the business logic for this event handler
+   * @param <Input> The type of the invocation event
+   * @param <Output> The type of the response
+   * @return The invocation response (the return value of the realHandler callback)
+   */
+  public static <Input, Output> Output instrument(
+      Input input, Context context, BiFunction<Input, Context, Output> realHandler) {
+    return new LambdaTracing<Input, Output>().instrumentRequest(input, context, realHandler);
+  }
+
+  /**
+   * Instrument a Lambda invocation
+   *
+   * @param input The invocation event
+   * @param context The invocation context
+   * @param realHandler The function that implements the business logic. Will be invoked with the
+   *     input and context parameters, from within the instrumentation scope.
+   * @return the return value from realHandler
+   */
+  public Output instrumentRequest(
+      Input input, Context context, BiFunction<Input, Context, Output> realHandler) {
+    final Tracer tracer = GlobalTracer.get();
+    final SpanContext spanContext = extractContext(tracer, input);
+
+    Span span = buildRootSpan(input, context, tracer, spanContext);
+    try (Scope scope = tracer.activateSpan(span)) {
+      try {
+        Output output = realHandler.apply(input, context);
+        parseResponse(span, output);
+        return output;
+      } catch (Throwable throwable) {
+        span.log(SpanUtil.createErrorAttributes(throwable));
+        throw throwable;
+      }
+    } finally {
+      span.finish();
+    }
+  }
+
+  protected SpanContext extractContext(Tracer tracer, Object input) {
+    return HeadersParser.parseAndExtract(tracer, input);
+  }
+
+  protected Span buildRootSpan(
+      Input input, Context context, Tracer tracer, SpanContext spanContext) {
+    return SpanUtil.buildSpan(input, context, tracer, spanContext, isColdStart);
+  }
+
+  protected void parseResponse(Span span, Output output) {
+    ResponseParser.parseResponse(output, span);
+  }
+}

src/main/java/com/newrelic/opentracing/aws/StreamLambdaTracing.java

@@ -0,0 +1,70 @@
+package com.newrelic.opentracing.aws;
+
+import com.amazonaws.services.lambda.runtime.Context;
+import com.amazonaws.services.lambda.runtime.RequestStreamHandler;
+import io.opentracing.Scope;
+import io.opentracing.Span;
+import io.opentracing.SpanContext;
+import io.opentracing.Tracer;
+import io.opentracing.util.GlobalTracer;
+import java.io.IOException;
+import java.io.InputStream;
+import java.io.OutputStream;
+
+/**
+ * Trace calls to lambda functions, implementing manual JSON serialization.
+ *
+ * <p>For flexibility, applications may extend this class to enhance the root span.
+ */
+public class StreamLambdaTracing {
+  /**
+   * One-line instrumentation convenience method.
+   *
+   * @param input The invocation event's input stream
+   * @param output The invocation response output stream
+   * @param context The invocation context
+   * @param realHandler The callback that implements the business logic for this event handler
+   */
+  public static void instrument(
+      InputStream input, OutputStream output, Context context, RequestStreamHandler realHandler)
+      throws IOException {
+    new StreamLambdaTracing().instrumentRequest(input, output, context, realHandler);
+  }
+
+  /**
+   * Instrument a Lambda invocation
+   *
+   * @param input The invocation event's input stream
+   * @param output The invocation response output stream
+   * @param context The invocation context
+   * @param realHandler The function that implements the business logic. Will be invoked with the
+   *     input and context parameters, from within the instrumentation scope.
+   */
+  public void instrumentRequest(
+      InputStream input, OutputStream output, Context context, RequestStreamHandler realHandler)
+      throws IOException {
+    final Tracer tracer = GlobalTracer.get();
+    final SpanContext spanContext = extractContext(tracer, input);
+
+    Span span = buildRootSpan(input, context, tracer, spanContext);
+    try (Scope scope = tracer.activateSpan(span)) {
+      try {
+        realHandler.handleRequest(input, output, context);
+      } catch (Throwable throwable) {
+        span.log(SpanUtil.createErrorAttributes(throwable));
+        throw throwable;
+      }
+    } finally {
+      span.finish();
+    }
+  }
+
+  protected Span buildRootSpan(
+      InputStream input, Context context, Tracer tracer, SpanContext spanContext) {
+    return SpanUtil.buildSpan(input, context, tracer, spanContext, LambdaTracing.isColdStart);
+  }
+
+  protected SpanContext extractContext(Tracer tracer, InputStream input) {
+    return null;
+  }
+}

src/main/java/com/newrelic/opentracing/aws/TracingRequestHandler.java

@@ -6,28 +6,26 @@
 package com.newrelic.opentracing.aws;
 
 import com.amazonaws.services.lambda.runtime.Context;
-import io.opentracing.Scope;
-import io.opentracing.Span;
 import io.opentracing.SpanContext;
 import io.opentracing.Tracer;
 import io.opentracing.propagation.Format;
-import io.opentracing.util.GlobalTracer;
-import java.util.concurrent.atomic.AtomicBoolean;
 
 /**
  * Tracing request handler that creates a span on every invocation of a Lambda.
  *
  * <p>Implement this interface and update your AWS Lambda Handler name to reference your class name,
  * e.g., com.mycompany.HandlerClass
  *
+ * <p>Due to an interaction between Java's type erasure and method inheritance, Input effectively
+ * must be a Map. For that reason, this interface is deprecated in favor of {@link LambdaTracing}.
+ *
  * @param <Input> The input parameter type
  * @param <Output> The output parameter type
  */
+@Deprecated
 public interface TracingRequestHandler<Input, Output>
     extends com.amazonaws.services.lambda.runtime.RequestHandler<Input, Output> {
 
-  AtomicBoolean isColdStart = new AtomicBoolean(true);
-
   /**
    * Method that handles the Lambda function request.
    *
@@ -40,22 +38,7 @@ public interface TracingRequestHandler<Input, Output>
   Output doHandleRequest(Input input, Context context);
 
   default Output handleRequest(Input input, Context context) {
-    final Tracer tracer = GlobalTracer.get();
-    final SpanContext spanContext = extractContext(tracer, input);
-
-    Span span = SpanUtil.buildSpan(input, context, tracer, spanContext, isColdStart);
-    try (Scope scope = tracer.activateSpan(span)) {
-      try {
-        Output output = doHandleRequest(input, context);
-        ResponseParser.parseResponse(output, span);
-        return output;
-      } catch (Throwable throwable) {
-        span.log(SpanUtil.createErrorAttributes(throwable));
-        throw throwable;
-      }
-    } finally {
-      span.finish();
-    }
+    return LambdaTracing.instrument(input, context, this::doHandleRequest);
   }
 
   /**

src/main/java/com/newrelic/opentracing/aws/TracingRequestStreamHandler.java

@@ -6,27 +6,26 @@
 package com.newrelic.opentracing.aws;
 
 import com.amazonaws.services.lambda.runtime.Context;
-import io.opentracing.Scope;
-import io.opentracing.Span;
 import io.opentracing.SpanContext;
 import io.opentracing.Tracer;
 import io.opentracing.propagation.Format;
-import io.opentracing.util.GlobalTracer;
+import java.io.IOException;
 import java.io.InputStream;
 import java.io.OutputStream;
-import java.util.concurrent.atomic.AtomicBoolean;
 
 /**
  * Tracing request stream handler that creates a span on every invocation of a Lambda.
  *
  * <p>Implement this interface and update your AWS Lambda Handler name to reference your class name,
  * e.g., com.mycompany.HandlerClass
+ *
+ * <p>While RequestStreamHandler's handleRequest method may throw an IOException, doHandleRequest
+ * may not. For that reason, this interface is deprecated in favor of {@link StreamLambdaTracing}.
  */
+@Deprecated
 public interface TracingRequestStreamHandler
     extends com.amazonaws.services.lambda.runtime.RequestStreamHandler {
 
-  AtomicBoolean isColdStart = new AtomicBoolean(true);
-
   /**
    * Method that handles the Lambda function request.
    *
@@ -39,19 +38,10 @@ public interface TracingRequestStreamHandler
   void doHandleRequest(InputStream input, OutputStream output, Context context);
 
   default void handleRequest(InputStream input, OutputStream output, Context context) {
-    final Tracer tracer = GlobalTracer.get();
-    final SpanContext spanContext = extractContext(tracer, input);
-
-    Span span = SpanUtil.buildSpan(input, context, tracer, spanContext, isColdStart);
-    try (Scope scope = tracer.activateSpan(span)) {
-      try {
-        doHandleRequest(input, output, context);
-      } catch (Throwable throwable) {
-        span.log(SpanUtil.createErrorAttributes(throwable));
-        throw throwable;
-      }
-    } finally {
-      span.finish();
+    try {
+      StreamLambdaTracing.instrument(input, output, context, this::doHandleRequest);
+    } catch (IOException e) {
+      throw new RuntimeException(e);
     }
   }