Add default impls of SPI classes

core/metrics-spi/pom.xml

@@ -0,0 +1,81 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <parent>
+        <artifactId>core</artifactId>
+        <groupId>software.amazon.awssdk</groupId>
+        <version>2.13.23-SNAPSHOT</version>
+    </parent>
+    <modelVersion>4.0.0</modelVersion>
+
+    <artifactId>metrics-spi</artifactId>
+    <name>AWS Java SDK :: Metrics SPI</name>
+    <description> This is the base module for SDK metrics feature. It contains the interfaces used for metrics feature
+        that are used by other modules in the library.
+    </description>
+
+    <dependencies>
+        <dependency>
+            <groupId>software.amazon.awssdk</groupId>
+            <artifactId>annotations</artifactId>
+            <version>${awsjavasdk.version}</version>
+        </dependency>
+        <dependency>
+            <groupId>software.amazon.awssdk</groupId>
+            <artifactId>utils</artifactId>
+            <version>${awsjavasdk.version}</version>
+        </dependency>
+        <dependency>
+            <groupId>software.amazon.awssdk</groupId>
+            <artifactId>test-utils</artifactId>
+            <version>${awsjavasdk.version}</version>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>junit</groupId>
+            <artifactId>junit</artifactId>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>com.github.tomakehurst</groupId>
+            <artifactId>wiremock</artifactId>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>org.assertj</groupId>
+            <artifactId>assertj-core</artifactId>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>org.mockito</groupId>
+            <artifactId>mockito-core</artifactId>
+            <scope>test</scope>
+        </dependency>
+    </dependencies>
+
+
+    <build>
+        <plugins>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-jar-plugin</artifactId>
+                <configuration>
+                    <archive>
+                        <manifestEntries>
+                            <Automatic-Module-Name>software.amazon.awssdk.metrics</Automatic-Module-Name>
+                        </manifestEntries>
+                    </archive>
+                </configuration>
+            </plugin>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-compiler-plugin</artifactId>
+                <configuration>
+                    <source>1.8</source>
+                    <target>1.8</target>
+                </configuration>
+            </plugin>
+        </plugins>
+    </build>
+</project>

core/metrics-spi/src/main/java/software/amazon/awssdk/metrics/MetricCategory.java

@@ -0,0 +1,82 @@
+/*
+ * Copyright 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.awssdk.metrics;
+
+import software.amazon.awssdk.annotations.SdkPublicApi;
+
+/**
+ * A enum class representing the different types of metric categories in the SDK.
+ * <p>
+ * A metric can be tagged with multiple categories. Clients can enable/disable metric collection
+ * at a {@link MetricCategory} level.
+ */
+@SdkPublicApi
+public enum MetricCategory {
+
+    /**
+     * All metrics defined by the SDK are classified under this category at a minimum. If the metrics feature is enabled
+     * but the category to collect is not, only metrics that are classified under this category are collected by the SDK
+     */
+    DEFAULT("Default"),
+
+    /**
+     * Metrics collected at the http client level are classified under this category.
+     */
+    HTTP_CLIENT("HttpClient"),
+
+    /**
+     * Metrics specific to streaming, eventStream APIs are classified under this category.
+     */
+    STREAMING("Streaming"),
+
+    /**
+     * This is an umbrella category (provided for convenience) that records metrics belonging to every category
+     * defined in this enum. Clients who wish to collect lot of SDK metrics data should use this.
+     * <p>
+     * Note: Enabling this option is verbose and can be expensive based on the platform the metrics are uploaded to.
+     * Please make sure you need all this data before using this category.
+     */
+    ALL("All")
+
+    ;
+
+    private final String value;
+
+    MetricCategory(String value) {
+        this.value = value;
+    }
+
+    public String getValue() {
+        return value;
+    }
+
+    /**
+     * Create a {@link MetricCategory} from the given String value. This method is case insensitive.
+     *
+     * @param value the value to create the {@link MetricCategory} from
+     * @return A {@link MetricCategory} if the given {@link #value} matches one of the enum values.
+     *         Otherwise throws {@link IllegalArgumentException}
+     */
+    public static MetricCategory fromString(String value) {
+        for (MetricCategory mc : MetricCategory.values()) {
+            if (mc.value.equalsIgnoreCase(value)) {
+                return mc;
+            }
+        }
+
+        throw new IllegalArgumentException("MetricCategory cannot be created from value: " + value);
+    }
+}

core/metrics-spi/src/main/java/software/amazon/awssdk/metrics/MetricCollection.java

