Add Java binding for new getStats implementation.

webrtc/sdk/android/api/org/webrtc/RTCStats.java

Index: webrtc/sdk/android/api/org/webrtc/RTCStats.java
diff --git a/webrtc/sdk/android/api/org/webrtc/RTCStats.java b/webrtc/sdk/android/api/org/webrtc/RTCStats.java
new file mode 100644
index 0000000000000000000000000000000000000000..fa25e830d54d13b0fb37ad8ccad7575ba3e23104
--- /dev/null
+++ b/webrtc/sdk/android/api/org/webrtc/RTCStats.java
@@ -0,0 +1,79 @@
+/*
+ *  Copyright 2017 The WebRTC project authors. All Rights Reserved.
+ *
+ *  Use of this source code is governed by a BSD-style license
+ *  that can be found in the LICENSE file in the root of the source
+ *  tree. An additional intellectual property rights grant can be found
+ *  in the file PATENTS.  All contributing project authors may
+ *  be found in the AUTHORS file in the root of the source tree.
+ */
+
+package org.webrtc;
+
+import java.util.Map;
+import java.util.SortedMap;
+
+/** Java version of webrtc::RTCStats. Represents an RTCStats object, as described in
+ *  https://w3c.github.io/webrtc-stats/. The |id|, |timestamp_us| and |type|
+ *  accessors have the same meaning for this class as for the RTCStats
+ *  dictionary. */

[hbos, 2017/04/10 10:19:42]

nit: Here and elsewhere, /** and */ on separate lines unless the entire comment
is a /** single line */.

[Taylor Brandstetter, 2017/04/10 23:59:33]

Done.

+public class RTCStats {
+  private final long timestamp_us;

[hbos, 2017/04/10 10:19:42]

nit: Here, constructor, getter and toString: timestampUs

[Taylor Brandstetter, 2017/04/10 23:59:32]

Done.

+  private final String type;
+  private final String id;
+  private final SortedMap<String, Object> members;
+
+  public RTCStats(long timestamp_us, String type, String id, SortedMap<String, Object> members) {
+    this.timestamp_us = timestamp_us;
+    this.type = type;
+    this.id = id;
+    this.members = members;
+  }
+
+  // Timestamp in nanoseconds.
+  public double timestamp_us() {
+    return timestamp_us;
+  }
+
+  // Equivalent to RTCStatsType in the stats spec.
+  public String type() {
+    return type;
+  }
+
+  // Unique ID representing this stats object. May be referred to by members of
+  // other stats objects.
+  public String id() {
+    return id;
+  }
+
+  /** Returns map of member names to values. Returns as an ordered map so that
+   *  the stats object can be serialized with a consistent ordering.
+   *
+   *  Values will be one of the following objects:
+   *  - Boolean
+   *  - Integer (for 32-bit signed integers)
+   *  - Long (for 32-bit unsigned and 64-bit signed integers)

[hbos, 2017/04/10 10:19:42]

Being able to distinguish between for example uint32_t and int64_t would only be
useful for serialization where we need the types to match between C++ and Java,
such as exporting to the same database between two platforms, in all other cases
you'd only need to know the Java type. Not sure whether to add a type enum or
not?

[Taylor Brandstetter, 2017/04/10 23:59:32]

If we don't have a clear use case, I'd suggest just leaving the type enum out
for the time being.

Also, if it had to, an application *could* figure out the type from the name of
the member ("payload_type" will always be a uint32_t, for example).

+   *  - BigInteger (for 64-bit unsigned integers)
+   *  - Double
+   *  - String
+   *  - The array form of any of the above (e.g., Integer[]) */
+  public SortedMap<String, Object> members() {
+    return members;

[hbos, 2017/04/10 10:19:42]

I thought about returning Collections.unmodifiableSortedMap(members) instead but
arrays are mutable even if the map isn't, so we can't go const either way. But
hey, giving ownership of the stats to the caller makes sense.

One thing to consider: For arrays, do we return primitive arrays or boxed
arrrays? E.g.
- int[]: An array of ints.
- Integer[]: An array of references to Integer objects wrapping ints.

One might think int[] makes more sense, but the upside of boxed arrays is they
can be converted to Object[], primitive arrays can't - there's no "generic" way
to iterate primitive arrays, but you can do so with objects, which is good for
looping through all stats.

I think the slight overhead is worth Object[], let's do it this way. Looks more
consistent too.

[Taylor Brandstetter, 2017/04/10 23:59:32]

I had the same line of thinking about arrays. And I don't have any strong
feelings about returning modifiable/unmodifiable structures.

+  }
+
+  public String toString() {
+    StringBuilder builder = new StringBuilder();
+    builder.append("{ timestamp_us: ")
+        .append(timestamp_us)
+        .append(", type: ")
+        .append(type)
+        .append(", id: ")
+        .append(id);
+    boolean first = true;
+    for (Map.Entry<String, Object> entry : members.entrySet()) {
+      builder.append(", ").append(entry.getKey()).append(": ").append(entry.getValue());

[hbos, 2017/04/10 10:19:42]

An array toString() is not printed as e.g. "[1, 2, 3]" but as e.g.
"[Ljava.lang.Integer;@41975e01". Also we might want \" around strings.

builder.append(", ").append(entry.getKey().append(": ");
if (entry.getValue() instanceof Object[]) {
  Object[] array = (Object[])entry.getValue();
  builder.append('[');
  for (int i = 0; i < array.length; ++i) {
    if (i != 0)
      builder.append(", ");
    if (array[i] instanceof String)
      builder.append('"').append(array[i]).append('"');
    else
      builder.append(array[i]);
  }
  builder.append(']');
} else {
  if (value instanceof String)
    builder.append('"').append(value).append('"');
  else
    builder.append(value);
}

[Taylor Brandstetter, 2017/04/10 23:59:33]

Done, good catch.

+    }
+    builder.append(" }");
+    return builder.toString();
+  }
+}