You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@datasketches.apache.org by le...@apache.org on 2019/08/29 18:33:33 UTC
[incubator-datasketches-java] branch master updated: Add additional
info in Javadocs
This is an automated email from the ASF dual-hosted git repository.
leerho pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/incubator-datasketches-java.git
The following commit(s) were added to refs/heads/master by this push:
new 787b916 Add additional info in Javadocs
787b916 is described below
commit 787b916e59b9340f2d52d747ad20478d8276b2e9
Author: Lee Rhodes <le...@users.noreply.github.com>
AuthorDate: Thu Aug 29 11:33:24 2019 -0700
Add additional info in Javadocs
---
.../org/apache/datasketches/hll/BaseHllSketch.java | 43 ++++++++++++++++++----
.../java/org/apache/datasketches/hll/HllUtil.java | 5 ++-
.../org/apache/datasketches/hll/HllArrayTest.java | 5 +--
.../org/apache/datasketches/hll/HllSketchTest.java | 24 ++++++++++--
4 files changed, 62 insertions(+), 15 deletions(-)
diff --git a/src/main/java/org/apache/datasketches/hll/BaseHllSketch.java b/src/main/java/org/apache/datasketches/hll/BaseHllSketch.java
index 7039eae..760b97e 100644
--- a/src/main/java/org/apache/datasketches/hll/BaseHllSketch.java
+++ b/src/main/java/org/apache/datasketches/hll/BaseHllSketch.java
@@ -201,17 +201,46 @@ abstract class BaseHllSketch {
public abstract void reset();
/**
- * Returns the serialization of this sketch as a byte array in compact form, which can be
- * converted back to on on-heap sketch (<i>heapified</i>) where it can be used for read or
- * write operations.
- * or directly <i>wrapped</i> designed
- * to be heapified only. It is not directly updatable.
- * @return the serialization of this sketch as a byte array.
+ * Serializes this sketch as a byte array in compact form. The compact form is smaller in size
+ * than the updatable form and read-only. It can be used in union operations as follows:
+ * <pre>
+ * Union union; HllSketch sk, sk2;
+ * int lgK = 12;
+ * sk = new HllSketch(lgK, TgtHllType.HLL_4); //can be 4, 6, or 8
+ * for (int i = 0; i < (2 << lgK); i++) { sk.update(i); }
+ * byte[] arr = HllSketch.toCompactByteArray();
+ * //...
+ * union = Union.heapify(arr); //initializes the union using data from the array.
+ * //OR, if used in an off-heap environment:
+ * union = Union.heapify(Memory.wrap(arr)); //same as above, except from Memory object.
+ *
+ * //To recover an updatable heap sketch:
+ * sk2 = HllSketch.heapify(arr);
+ * //OR, if used in an off-heap environment:
+ * sk2 = HllSketch.heapify(Memory.wrap(arr));
+ * </pre>
+ *
+ * <p>The sketch "wrapping" operation skips actual deserialization thus is quite fast. However,
+ * any attempt to update the derived HllSketch will result in a Read-only exception.
+ * @return this sketch as a compact byte array.
*/
public abstract byte[] toCompactByteArray();
/**
- * Serializes this sketch as an updatable byte array.
+ * Serializes this sketch as a byte array in an updatable form. The updatable form is larger than
+ * the compact form. The use of this form is primarily in environments that support updating
+ * sketches in off-heap memory. If the sketch is constructed using HLL_8, sketch updating and
+ * union updating operations can actually occur in WritableMemory, which can be off-heap:
+ * <pre>
+ * Union union; HllSketch sk;
+ * int lgK = 12;
+ * sk = new HllSketch(lgK, TgtHllType.HLL_8) //must be 8
+ * for (int i = 0; i < (2 << lgK); i++) { sk.update(i); }
+ * byte[] arr = sk.toUpdatableByteArray();
+ * WritableMemory wmem = WritableMemory.wrap(arr);
+ * //...
+ * union = Union.writableWrap(wmem); //no deserialization!
+ * </pre>
* @return this sketch as an updatable byte array.
*/
public abstract byte[] toUpdatableByteArray();
diff --git a/src/main/java/org/apache/datasketches/hll/HllUtil.java b/src/main/java/org/apache/datasketches/hll/HllUtil.java
index 6489d59..d4bbaea 100644
--- a/src/main/java/org/apache/datasketches/hll/HllUtil.java
+++ b/src/main/java/org/apache/datasketches/hll/HllUtil.java
@@ -31,6 +31,7 @@ import static org.apache.datasketches.hll.PreambleUtil.extractSerVer;
import org.apache.datasketches.Family;
import org.apache.datasketches.SketchesArgumentException;
+import org.apache.datasketches.SketchesReadOnlyException;
import org.apache.datasketches.memory.Memory;
/**
@@ -112,8 +113,8 @@ final class HllUtil {
//Exceptions
static final void noWriteAccess() {
- throw new SketchesArgumentException(
- "This sketch does not have write access to the underlying resource.");
+ throw new SketchesReadOnlyException(
+ "This sketch is compact or does not have write access to the underlying resource.");
}
static final void badPreambleState(final Memory mem) {
diff --git a/src/test/java/org/apache/datasketches/hll/HllArrayTest.java b/src/test/java/org/apache/datasketches/hll/HllArrayTest.java
index cfcd86e..dfa756f 100644
--- a/src/test/java/org/apache/datasketches/hll/HllArrayTest.java
+++ b/src/test/java/org/apache/datasketches/hll/HllArrayTest.java
@@ -23,9 +23,8 @@ import static org.testng.Assert.assertEquals;
import static org.testng.Assert.assertFalse;
import static org.testng.Assert.assertTrue;
-import org.testng.annotations.Test;
-
import org.apache.datasketches.memory.WritableMemory;
+import org.testng.annotations.Test;
/**
* @author Lee Rhodes
@@ -139,7 +138,7 @@ public class HllArrayTest {
* @param s value to print
*/
static void println(String s) {
- //System.out.println(s); //disable here
+ System.out.println(s); //disable here
}
}
diff --git a/src/test/java/org/apache/datasketches/hll/HllSketchTest.java b/src/test/java/org/apache/datasketches/hll/HllSketchTest.java
index 7c926b7..f2d84c0 100644
--- a/src/test/java/org/apache/datasketches/hll/HllSketchTest.java
+++ b/src/test/java/org/apache/datasketches/hll/HllSketchTest.java
@@ -35,11 +35,10 @@ import static org.testng.Assert.assertNull;
import static org.testng.Assert.assertTrue;
import static org.testng.Assert.fail;
-import org.testng.annotations.Test;
-
+import org.apache.datasketches.SketchesArgumentException;
import org.apache.datasketches.memory.Memory;
import org.apache.datasketches.memory.WritableMemory;
-import org.apache.datasketches.SketchesArgumentException;
+import org.testng.annotations.Test;
/**
* @author Lee Rhodes
@@ -418,6 +417,25 @@ public class HllSketchTest {
HllSketch sk2 = HllSketch.writableWrap(wmem);
}
+ @SuppressWarnings("unused")
+ @Test
+ public void checkJavadocExample() {
+ Union union; HllSketch sk, sk2;
+ int lgK = 12;
+ sk = new HllSketch(lgK, TgtHllType.HLL_4); //can be 4, 6, or 8
+ for (int i = 0; i < (2 << lgK); i++) { sk.update(i); }
+ byte[] arr = sk.toCompactByteArray();
+ // ...
+ union = Union.heapify(arr); //initializes the union using data from the array.
+ //OR, if used in an off-heap environment:
+ union = Union.heapify(Memory.wrap(arr));
+
+ //To recover an updatable Heap sketch:
+ sk2 = HllSketch.heapify(arr);
+ //OR, if used in an off-heap environment:
+ sk2 = HllSketch.heapify(Memory.wrap(arr));
+ }
+
@Test
public void printlnTest() {
println("PRINTING: "+this.getClass().getName());
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@datasketches.apache.org
For additional commands, e-mail: commits-help@datasketches.apache.org