@@ -0,0 +1,45 @@
+/*
+ * Copyright 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.awssdk.metrics;
+
+import java.util.Collection;
+import java.util.List;
+import software.amazon.awssdk.annotations.SdkPublicApi;
+
+/**
+ * An immutable collection of metrics.
+ */
+@SdkPublicApi
+public interface MetricCollection extends Iterable<MetricRecord<?>> {
+    /**
+     * @return The name of this metric collection.
+     */
+    String name();
+
+    /**
+     * Return all the values of the given metric.
+     *
+     * @param metric The metric.
+     * @param <T> The type of the value.
+     * @return All of the values of this metric.
+     */
+    <T> List<T> metricValues(SdkMetric<T> metric);
+
+    /**
+     * @return The child metric collections.
+     */
+    Collection<MetricCollection> children();
+}

core/metrics-spi/src/main/java/software/amazon/awssdk/metrics/MetricCollector.java

@@ -0,0 +1,57 @@
+/*
+ * Copyright 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.awssdk.metrics;
+
+import software.amazon.awssdk.annotations.NotThreadSafe;
+import software.amazon.awssdk.annotations.SdkPublicApi;
+import software.amazon.awssdk.metrics.internal.DefaultMetricCollector;
+
+/**
+ * Used to collect metrics reported by the SDK.
+ */
+@NotThreadSafe
+@SdkPublicApi
+public interface MetricCollector {
+    /**
+     * @return The name of this collector.
+     */
+    String name();
+
+    /**
+     * Report a metric.
+     */
+    <T> void reportMetric(SdkMetric<T> metric, T data);
+
+    /**
+     * Create a child of this metric collector.
+     *
+     * @param name The name of the child collector.
+     * @return The child collector.
+     */
+    MetricCollector createChild(String name);
+
+    /**
+     * Return the collected metrics.
+     * <p>
+     * Calling {@code collect()} prevents further invocations of {@link #reportMetric(SdkMetric, Object)}.
+     * @return The collected metrics.
+     */
+    MetricCollection collect();
+
+    static MetricCollector create(String name) {
+        return DefaultMetricCollector.create(name);
+    }
+}

core/metrics-spi/src/main/java/software/amazon/awssdk/metrics/MetricPublisher.java

@@ -0,0 +1,68 @@
+/*
+ * Copyright 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.awssdk.metrics;
+
+import software.amazon.awssdk.annotations.SdkPublicApi;
+import software.amazon.awssdk.annotations.ThreadSafe;
+import software.amazon.awssdk.metrics.MetricCollection;
+import software.amazon.awssdk.utils.SdkAutoCloseable;
+
+/**
+ * Interface to report and publish the collected SDK metric events to external
+ * sources.
+ * <p>
+ * Conceptually, a publisher receives a stream of {@link MetricCollection} objects
+ * overs its lifetime through its {@link #publish(MetricCollection)} )} method.
+ * Implementations are then free further aggregate these events into sets of
+ * metrics that are then published to some external system for further use.
+ * As long as a publisher is not closed, then it can receive {@code
+ * MetricCollection} objects at any time. In addition, as the SDK makes use of
+ * multithreading, it's possible that the publisher is shared concurrently by
+ * multiple threads, and necessitates that all implementations are threadsafe.
+ * <p>
+ * The SDK may invoke methods on the interface from multiple threads
+ * concurrently so implementations must be threadsafe.
+ */
+@ThreadSafe
+@SdkPublicApi
+public interface MetricPublisher extends SdkAutoCloseable {
+    /**
+     * Notify the publisher of new metric data. After this call returns, the
+     * caller can safely discard the given {@code metricCollection} instance if it
+     * no longer needs it. Implementations are strongly encouraged to complete
+     * any further aggregation and publishing of metrics in an asynchronous manner to
+     * avoid blocking the calling thread.
+     * <p>
+     * With the exception of a {@code null} {@code metricCollection}, all
+     * invocations of this method must return normally. This
+     * is to ensure that callers of the publisher can safely assume that even
+     * in situations where an error happens during publishing that it will not
+     * interrupt the calling thread.
+     *
+     * @param metricCollection The collection of metrics.
+     * @throws IllegalArgumentException If {@code metricCollection} is {@code null}.
+     */
+    void publish(MetricCollection metricCollection);
+
+    /**
+     * {@inheritDoc}
+     * <p>
+     * <b>Important:</b> Implementations must block the calling thread until all
+     * pending metrics are published and any resources acquired have been freed.
+     */
+    @Override
+    void close();
+}

core/metrics-spi/src/main/java/software/amazon/awssdk/metrics/MetricRecord.java

@@ -0,0 +1,34 @@
+/*
+ * Copyright 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.awssdk.metrics;
+
+import software.amazon.awssdk.annotations.SdkPublicApi;
+
+/**
+ * A container associating a metric and its value.
+ */
+@SdkPublicApi
+public interface MetricRecord<T> {
+    /**
+     * @return The metric.
+     */
+    SdkMetric<T> metric();
+
+    /**
+     * @return The value of this metric.
+     */
+    T value();
+}