wip: exposing the create functions and correcting the code example in DelegatingMetricData class comment.

Author: vasantteja

docs/apidiffs/current_vs_latest/opentelemetry-sdk-metrics.txt

@@ -13,3 +13,46 @@ Comparing source compatibility of opentelemetry-sdk-metrics-1.48.0-SNAPSHOT.jar
 	+++  NEW METHOD: PUBLIC(+) java.lang.String getUnit()
 	+++  NEW METHOD: PUBLIC(+) int hashCode()
 	+++  NEW METHOD: PUBLIC(+) java.lang.String toString()
+***  MODIFIED INTERFACE: PUBLIC ABSTRACT io.opentelemetry.sdk.metrics.data.DoubleExemplarData  (not serializable)
+	===  CLASS FILE FORMAT VERSION: 52.0 <- 52.0
+	+++  NEW METHOD: PUBLIC(+) STATIC(+) io.opentelemetry.sdk.metrics.data.DoubleExemplarData create(io.opentelemetry.api.common.Attributes, long, io.opentelemetry.api.trace.SpanContext, double)
+***  MODIFIED INTERFACE: PUBLIC ABSTRACT io.opentelemetry.sdk.metrics.data.DoublePointData  (not serializable)
+	===  CLASS FILE FORMAT VERSION: 52.0 <- 52.0
+	+++  NEW METHOD: PUBLIC(+) STATIC(+) io.opentelemetry.sdk.metrics.data.DoublePointData create(long, long, io.opentelemetry.api.common.Attributes, double)
+***  MODIFIED INTERFACE: PUBLIC ABSTRACT io.opentelemetry.sdk.metrics.data.ExponentialHistogramBuckets  (not serializable)
+	===  CLASS FILE FORMAT VERSION: 52.0 <- 52.0
+	+++  NEW METHOD: PUBLIC(+) STATIC(+) io.opentelemetry.sdk.metrics.data.ExponentialHistogramBuckets create(int, int, java.util.List<java.lang.Long>)
+***  MODIFIED INTERFACE: PUBLIC ABSTRACT io.opentelemetry.sdk.metrics.data.ExponentialHistogramData  (not serializable)
+	===  CLASS FILE FORMAT VERSION: 52.0 <- 52.0
+	+++  NEW METHOD: PUBLIC(+) STATIC(+) io.opentelemetry.sdk.metrics.data.ExponentialHistogramData create(io.opentelemetry.sdk.metrics.data.AggregationTemporality, java.util.Collection<io.opentelemetry.sdk.metrics.data.ExponentialHistogramPointData>)
+***  MODIFIED INTERFACE: PUBLIC ABSTRACT io.opentelemetry.sdk.metrics.data.ExponentialHistogramPointData  (not serializable)
+	===  CLASS FILE FORMAT VERSION: 52.0 <- 52.0
+	+++  NEW METHOD: PUBLIC(+) STATIC(+) io.opentelemetry.sdk.metrics.data.ExponentialHistogramPointData create(int, double, long, boolean, double, boolean, double, io.opentelemetry.sdk.metrics.data.ExponentialHistogramBuckets, io.opentelemetry.sdk.metrics.data.ExponentialHistogramBuckets, long, long, io.opentelemetry.api.common.Attributes, java.util.List<io.opentelemetry.sdk.metrics.data.DoubleExemplarData>)
+***  MODIFIED INTERFACE: PUBLIC ABSTRACT io.opentelemetry.sdk.metrics.data.GaugeData  (not serializable)
+	===  CLASS FILE FORMAT VERSION: 52.0 <- 52.0
+	GENERIC TEMPLATES: === T:io.opentelemetry.sdk.metrics.data.PointData
+	+++  NEW METHOD: PUBLIC(+) STATIC(+) io.opentelemetry.sdk.metrics.internal.data.ImmutableGaugeData<T> create(java.util.Collection<T>)
+		GENERIC TEMPLATES: +++ T:io.opentelemetry.sdk.metrics.data.PointData
+***  MODIFIED INTERFACE: PUBLIC ABSTRACT io.opentelemetry.sdk.metrics.data.HistogramData  (not serializable)
+	===  CLASS FILE FORMAT VERSION: 52.0 <- 52.0
+	+++  NEW METHOD: PUBLIC(+) STATIC(+) io.opentelemetry.sdk.metrics.data.HistogramData create(io.opentelemetry.sdk.metrics.data.AggregationTemporality, java.util.Collection<io.opentelemetry.sdk.metrics.data.HistogramPointData>)
+***  MODIFIED INTERFACE: PUBLIC ABSTRACT io.opentelemetry.sdk.metrics.data.LongExemplarData  (not serializable)
+	===  CLASS FILE FORMAT VERSION: 52.0 <- 52.0
+	+++  NEW METHOD: PUBLIC(+) STATIC(+) io.opentelemetry.sdk.metrics.data.LongExemplarData create(io.opentelemetry.api.common.Attributes, long, io.opentelemetry.api.trace.SpanContext, long)
+***  MODIFIED INTERFACE: PUBLIC ABSTRACT io.opentelemetry.sdk.metrics.data.LongPointData  (not serializable)
+	===  CLASS FILE FORMAT VERSION: 52.0 <- 52.0
+	+++  NEW METHOD: PUBLIC(+) STATIC(+) io.opentelemetry.sdk.metrics.data.LongPointData create(long, long, io.opentelemetry.api.common.Attributes, long)
+***  MODIFIED INTERFACE: PUBLIC ABSTRACT io.opentelemetry.sdk.metrics.data.SumData  (not serializable)
+	===  CLASS FILE FORMAT VERSION: 52.0 <- 52.0
+	GENERIC TEMPLATES: === T:io.opentelemetry.sdk.metrics.data.PointData
+	+++  NEW METHOD: PUBLIC(+) STATIC(+) io.opentelemetry.sdk.metrics.internal.data.ImmutableSumData<T> create(boolean, io.opentelemetry.sdk.metrics.data.AggregationTemporality, java.util.Collection<T>)
+		GENERIC TEMPLATES: +++ T:io.opentelemetry.sdk.metrics.data.PointData
+***  MODIFIED INTERFACE: PUBLIC ABSTRACT io.opentelemetry.sdk.metrics.data.SummaryData  (not serializable)
+	===  CLASS FILE FORMAT VERSION: 52.0 <- 52.0
+	+++  NEW METHOD: PUBLIC(+) STATIC(+) io.opentelemetry.sdk.metrics.data.SummaryData create(java.util.Collection<io.opentelemetry.sdk.metrics.data.SummaryPointData>)
+***  MODIFIED INTERFACE: PUBLIC ABSTRACT io.opentelemetry.sdk.metrics.data.SummaryPointData  (not serializable)
+	===  CLASS FILE FORMAT VERSION: 52.0 <- 52.0
+	+++  NEW METHOD: PUBLIC(+) STATIC(+) io.opentelemetry.sdk.metrics.internal.data.ImmutableSummaryPointData create(long, long, io.opentelemetry.api.common.Attributes, long, double, java.util.List<io.opentelemetry.sdk.metrics.data.ValueAtQuantile>)
+***  MODIFIED INTERFACE: PUBLIC ABSTRACT io.opentelemetry.sdk.metrics.data.ValueAtQuantile  (not serializable)
+	===  CLASS FILE FORMAT VERSION: 52.0 <- 52.0
+	+++  NEW METHOD: PUBLIC(+) STATIC(+) io.opentelemetry.sdk.metrics.data.ValueAtQuantile create(double, double)

