This is an automated email from the ASF dual-hosted git repository. leerho pushed a commit to branch Cleanup_phase2 in repository https://gitbox.apache.org/repos/asf/datasketches-java.git
commit 3e4eae07719491550c7195f2efe0f884225169c9 Author: Lee Rhodes <[email protected]> AuthorDate: Fri Aug 15 15:27:10 2025 -0700 Correcting javadocs --- .../quantiles/DirectCompactDoublesSketch.java | 2 +- .../quantiles/DirectUpdateDoublesSketch.java | 2 +- .../datasketches/quantiles/DoublesSketch.java | 48 ++++++++++++++++++---- .../datasketches/quantiles/DoublesUnionImpl.java | 2 +- .../quantiles/UpdateDoublesSketch.java | 30 +++++++++++--- 5 files changed, 66 insertions(+), 18 deletions(-) diff --git a/src/main/java/org/apache/datasketches/quantiles/DirectCompactDoublesSketch.java b/src/main/java/org/apache/datasketches/quantiles/DirectCompactDoublesSketch.java index 63a81e047..af0579eef 100644 --- a/src/main/java/org/apache/datasketches/quantiles/DirectCompactDoublesSketch.java +++ b/src/main/java/org/apache/datasketches/quantiles/DirectCompactDoublesSketch.java @@ -250,7 +250,7 @@ final class DirectCompactDoublesSketch extends CompactDoublesSketch { /** * Checks a sketch's serial version and flags to see if the sketch can be wrapped as a * DirectCompactDoubleSketch. Throws an exception if the sketch is neither empty nor compact - * and ordered, unles the sketch uses serialization version 2. + * and ordered, unless the sketch uses serialization version 2. * @param serVer the serialization version * @param flags Flags from the sketch to evaluate */ diff --git a/src/main/java/org/apache/datasketches/quantiles/DirectUpdateDoublesSketch.java b/src/main/java/org/apache/datasketches/quantiles/DirectUpdateDoublesSketch.java index 1025aeb86..4976039d5 100644 --- a/src/main/java/org/apache/datasketches/quantiles/DirectUpdateDoublesSketch.java +++ b/src/main/java/org/apache/datasketches/quantiles/DirectUpdateDoublesSketch.java @@ -384,7 +384,7 @@ final class DirectUpdateDoublesSketch extends UpdateDoublesSketch { static void checkCompact(final int serVer, final int flags) { final boolean compact = (serVer == 2) || ((flags & COMPACT_FLAG_MASK) > 0); if (compact) { - throw new SketchesArgumentException("Compact MemorySegment is not supported for Wrap Instance."); + throw new SketchesArgumentException("MemorySegment is in compact form and is not supported for this writableWrap Instance."); } } diff --git a/src/main/java/org/apache/datasketches/quantiles/DoublesSketch.java b/src/main/java/org/apache/datasketches/quantiles/DoublesSketch.java index b8b0b7633..f39b6b69a 100644 --- a/src/main/java/org/apache/datasketches/quantiles/DoublesSketch.java +++ b/src/main/java/org/apache/datasketches/quantiles/DoublesSketch.java @@ -151,29 +151,59 @@ public abstract class DoublesSketch implements QuantilesDoublesAPI, MemorySegmen } /** - * Wrap this sketch around the given updatable MemorySegment image of a DoublesSketch, compact or updatable. + * Wrap this sketch around the given MemorySegment image of a compact, read-only DoublesSketch. * - * @param srcSeg the given MemorySegment image of a DoublesSketch that may have data - * @return a sketch that wraps the given srcSeg in read-only mode. + * @param srcSeg the given MemorySegment image of a compact, read-only DoublesSketch. + * @return a compact, read-only sketch that wraps the given MemorySegment. */ public static DoublesSketch wrap(final MemorySegment srcSeg) { + if (!checkIsMemorySegmentCompact(srcSeg)) { + throw new SketchesArgumentException("MemorySegment sketch image must be in compact form."); + } + return DirectCompactDoublesSketch.wrapInstance(srcSeg); + } + + /** + * Wrap this sketch around the given MemorySegment image of an updatable DoublesSketch. + * + * <p>The given MemorySegment must be writable and it must contain a <i>UpdateDoublesSketch</i>. + * The sketch will be updated and managed totally within the MemorySegment. If the given source + * MemorySegment is created off-heap, then all the management of the sketch's internal data will be off-heap as well.</p> + * + * <p><b>NOTE:</b>If during updating of the sketch the sketch requires more capacity than the given size of the MemorySegment, the sketch + * will request more capacity using the {@link MemorySegmentRequest MemorySegmentRequest} interface. The default of this interface will + * return a new MemorySegment on the heap.</p> + * + * @param srcSeg the given MemorySegment image of an <i>UpdateDoublesSketch</i>. + * @return an updatable sketch that wraps the given MemorySegment. + */ + public static DoublesSketch writableWrap(final MemorySegment srcSeg) { if (checkIsMemorySegmentCompact(srcSeg)) { - return DirectCompactDoublesSketch.wrapInstance(srcSeg); + throw new SketchesArgumentException("MemorySegment sketch image must be in updatable form."); } return DirectUpdateDoublesSketch.wrapInstance(srcSeg, null); } /** - * Wrap this sketch around the given updatable MemorySegment image of a DoublesSketch, compact or updatable. + * Wrap this sketch around the given MemorySegment image of an updatable DoublesSketch. + * + * <p>The given MemorySegment must be writable and it must contain a <i>UpdateDoublesSketch</i>. + * The sketch will be updated and managed totally within the MemorySegment. If the given source + * MemorySegment is created off-heap, then all the management of the sketch's internal data will be off-heap as well.</p> + * + * <p><b>NOTE:</b>If during updating of the sketch the sketch requires more capacity than the given size of the MemorySegment, the sketch + * will request more capacity using the {@link MemorySegmentRequest MemorySegmentRequest} interface. The default of this interface will + * return a new MemorySegment on the heap. It is up to the user to optionally extend this interface if more flexible + * handling of requests for more capacity is required.</p> * - * @param srcSeg the given MemorySegment image of a DoublesSketch that may have data. + * @param srcSeg the given MemorySegment image of a DoublesSketch. * @param mSegReq the MemorySegmentRequest used if the given MemorySegment needs to expand. * Otherwise, it can be null and the default MemorySegmentRequest will be used. - * @return a sketch that wraps the given srcSeg in read-only mode. + * @return a sketch that wraps the given MemorySegment. */ - public static DoublesSketch wrap(final MemorySegment srcSeg, final MemorySegmentRequest mSegReq) { + public static DoublesSketch writableWrap(final MemorySegment srcSeg, final MemorySegmentRequest mSegReq) { if (checkIsMemorySegmentCompact(srcSeg)) { - return DirectCompactDoublesSketch.wrapInstance(srcSeg); + throw new SketchesArgumentException("MemorySegment sketch image must be in updatable form."); } return DirectUpdateDoublesSketch.wrapInstance(srcSeg, mSegReq); } diff --git a/src/main/java/org/apache/datasketches/quantiles/DoublesUnionImpl.java b/src/main/java/org/apache/datasketches/quantiles/DoublesUnionImpl.java index 59c1021ea..2f2c55bbf 100644 --- a/src/main/java/org/apache/datasketches/quantiles/DoublesUnionImpl.java +++ b/src/main/java/org/apache/datasketches/quantiles/DoublesUnionImpl.java @@ -138,7 +138,7 @@ final class DoublesUnionImpl extends DoublesUnion { @Override public void union(final MemorySegment seg) { Objects.requireNonNull(seg); - gadget_ = updateLogic(maxK_, gadget_, DoublesSketch.wrap(seg, null)); + gadget_ = updateLogic(maxK_, gadget_, DoublesSketch.writableWrap(seg, null)); gadget_.doublesSV = null; } diff --git a/src/main/java/org/apache/datasketches/quantiles/UpdateDoublesSketch.java b/src/main/java/org/apache/datasketches/quantiles/UpdateDoublesSketch.java index cf3c8ac60..d511d8fa7 100644 --- a/src/main/java/org/apache/datasketches/quantiles/UpdateDoublesSketch.java +++ b/src/main/java/org/apache/datasketches/quantiles/UpdateDoublesSketch.java @@ -34,22 +34,40 @@ public abstract class UpdateDoublesSketch extends DoublesSketch { } /** - * Wrap this sketch around the given MemorySegment image of an UpdateDoublesSketch. + * Wrap a sketch around the given source MemorySegment containing sketch data that originated from this sketch. * - * @param srcSeg the given MemorySegment image of an UpdateDoublesSketch and must not be null. - * @return a sketch that wraps the given srcSeg + * <p>The given MemorySegment must be writable and it must contain a <i>UpdateDoublesSketch</i>. + * The sketch will be updated and managed totally within the MemorySegment. If the given source + * MemorySegment is created off-heap, then all the management of the sketch's internal data will be off-heap as well.</p> + * + * <p><b>NOTE:</b>If during updating of the sketch the sketch requires more capacity than the given size of the MemorySegment, the sketch + * will request more capacity using the {@link MemorySegmentRequest MemorySegmentRequest} interface. The default of this interface will + * return a new MemorySegment on the heap.</p> + * + * @param srcSeg a MemorySegment that contains sketch data. + * @return an instance of this sketch that wraps the given MemorySegment. */ public static UpdateDoublesSketch wrap(final MemorySegment srcSeg) { return DirectUpdateDoublesSketch.wrapInstance(srcSeg, null); } /** - * Wrap this sketch around the given MemorySegment image of an UpdateDoublesSketch. + * Wrap a sketch around the given source MemorySegment containing sketch data that originated from this sketch and including an + * optional, user defined {@link MemorySegmentRequest MemorySegmentRequest}. + * + * <p>The given MemorySegment must be writable and it must contain a <i>UpdateDoublesSketch</i>. + * The sketch will be updated and managed totally within the MemorySegment. If the given source + * MemorySegment is created off-heap, then all the management of the sketch's internal data will be off-heap as well.</p> + * + * <p><b>NOTE:</b>If during updating of the sketch the sketch requires more capacity than the given size of the MemorySegment, the sketch + * will request more capacity using the {@link MemorySegmentRequest MemorySegmentRequest} interface. The default of this interface will + * return a new MemorySegment on the heap. It is up to the user to optionally extend this interface if more flexible + * handling of requests for more capacity is required.</p> * - * @param srcSeg the given MemorySegment image of an UpdateDoublesSketch and must not be null. + * @param srcSeg a MemorySegment that contains sketch data. * @param mSegReq the MemorySegmentRequest used if the given MemorySegment needs to expand. * Otherwise, it can be null and the default MemorySegmentRequest will be used. - * @return a sketch that wraps the given srcSeg + * @return an instance of this sketch that wraps the given MemorySegment. */ public static UpdateDoublesSketch wrap(final MemorySegment srcSeg, final MemorySegmentRequest mSegReq) { return DirectUpdateDoublesSketch.wrapInstance(srcSeg, mSegReq); --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
