chore: introduce ByteRangeSpec#endOffsetInclusive (#1832)

There are some cases where endOffset and endOffsetInclusive are both necessary and externally being able to differentiate is needed.

### Test Refactor

As part of this change, I've update the declaration of ByteRangeSpec.RangeScenario to be more verbose and easier to read, as well as have a more direct description for the test name.

This does add a fair number of lines of code, but I think it brings some clarity compared to a method with 4 different long arguments. It also reduces (and possible errors in declaration) between related scenarios.

In general the new pattern is: define the four properties of any range (beginOffset, endOffset, endOffsetInclusive, length) then specify those ByteRangeSpecs for which it should be applicable.

Author: BenWhitehead

google-cloud-storage/src/main/java/com/google/cloud/storage/ByteRangeSpec.java

@@ -50,6 +50,8 @@ private ByteRangeSpec() {}
 
   abstract long endOffset() throws ArithmeticException;
 
+  abstract long endOffsetInclusive() throws ArithmeticException;
+
   abstract long length() throws ArithmeticException;
 
   // TODO: add validation to this if it ever becomes public
@@ -97,9 +99,7 @@ public boolean equals(Object o) {
 
   @Override
   public String toString() {
-    return append(MoreObjects.toStringHelper(""))
-        .add("httpRangeHeader", getHttpRangeHeader())
-        .toString();
+    return append(MoreObjects.toStringHelper("ByteRangeSpec")).toString();
   }
 
   protected abstract MoreObjects.ToStringHelper append(MoreObjects.ToStringHelper tsh);
@@ -162,6 +162,11 @@ long beginOffset() {
 
     @Override
     long endOffset() throws ArithmeticException {
+      return Math.addExact(beginOffset, length);
+    }
+
+    @Override
+    long endOffsetInclusive() throws ArithmeticException {
       return Math.addExact(beginOffset, length) - 1;
     }
 
@@ -209,7 +214,7 @@ ByteRangeSpec withNewRelativeLength(long relativeLength) {
 
     @Override
     protected String fmtAsHttpRangeHeader() throws ArithmeticException {
-      return String.format("bytes=%d-%d", beginOffset, endOffset());
+      return String.format("bytes=%d-%d", beginOffset, endOffsetInclusive());
     }
 
     @Override
@@ -239,9 +244,14 @@ long endOffset() throws ArithmeticException {
       return endOffsetExclusive;
     }
 
+    @Override
+    long endOffsetInclusive() throws ArithmeticException {
+      return Math.subtractExact(endOffsetExclusive, 1);
+    }
+
     @Override
     long length() throws ArithmeticException {
-      return endOffsetExclusive - beginOffset;
+      return Math.subtractExact(endOffsetExclusive, beginOffset);
     }
 
     @Override
@@ -284,7 +294,7 @@ ByteRangeSpec withNewRelativeLength(long relativeLength) {
 
     @Override
     protected String fmtAsHttpRangeHeader() throws ArithmeticException {
-      return String.format("bytes=%d-%d", beginOffset, endOffsetExclusive - 1);
+      return String.format("bytes=%d-%d", beginOffset, endOffsetInclusive());
     }
 
     @Override
@@ -311,12 +321,17 @@ long beginOffset() {
 
     @Override
     long endOffset() throws ArithmeticException {
+      return Math.addExact(endOffsetInclusive, 1L);
+    }
+
+    @Override
+    long endOffsetInclusive() throws ArithmeticException {
       return endOffsetInclusive;
     }
 
     @Override
     long length() throws ArithmeticException {
-      return endOffsetInclusive - beginOffset;
+      return Math.addExact(Math.subtractExact(endOffsetInclusive, beginOffset), 1);
     }
 
     @Override
@@ -346,7 +361,7 @@ ByteRangeSpec withNewEndOffset(long endOffsetExclusive) {
     @Override
     ByteRangeSpec withNewEndOffsetClosed(long endOffsetInclusive) {
       if (endOffsetInclusive != this.endOffsetInclusive) {
-        return new LeftClosedRightOpenByteRangeSpec(beginOffset, endOffsetInclusive);
+        return new LeftClosedRightClosedByteRangeSpec(beginOffset, endOffsetInclusive);
       } else {
         return this;
       }
@@ -387,6 +402,11 @@ long endOffset() throws ArithmeticException {
       return EFFECTIVE_INFINITY;
     }
 
+    @Override
+    long endOffsetInclusive() throws ArithmeticException {
+      return EFFECTIVE_INFINITY;
+    }
+
     @Override
     long length() throws ArithmeticException {
       return EFFECTIVE_INFINITY;
@@ -455,6 +475,11 @@ long endOffset() throws ArithmeticException {
       return EFFECTIVE_INFINITY;
     }
 
+    @Override
+    long endOffsetInclusive() throws ArithmeticException {
+      return EFFECTIVE_INFINITY;
+    }
+
     @Override
     long length() throws ArithmeticException {
       return EFFECTIVE_INFINITY;