sdk/metrics/src/main/java/io/opentelemetry/sdk/metrics/data/DelegatingMetricData.java

@@ -17,20 +17,18 @@
  * custom implementation.
  *
  * <pre>{@code
- * // class MetricDataWithCustomAttributes extends DelegatingMetricData {
+ * // class MetricDataWithCustomDescription extends DelegatingMetricData {
  * //
- * //   private final Attributes attributes;
+ * //   private final String description;
  * //
- * //   MetricDataWithCustomAttributes(MetricData delegate) {
+ * //   MetricDataWithCustomDescription(MetricData delegate) {
  * //     super(delegate);
- * //     Attributes.Builder newAttributes = Attributes.builder(delegate.getAttributes());
- * //     newAttributes.put("custom_key", "custom_value");
- * //     attributes = newAttributes.build();
+ * //     this.description = delegate.getDescription() + " (custom)";
  * //   }
  * //
  * //   @Override
- * //   public Attributes getAttributes() {
- * //     return attributes;
+ * //   public String getDescription() {
+ * //     return description;
  * //   }
  * // }
  * }</pre>

sdk/metrics/src/main/java/io/opentelemetry/sdk/metrics/data/DoubleExemplarData.java

@@ -5,6 +5,9 @@
 
 package io.opentelemetry.sdk.metrics.data;
 
+import io.opentelemetry.api.common.Attributes;
+import io.opentelemetry.api.trace.SpanContext;
+import io.opentelemetry.sdk.metrics.internal.data.ImmutableDoubleExemplarData;
 import javax.annotation.concurrent.Immutable;
 
 /**
@@ -14,6 +17,22 @@
  */
 @Immutable
 public interface DoubleExemplarData extends ExemplarData {
+
+  /**
+   * Construct a new exemplar.
+   *
+   * @param filteredAttributes The set of {@link Attributes} not already associated with the {@link
+   *     PointData}.
+   * @param recordTimeNanos The time when the sample qas recorded in nanoseconds.
+   * @param spanContext The associated span context.
+   * @param value The value recorded.
+   */
+  static DoubleExemplarData create(
+      Attributes filteredAttributes, long recordTimeNanos, SpanContext spanContext, double value) {
+    return ImmutableDoubleExemplarData.create(
+        filteredAttributes, recordTimeNanos, spanContext, value);
+  }
+
   /** Numerical value of the measurement that was recorded. */
   double getValue();
 }

