[tor-commits] [metrics-lib/master] Add new method to retrieve raw descriptor length.

[karsten at torproject.org]

commit a113feb2c4f195dbc607e3da8c5fc2be19a6d475
Author: Karsten Loesing <karsten.loesing at gmx.net>
Date:   Thu Jun 15 14:25:29 2017 +0200

    Add new method to retrieve raw descriptor length.
    
    When we switched from storing copies of byte[] to storing byte[]
    references, offset, and length, getRawDescriptor() suddenly became
    more expensive than before.  (Before that, copying bytes in the first
    place was always expensive.)  If an application only calls
    Descriptor#getRawDescriptorBytes() to learn the array length, there's
    now a more efficient way to provide that information.
---
 CHANGELOG.md                                              |  3 +++
 src/main/java/org/torproject/descriptor/Descriptor.java   | 15 +++++++++++++++
 .../org/torproject/descriptor/impl/DescriptorImpl.java    |  5 +++++
 3 files changed, 23 insertions(+)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 44f1130..95cd851 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -12,6 +12,9 @@
  * Medium changes
    - Let DescriptorParser return an Iterable instead of a List, which
      prepares parsing large descriptor files descriptor by descriptor.
+   - Add new method to retrieve the raw descriptor length, rather than
+     forcing applications to request (a copy of) raw descriptor bytes
+     only to determine the raw descriptor length.
 
  * Minor changes
    - Fix a bug where NetworkStatusEntry's getMicrodescriptorDigests()
diff --git a/src/main/java/org/torproject/descriptor/Descriptor.java b/src/main/java/org/torproject/descriptor/Descriptor.java
index fb511bf..ca2a4cf 100644
--- a/src/main/java/org/torproject/descriptor/Descriptor.java
+++ b/src/main/java/org/torproject/descriptor/Descriptor.java
@@ -17,11 +17,26 @@ public interface Descriptor {
   /**
    * Return the raw descriptor bytes.
    *
+   * <p>This method creates a new copy of raw descriptor bytes from a
+   * potentially larger byte array containing multiple descriptors.
+   * Applications that only want to learn about raw descriptor length in bytes
+   * should instead use {@link #getRawDescriptorLength()}.</p>
+   *
    * @since 1.0.0
    */
   public byte[] getRawDescriptorBytes();
 
   /**
+   * Return the raw descriptor length in bytes.
+   *
+   * <p>Returns the exact same result as {@code getRawDescriptorBytes().length},
+   * but much more efficiently.</p>
+   *
+   * @since 1.9.0
+   */
+  public int getRawDescriptorLength();
+
+  /**
    * Return the (possibly empty) list of annotations in the format
    * {@code "@key( value)*"}.
    *
diff --git a/src/main/java/org/torproject/descriptor/impl/DescriptorImpl.java b/src/main/java/org/torproject/descriptor/impl/DescriptorImpl.java
index d88b542..e0f94f0 100644
--- a/src/main/java/org/torproject/descriptor/impl/DescriptorImpl.java
+++ b/src/main/java/org/torproject/descriptor/impl/DescriptorImpl.java
@@ -41,6 +41,11 @@ public abstract class DescriptorImpl implements Descriptor {
    */
   protected int length;
 
+  @Override
+  public int getRawDescriptorLength() {
+    return this.length;
+  }
+
   /**
    * Optional reference to the descriptor file, if this descriptor was read from
    * a descriptor file.