sdk/metrics/src/main/java/io/opentelemetry/sdk/metrics/data/DoublePointData.java

@@ -5,6 +5,9 @@
 
 package io.opentelemetry.sdk.metrics.data;
 
+import io.opentelemetry.api.common.Attributes;
+import io.opentelemetry.sdk.metrics.internal.data.ImmutableDoublePointData;
+import java.util.Collections;
 import java.util.List;
 
 /**
@@ -13,6 +16,23 @@
  * @since 1.14.0
  */
 public interface DoublePointData extends PointData {
+
+  /**
+   * Creates a {@link DoublePointData}.
+   *
+   * @param startEpochNanos The starting time for the period where this point was sampled. Note:
+   *     While start time is optional in OTLP, all SDKs should produce it for all their metrics, so
+   *     it is required here.
+   * @param epochNanos The ending time for the period when this value was sampled.
+   * @param attributes The set of attributes associated with this point.
+   * @param value The value that was sampled.
+   */
+  static DoublePointData create(
+      long startEpochNanos, long epochNanos, Attributes attributes, double value) {
+    return ImmutableDoublePointData.create(
+        startEpochNanos, epochNanos, attributes, value, Collections.emptyList());
+  }
+
   /** Returns the value of the data point. */
   double getValue();
 

sdk/metrics/src/main/java/io/opentelemetry/sdk/metrics/data/ExponentialHistogramBuckets.java

@@ -5,6 +5,7 @@
 
 package io.opentelemetry.sdk.metrics.data;
 
+import io.opentelemetry.sdk.metrics.internal.data.ImmutableExponentialHistogramBuckets;
 import java.util.List;
 import javax.annotation.concurrent.Immutable;
 
@@ -25,6 +26,16 @@
 @Immutable
 public interface ExponentialHistogramBuckets {
 
+  /**
+   * Create a ExponentialHistogramBuckets.
+   *
+   * @return a ExponentialHistogramBuckets.
+   */
+  @SuppressWarnings("TooManyParameters")
+  static ExponentialHistogramBuckets create(int scale, int offset, List<Long> bucketCounts) {
+    return ImmutableExponentialHistogramBuckets.create(scale, offset, bucketCounts);
+  }
+
   /** The scale of the buckets. Must align with {@link ExponentialHistogramPointData#getScale()}. */
   int getScale();
 

sdk/metrics/src/main/java/io/opentelemetry/sdk/metrics/data/ExponentialHistogramData.java

@@ -5,6 +5,7 @@
 
 package io.opentelemetry.sdk.metrics.data;
 
+import io.opentelemetry.sdk.metrics.internal.data.ImmutableExponentialHistogramData;
 import java.util.Collection;
 import javax.annotation.concurrent.Immutable;
 
@@ -15,15 +16,21 @@
  * <p><i>Note: This is called "ExponentialHistogramData" to reflect which primitives are used to
  * record it, however "ExponentialHistogram" is the equivalent OTLP type.</i>
  *
- * @see <a
- *     href="https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/data-model.md#exponentialhistogram">Exponential
+ * @see <a href=
+ *     "https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/data-model.md#exponentialhistogram">Exponential
  *     Histogram Data Model</a>
  * @see ExponentialHistogramPointData
  * @since 1.23.0
  */
 @Immutable
 public interface ExponentialHistogramData extends Data<ExponentialHistogramPointData> {
 
+  /** Returns a new {@link ExponentialHistogramData}. */
+  static ExponentialHistogramData create(
+      AggregationTemporality temporality, Collection<ExponentialHistogramPointData> points) {
+    return ImmutableExponentialHistogramData.create(temporality, points);
+  }
+
   /**
    * Returns the {@code AggregationTemporality} of this metric.
    *

sdk/metrics/src/main/java/io/opentelemetry/sdk/metrics/data/ExponentialHistogramPointData.java

@@ -5,6 +5,8 @@
 
 package io.opentelemetry.sdk.metrics.data;
 
+import io.opentelemetry.api.common.Attributes;
+import io.opentelemetry.sdk.metrics.internal.data.ImmutableExponentialHistogramPointData;
 import java.util.List;
 import javax.annotation.concurrent.Immutable;
 
@@ -24,6 +26,43 @@
 @Immutable
 public interface ExponentialHistogramPointData extends PointData {
 
+  /**
+   * Create a DoubleExponentialHistogramPointData.
+   *
+   * @return a DoubleExponentialHistogramPointData.
+   */
+  @SuppressWarnings("TooManyParameters")
+  static ExponentialHistogramPointData create(
+      int scale,
+      double sum,
+      long zeroCount,
+      boolean hasMin,
+      double min,
+      boolean hasMax,
+      double max,
+      ExponentialHistogramBuckets positiveBuckets,
+      ExponentialHistogramBuckets negativeBuckets,
+      long startEpochNanos,
+      long epochNanos,
+      Attributes attributes,
+      List<DoubleExemplarData> exemplars) {
+
+    return ImmutableExponentialHistogramPointData.create(
+        scale,
+        sum,
+        zeroCount,
+        hasMin,
+        min,
+        hasMax,
+        max,
+        positiveBuckets,
+        negativeBuckets,
+        startEpochNanos,
+        epochNanos,
+        attributes,
+        exemplars);
+  }
+
   /**
    * Scale characterises the resolution of the histogram, with larger values of scale offering
    * greater precision. Bucket boundaries of the histogram are located at integer powers of the

sdk/metrics/src/main/java/io/opentelemetry/sdk/metrics/data/GaugeData.java

@@ -5,6 +5,8 @@
 
 package io.opentelemetry.sdk.metrics.data;
 
+import io.opentelemetry.sdk.metrics.internal.data.ImmutableGaugeData;
+import java.util.Collection;
 import javax.annotation.concurrent.Immutable;
 
 /**
@@ -13,4 +15,16 @@
  * @since 1.14.0
  */
 @Immutable
-public interface GaugeData<T extends PointData> extends Data<T> {}
+public interface GaugeData<T extends PointData> extends Data<T> {
+
+  /**
+   * Creates an instance of {@link ImmutableGaugeData} with the given collection of points.
+   *
+   * @param <T> the type of the point data
+   * @param points the collection of points to be included in the gauge data
+   * @return an instance of {@link ImmutableGaugeData} containing the provided points
+   */
+  static <T extends PointData> ImmutableGaugeData<T> create(Collection<T> points) {
+    return ImmutableGaugeData.create(points);
+  }
+}

sdk/metrics/src/main/java/io/opentelemetry/sdk/metrics/data/HistogramData.java

@@ -5,6 +5,7 @@
 
 package io.opentelemetry.sdk.metrics.data;
 
+import io.opentelemetry.sdk.metrics.internal.data.ImmutableHistogramData;
 import java.util.Collection;
 import javax.annotation.concurrent.Immutable;
 
@@ -15,6 +16,19 @@
  */
 @Immutable
 public interface HistogramData extends Data<HistogramPointData> {
+
+  /**
+   * Creates a new instance of {@link HistogramData}.
+   *
+   * @param temporality the aggregation temporality of the histogram data
+   * @param points the collection of histogram point data
+   * @return a new instance of {@link HistogramData}
+   */
+  static HistogramData create(
+      AggregationTemporality temporality, Collection<HistogramPointData> points) {
+    return ImmutableHistogramData.create(temporality, points);
+  }
+
   /** Returns the histogram {@link AggregationTemporality}. */
   AggregationTemporality getAggregationTemporality();
 

sdk/metrics/src/main/java/io/opentelemetry/sdk/metrics/data/HistogramPointData.java

@@ -5,16 +5,54 @@
 
 package io.opentelemetry.sdk.metrics.data;
 
+import java.util.Collections;
 import java.util.List;
 import javax.annotation.concurrent.Immutable;
 
+import io.opentelemetry.api.common.Attributes;
+import io.opentelemetry.sdk.metrics.internal.data.ImmutableHistogramPointData;
+
 /**
  * Point data for {@link HistogramData}.
  *
  * @since 1.14.0
  */
 @Immutable
 public interface HistogramPointData extends PointData {
+
+  /**
+   * Creates a HistogramPointData. For a Histogram with N defined boundaries, there should be N+1
+   * counts.
+   *
+   * @return a HistogramPointData.
+   * @throws IllegalArgumentException if the given boundaries/counts were invalid
+   */
+  @SuppressWarnings("TooManyParameters")
+  static HistogramPointData create(
+      long startEpochNanos,
+      long epochNanos,
+      Attributes attributes,
+      double sum,
+      boolean hasMin,
+      double min,
+      boolean hasMax,
+      double max,
+      List<Double> boundaries,
+      List<Long> counts) {
+    return ImmutableHistogramPointData.create(
+        startEpochNanos,
+        epochNanos,
+        attributes,
+        sum,
+        hasMin,
+        min,
+        hasMax,
+        max,
+        boundaries,
+        counts,
+        Collections.emptyList());
+  }
+
   /**
    * The sum of all measurements recorded.
    *