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 2021/08/17 17:57:19 UTC
[datasketches-memory] 01/01: Fix Javadocs, no code changes.
This is an automated email from the ASF dual-hosted git repository.
leerho pushed a commit to branch Fix_javadocs
in repository https://gitbox.apache.org/repos/asf/datasketches-memory.git
commit f6b8ba1ffa58d2eadda72eba80f9e4ea88796270
Author: Lee Rhodes <le...@users.noreply.github.com>
AuthorDate: Tue Aug 17 10:56:55 2021 -0700
Fix Javadocs, no code changes.
---
.../memory/test/DruidIssue11544Test.java | 1 +
.../memory/test/MemoryCloseExceptionTest.java | 1 +
.../datasketches/memory/test/ReflectUtil.java | 1 +
.../datasketches/memory/test/UnsafeUtilTest.java | 1 +
.../org/apache/datasketches/memory/BaseBuffer.java | 12 +++----
.../org/apache/datasketches/memory/BaseState.java | 5 ++-
.../org/apache/datasketches/memory/Buffer.java | 6 ++++
.../org/apache/datasketches/memory/Memory.java | 19 +++++++----
.../datasketches/memory/MemoryCloseException.java | 8 +++++
.../datasketches/memory/MemoryRequestServer.java | 2 +-
.../datasketches/memory/Utf8CodingException.java | 37 ++++++++++++++++++++--
.../apache/datasketches/memory/WritableBuffer.java | 6 ++++
.../apache/datasketches/memory/WritableMemory.java | 6 +++-
.../org/apache/datasketches/memory/XxHash.java | 2 +-
.../memory/internal/BaseStateImpl.java | 6 +++-
.../memory/internal/BaseWritableBufferImpl.java | 8 +++++
.../memory/internal/BaseWritableMemoryImpl.java | 35 +++++++++++++++++++-
.../apache/datasketches/memory/internal/Ints.java | 5 +++
.../memory/internal/NativeWritableBufferImpl.java | 3 +-
.../memory/internal/NativeWritableMemoryImpl.java | 3 +-
.../internal/NonNativeWritableBufferImpl.java | 3 +-
.../internal/NonNativeWritableMemoryImpl.java | 3 +-
.../apache/datasketches/memory/internal/Prim.java | 1 +
.../datasketches/memory/internal/StepBoolean.java | 6 +++-
.../datasketches/memory/internal/UnsafeUtil.java | 2 +-
.../apache/datasketches/memory/internal/Util.java | 1 +
.../src/main/java/module-info.java | 2 +-
27 files changed, 152 insertions(+), 33 deletions(-)
diff --git a/datasketches-memory-java8-tests/src/test/java/org/apache/datasketches/memory/test/DruidIssue11544Test.java b/datasketches-memory-java8-tests/src/test/java/org/apache/datasketches/memory/test/DruidIssue11544Test.java
index 92e5057..042203e 100644
--- a/datasketches-memory-java8-tests/src/test/java/org/apache/datasketches/memory/test/DruidIssue11544Test.java
+++ b/datasketches-memory-java8-tests/src/test/java/org/apache/datasketches/memory/test/DruidIssue11544Test.java
@@ -48,6 +48,7 @@ import org.testng.annotations.Test;
* @author Lee Rhodes
*
*/
+@SuppressWarnings("javadoc")
public class DruidIssue11544Test {
@Test
diff --git a/datasketches-memory-java8-tests/src/test/java/org/apache/datasketches/memory/test/MemoryCloseExceptionTest.java b/datasketches-memory-java8-tests/src/test/java/org/apache/datasketches/memory/test/MemoryCloseExceptionTest.java
index 5dafda0..3bf6c5e 100644
--- a/datasketches-memory-java8-tests/src/test/java/org/apache/datasketches/memory/test/MemoryCloseExceptionTest.java
+++ b/datasketches-memory-java8-tests/src/test/java/org/apache/datasketches/memory/test/MemoryCloseExceptionTest.java
@@ -22,6 +22,7 @@ package org.apache.datasketches.memory.test;
import org.apache.datasketches.memory.MemoryCloseException;
import org.testng.annotations.Test;
+@SuppressWarnings("javadoc")
public class MemoryCloseExceptionTest {
@Test
diff --git a/datasketches-memory-java8-tests/src/test/java/org/apache/datasketches/memory/test/ReflectUtil.java b/datasketches-memory-java8-tests/src/test/java/org/apache/datasketches/memory/test/ReflectUtil.java
index 8892454..3d27dda 100644
--- a/datasketches-memory-java8-tests/src/test/java/org/apache/datasketches/memory/test/ReflectUtil.java
+++ b/datasketches-memory-java8-tests/src/test/java/org/apache/datasketches/memory/test/ReflectUtil.java
@@ -28,6 +28,7 @@ import java.nio.ByteOrder;
import org.apache.datasketches.memory.MemoryRequestServer;
+@SuppressWarnings("javadoc")
public final class ReflectUtil {
private ReflectUtil() {}
diff --git a/datasketches-memory-java8-tests/src/test/java/org/apache/datasketches/memory/test/UnsafeUtilTest.java b/datasketches-memory-java8-tests/src/test/java/org/apache/datasketches/memory/test/UnsafeUtilTest.java
index 8cace37..53c6f77 100644
--- a/datasketches-memory-java8-tests/src/test/java/org/apache/datasketches/memory/test/UnsafeUtilTest.java
+++ b/datasketches-memory-java8-tests/src/test/java/org/apache/datasketches/memory/test/UnsafeUtilTest.java
@@ -34,6 +34,7 @@ import org.testng.annotations.Test;
/**
* @author Lee Rhodes
*/
+@SuppressWarnings("javadoc")
public class UnsafeUtilTest {
long testField = 1; //Do not remove & cannot be static. Used in reflection check.
diff --git a/datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/BaseBuffer.java b/datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/BaseBuffer.java
index fd14737..3e1869e 100644
--- a/datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/BaseBuffer.java
+++ b/datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/BaseBuffer.java
@@ -19,6 +19,11 @@
package org.apache.datasketches.memory;
+/**
+ * Defines the relative positional API.
+ *
+ * @author Lee Rhodes
+ */
public interface BaseBuffer extends BaseState {
/**
@@ -116,11 +121,4 @@ public interface BaseBuffer extends BaseState {
*/
BaseBuffer setAndCheckStartPositionEnd(long start, long position, long end);
-
-
-
-
-
-
-
}
diff --git a/datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/BaseState.java b/datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/BaseState.java
index f7384ae..2f0cd96 100644
--- a/datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/BaseState.java
+++ b/datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/BaseState.java
@@ -32,7 +32,10 @@ import org.apache.datasketches.memory.internal.BaseStateImpl;
* @author Lee Rhodes
*/
public interface BaseState {
- static final MemoryRequestServer defaultMemReqSvr = null;//new DefaultMemoryRequestServer(); //or null.
+ /**
+ * The placeholder for the default MemoryRequestServer, if set at all.
+ */
+ static final MemoryRequestServer defaultMemReqSvr = null; //new DefaultMemoryRequestServer();
//Byte Order Related
diff --git a/datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/Buffer.java b/datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/Buffer.java
index 2bbf4fe..fe4a9c8 100644
--- a/datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/Buffer.java
+++ b/datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/Buffer.java
@@ -27,6 +27,11 @@ import java.util.Objects;
import org.apache.datasketches.memory.internal.BaseWritableBufferImpl;
+/**
+ * Defines the read-only API for relative positional access to a resource.
+ *
+ * @author Lee Rhodes
+ */
public interface Buffer extends BaseBuffer {
//BYTE BUFFER
@@ -144,6 +149,7 @@ public interface Buffer extends BaseBuffer {
/**
* Convert this Buffer to a Memory with the given byte order.
* The current <i>start</i>, <i>position</i> and <i>end</i> are ignored.
+ * @param byteOrder the given byte order.
* @return Memory
*/
Memory asMemory(ByteOrder byteOrder);
diff --git a/datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/Memory.java b/datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/Memory.java
index 7699e36..71ac7a5 100644
--- a/datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/Memory.java
+++ b/datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/Memory.java
@@ -33,6 +33,11 @@ import org.apache.datasketches.memory.internal.BaseWritableMemoryImpl;
import org.apache.datasketches.memory.internal.Prim;
import org.apache.datasketches.memory.internal.UnsafeUtil;
+/**
+ * Defines the read-only API for offset access to a resource.
+ *
+ * @author Lee Rhodes
+ */
public interface Memory extends BaseState {
//BYTE BUFFER
@@ -40,7 +45,7 @@ public interface Memory extends BaseState {
/**
* Accesses the given <i>ByteBuffer</i> for read-only operations. The returned <i>Memory</i> object has
* the same byte order, as the given <i>ByteBuffer</i>.
- * @param byteBuffer the given <i>ByteBuffer</i>. It must be non-null and with capacity >= 0.
+ * @param byteBuffer the given <i>ByteBuffer</i>. It must be non-null and with capacity ≥ 0.
* @return a new <i>Memory</i> for read-only operations on the given <i>ByteBuffer</i>.
*/
static Memory wrap(ByteBuffer byteBuffer) {
@@ -50,7 +55,7 @@ public interface Memory extends BaseState {
/**
* Accesses the given <i>ByteBuffer</i> for read-only operations. The returned <i>Memory</i> object has
* the given byte order, ignoring the byte order of the given <i>ByteBuffer</i> for future reads and writes.
- * @param byteBuffer the given <i>ByteBuffer</i>. It must be non-null and with capacity >= 0.
+ * @param byteBuffer the given <i>ByteBuffer</i>. It must be non-null and with capacity ≥ 0.
* @param byteOrder the byte order to be used. It must be non-null.
* @return a new <i>Memory</i> for read-only operations on the given <i>ByteBuffer</i>.
*/
@@ -66,7 +71,7 @@ public interface Memory extends BaseState {
* Maps the entire given file into native-ordered <i>Memory</i> for read operations
* Calling this method is equivalent to calling
* {@link #map(File, long, long, ByteOrder) map(file, 0, file.length(), ByteOrder.nativeOrder())}.
- * @param file the given file to map. It must be non-null, length >= 0, and readable.
+ * @param file the given file to map. It must be non-null, length ≥ 0, and readable.
* @return <i>MapHandle</i> for managing the mapped memory.
* Please read Javadocs for {@link Handle}.
*/
@@ -99,8 +104,8 @@ public interface Memory extends BaseState {
* <li>Returned object's origin = this object's origin + offsetBytes</li>
* <li>Returned object's capacity = capacityBytes</li>
* </ul>
- * @param offsetBytes the starting offset with respect to the origin of this <i>Memory</i>. It must be >=0.
- * @param capacityBytes the capacity of the region in bytes. It must be >= 0.
+ * @param offsetBytes the starting offset with respect to the origin of this <i>Memory</i>. It must be ≥ 0.
+ * @param capacityBytes the capacity of the region in bytes. It must be ≥ 0.
* @return a new <i>Memory</i> representing the defined region based on the given
* offsetBytes and capacityBytes.
*/
@@ -115,8 +120,8 @@ public interface Memory extends BaseState {
* <li>Returned object's capacity = <i>capacityBytes</i></li>
* <li>Returned object's byte order = <i>byteOrder</i></li>
* </ul>
- * @param offsetBytes the starting offset with respect to the origin of this Memory. It must be >=0.
- * @param capacityBytes the capacity of the region in bytes. It must be >= 0.
+ * @param offsetBytes the starting offset with respect to the origin of this Memory. It must be ≥ 0.
+ * @param capacityBytes the capacity of the region in bytes. It must be ≥ 0.
* @param byteOrder the given byte order. It must be non-null.
* @return a new <i>Memory</i> representing the defined region based on the given
* offsetBytes, capacityBytes and byteOrder.
diff --git a/datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/MemoryCloseException.java b/datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/MemoryCloseException.java
index 072067f..782c6cd 100644
--- a/datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/MemoryCloseException.java
+++ b/datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/MemoryCloseException.java
@@ -28,10 +28,18 @@ package org.apache.datasketches.memory;
public class MemoryCloseException extends MemoryException {
private static final long serialVersionUID = 2L;
+ /**
+ * The associated resource failed to close.
+ */
public MemoryCloseException() {
super("The associated resource failed to close.");
}
+ /**
+ * The associated resource failed to close, with comment
+ *
+ * @param resource the named resource that failed to close, plus other comments.
+ */
public MemoryCloseException(final String resource) {
super("The associated resource, " + resource + ", failed to close");
}
diff --git a/datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/MemoryRequestServer.java b/datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/MemoryRequestServer.java
index 9db2701..e2ca235 100644
--- a/datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/MemoryRequestServer.java
+++ b/datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/MemoryRequestServer.java
@@ -31,7 +31,7 @@ public interface MemoryRequestServer {
* Request new WritableMemory with the given capacity. The current Writable Memory will be used to
* determine the byte order of the returned WritableMemory and other checks.
* @param currentWritableMemory the current writableMemory of the client. It must be non-null.
- * @param capacityBytes The capacity being requested. It must be >0.
+ * @param capacityBytes The capacity being requested. It must be ≥ 0.
*
* @return new WritableMemory with the given capacity.
*/
diff --git a/datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/Utf8CodingException.java b/datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/Utf8CodingException.java
index 30102e1..895a146 100644
--- a/datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/Utf8CodingException.java
+++ b/datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/Utf8CodingException.java
@@ -37,7 +37,15 @@ public final class Utf8CodingException extends RuntimeException {
super(message);
}
- //Decode
+ //DECODE
+ /**
+ * Exception for a short UTF_8 Decode Byte Sequence
+ * @param leadByte the given lead byte
+ * @param address the given address
+ * @param limit the given limit
+ * @param required what is required
+ * @return the exception
+ */
public static Utf8CodingException shortUtf8DecodeByteSequence(final byte leadByte, final long address,
final long limit, final int required) {
final String s = "Too few Utf8 decode bytes remaining given the leading byte. "
@@ -45,28 +53,53 @@ public final class Utf8CodingException extends RuntimeException {
return new Utf8CodingException(s);
}
+ /**
+ * Exception for an illegal UTF_8 Decode Byte Sequence
+ * @param bytes the illegal byte sequence
+ * @return the exception.
+ */
public static Utf8CodingException illegalUtf8DecodeByteSequence(final byte[] bytes) {
final String s = "Invalid UTF-8 decode byte sequence: " + badBytes(bytes);
return new Utf8CodingException(s);
}
- //Encode
+ //ENCODE
+ /**
+ * Exception for out-of-memory
+ * @return the exception
+ */
public static Utf8CodingException outOfMemory() {
final String s = "Out-of-memory with characters remaining to be encoded";
return new Utf8CodingException(s);
}
+ /**
+ * Exception for an unpaired surrogate
+ * @param c The last char to encode is an unpaired surrogate
+ * @return the exception plus the unpaired surrogate character
+ */
public static Utf8CodingException unpairedSurrogate(final char c) {
final String s = "Last char to encode is an unpaired surrogate: 0X"
+ Integer.toHexString(c & 0XFFFF);
return new Utf8CodingException(s);
}
+ /**
+ * Exception for a short UTF_8 encode byte length
+ * @param remaining The surrogate pair that is short
+ * @return the exception plus the surrogate pair that is short
+ */
public static Utf8CodingException shortUtf8EncodeByteLength(final int remaining) {
final String s = "Too few MemoryImpl bytes to encode a surrogate pair: " + remaining;
return new Utf8CodingException(s);
}
+ /**
+ * Exception for an illegal surrogate pair
+ * @param c1 the first character of the pair
+ * @param c2 the second character of the pair
+ * @return the exception plus the illegal pair
+ */
public static Utf8CodingException illegalSurrogatePair(final char c1, final char c2) {
final String s = "Illegal Surrogate Pair: Char 1: " + Integer.toHexString(c1 & 0XFFFF)
+ ", Char 2: " + Integer.toHexString(c2 & 0XFFFF);
diff --git a/datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/WritableBuffer.java b/datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/WritableBuffer.java
index aa17216..921d36a 100644
--- a/datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/WritableBuffer.java
+++ b/datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/WritableBuffer.java
@@ -27,6 +27,11 @@ import java.util.Objects;
import org.apache.datasketches.memory.internal.BaseWritableBufferImpl;
import org.apache.datasketches.memory.internal.Util;
+/**
+ * Defines the writable API for relative positional access to a resource
+ *
+ * @author Lee Rhodes
+ */
public interface WritableBuffer extends Buffer {
//BYTE BUFFER
@@ -154,6 +159,7 @@ public interface WritableBuffer extends Buffer {
* Convert this WritableBuffer to a WritableMemory with the given byte order.
* If this object's capacity is zero, the returned object is effectively immutable and
* the backing storage and byte order are unspecified.
+ * @param byteOrder the byte order to be used.
* @return WritableMemory
*/
WritableMemory asWritableMemory(ByteOrder byteOrder);
diff --git a/datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/WritableMemory.java b/datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/WritableMemory.java
index 027c7d3..b519d49 100644
--- a/datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/WritableMemory.java
+++ b/datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/WritableMemory.java
@@ -17,7 +17,6 @@
* under the License.
*/
-
package org.apache.datasketches.memory;
import static org.apache.datasketches.memory.internal.Util.negativeCheck;
@@ -31,6 +30,11 @@ import org.apache.datasketches.memory.internal.BaseWritableMemoryImpl;
import org.apache.datasketches.memory.internal.Prim;
import org.apache.datasketches.memory.internal.UnsafeUtil;
+/**
+ * Defines the writable API for offset access to a resource.
+ *
+ * @author Lee Rhodes
+ */
public interface WritableMemory extends Memory {
//BYTE BUFFER
diff --git a/datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/XxHash.java b/datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/XxHash.java
index de20bd5..d9ec5db 100644
--- a/datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/XxHash.java
+++ b/datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/XxHash.java
@@ -49,7 +49,7 @@ import static org.apache.datasketches.memory.internal.XxHash64.hashShorts;
*/
public final class XxHash {
- public XxHash() { /* singleton */ }
+ private XxHash() { /* singleton */ }
/**
* Hash the given arr starting at the given offset and continuing for the given length using the
diff --git a/datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/internal/BaseStateImpl.java b/datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/internal/BaseStateImpl.java
index 70d8c15..1b92232 100644
--- a/datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/internal/BaseStateImpl.java
+++ b/datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/internal/BaseStateImpl.java
@@ -340,7 +340,11 @@ public abstract class BaseStateImpl implements BaseState {
//TO STRING
- //For debugging
+ /**
+ * Decodes the resource type. This is primarily for debugging.
+ * @param typeId the given typeId
+ * @return a human readable string.
+ */
public static final String typeDecode(final int typeId) {
StringBuilder sb = new StringBuilder();
int group1 = typeId & 0x7;
diff --git a/datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/internal/BaseWritableBufferImpl.java b/datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/internal/BaseWritableBufferImpl.java
index f71af03..832561f 100644
--- a/datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/internal/BaseWritableBufferImpl.java
+++ b/datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/internal/BaseWritableBufferImpl.java
@@ -67,6 +67,14 @@ public abstract class BaseWritableBufferImpl extends BaseBufferImpl implements W
super(unsafeObj, nativeBaseOffset, regionOffset, capacityBytes);
}
+ /**
+ * The static constructor that chooses the correct ByteBuffer leaf node based on the byte order.
+ * @param byteBuf the ByteBuffer being wrapped
+ * @param localReadOnly the requested read-only state
+ * @param byteOrder the requested byteOrder
+ * @param memReqSvr the requested MemoryRequestServer, which may be null.
+ * @return this class constructed via the leaf node.
+ */
public static BaseWritableBufferImpl wrapByteBuffer(
final ByteBuffer byteBuf, final boolean localReadOnly, final ByteOrder byteOrder,
final MemoryRequestServer memReqSvr) {
diff --git a/datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/internal/BaseWritableMemoryImpl.java b/datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/internal/BaseWritableMemoryImpl.java
index 097a405..ad397b0 100644
--- a/datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/internal/BaseWritableMemoryImpl.java
+++ b/datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/internal/BaseWritableMemoryImpl.java
@@ -80,15 +80,32 @@ public abstract class BaseWritableMemoryImpl extends BaseStateImpl implements Wr
super(unsafeObj, nativeBaseOffset, regionOffset, capacityBytes);
}
+ /**
+ * The static constructor that chooses the correct Heap leaf node based on the byte order.
+ * @param arr the primitive heap array being wrapped
+ * @param offsetBytes the offset bytes into the array (independent of array type).
+ * @param lengthBytes the length of the wrapped region.
+ * @param localReadOnly the requested read-only status
+ * @param byteOrder the requested byte order
+ * @param memReqSvr the requested MemoryRequestServer, which may be null.
+ * @return this class constructed via the leaf node.
+ */
public static BaseWritableMemoryImpl wrapHeapArray(final Object arr, final long offsetBytes, final long lengthBytes,
final boolean localReadOnly, final ByteOrder byteOrder, final MemoryRequestServer memReqSvr) {
-
final int typeId = localReadOnly ? READONLY : 0;
return Util.isNativeByteOrder(byteOrder)
? new HeapWritableMemoryImpl(arr, offsetBytes, lengthBytes, typeId, memReqSvr)
: new HeapNonNativeWritableMemoryImpl(arr, offsetBytes, lengthBytes, typeId, memReqSvr);
}
+ /**
+ * The static constructor that chooses the correct ByteBuffer leaf node based on the byte order.
+ * @param byteBuf the ByteBuffer being wrapped
+ * @param localReadOnly the requested read-only state
+ * @param byteOrder the requested byteOrder
+ * @param memReqSvr the requested MemoryRequestServer, which may be null.
+ * @return this class constructed via the leaf node.
+ */
public static BaseWritableMemoryImpl wrapByteBuffer(
final ByteBuffer byteBuf, final boolean localReadOnly, final ByteOrder byteOrder,
final MemoryRequestServer memReqSvr) {
@@ -101,6 +118,15 @@ public abstract class BaseWritableMemoryImpl extends BaseStateImpl implements Wr
abb.regionOffset, abb.capacityBytes, typeId, byteBuf, memReqSvr);
}
+ /**
+ * The static constructor that chooses the correct Map leaf node based on the byte order.
+ * @param file the file being wrapped.
+ * @param fileOffsetBytes the file offset bytes
+ * @param capacityBytes the requested capacity of the memory mapped region
+ * @param localReadOnly the requested read-only state
+ * @param byteOrder the requested byte-order
+ * @return this class constructed via the leaf node.
+ */
@SuppressWarnings("resource")
public static WritableMapHandle wrapMap(final File file, final long fileOffsetBytes,
final long capacityBytes, final boolean localReadOnly, final ByteOrder byteOrder) {
@@ -115,6 +141,13 @@ public abstract class BaseWritableMemoryImpl extends BaseStateImpl implements Wr
return new WritableMapHandleImpl(dirWMap, wmem);
}
+ /**
+ * The static constructor that chooses the correct Direct leaf node based on the byte order.
+ * @param capacityBytes the requested capacity for the Direct (off-heap) memory
+ * @param byteOrder the requested byte order
+ * @param memReqSvr the requested MemoryRequestServer, which may be null
+ * @return this class constructed via the leaf node.
+ */
@SuppressWarnings("resource")
public static WritableHandle wrapDirect(final long capacityBytes,
final ByteOrder byteOrder, final MemoryRequestServer memReqSvr) {
diff --git a/datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/internal/Ints.java b/datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/internal/Ints.java
index 4d17365..72a447d 100644
--- a/datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/internal/Ints.java
+++ b/datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/internal/Ints.java
@@ -24,6 +24,11 @@ public final class Ints {
private Ints() {}
+ /**
+ * Checks if a cast of a long to an int is within the range of an int
+ * @param v the given long
+ * @return returns the cast int, or throws an exception that the long was out-of-range of an int.
+ */
public static int checkedCast(final long v) {
final int result = (int) v;
if (result != v) {
diff --git a/datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/internal/NativeWritableBufferImpl.java b/datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/internal/NativeWritableBufferImpl.java
index e9bdd31..2dd1ce2 100644
--- a/datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/internal/NativeWritableBufferImpl.java
+++ b/datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/internal/NativeWritableBufferImpl.java
@@ -52,8 +52,7 @@ import org.apache.datasketches.memory.WritableBuffer;
*/
/**
- * Implementation of {@link WritableBuffer} for native endian byte order. Non-native variant is
- * {@link NonNativeWritableBufferImpl}.
+ * Implementation of {@link WritableBuffer} for native endian byte order.
* @author Roman Leventov
* @author Lee Rhodes
*/
diff --git a/datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/internal/NativeWritableMemoryImpl.java b/datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/internal/NativeWritableMemoryImpl.java
index 3530f98..c16423e 100644
--- a/datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/internal/NativeWritableMemoryImpl.java
+++ b/datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/internal/NativeWritableMemoryImpl.java
@@ -52,8 +52,7 @@ import org.apache.datasketches.memory.WritableMemory;
*/
/**
- * Implementation of {@link WritableMemory} for native endian byte order. Non-native variant is
- * {@link NonNativeWritableMemoryImpl}.
+ * Implementation of {@link WritableMemory} for native endian byte order.
* @author Roman Leventov
* @author Lee Rhodes
*/
diff --git a/datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/internal/NonNativeWritableBufferImpl.java b/datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/internal/NonNativeWritableBufferImpl.java
index 25e37aa..a8203ba 100644
--- a/datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/internal/NonNativeWritableBufferImpl.java
+++ b/datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/internal/NonNativeWritableBufferImpl.java
@@ -45,8 +45,7 @@ import org.apache.datasketches.memory.WritableBuffer;
*/
/**
- * Implementation of {@link WritableBuffer} for non-native endian byte order. Native variant is
- * {@link NativeWritableBufferImpl}.
+ * Implementation of {@link WritableBuffer} for non-native endian byte order.
* @author Roman Leventov
* @author Lee Rhodes
*/
diff --git a/datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/internal/NonNativeWritableMemoryImpl.java b/datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/internal/NonNativeWritableMemoryImpl.java
index 93ff62d..de74333 100644
--- a/datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/internal/NonNativeWritableMemoryImpl.java
+++ b/datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/internal/NonNativeWritableMemoryImpl.java
@@ -45,8 +45,7 @@ import org.apache.datasketches.memory.WritableMemory;
*/
/**
- * Implementation of {@link WritableMemory} for non-native endian byte order. Native variant is
- * {@link NativeWritableMemoryImpl}.
+ * Implementation of {@link WritableMemory} for non-native endian byte order.
* @author Roman Leventov
* @author Lee Rhodes
*/
diff --git a/datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/internal/Prim.java b/datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/internal/Prim.java
index 411be5b..96d8203 100644
--- a/datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/internal/Prim.java
+++ b/datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/internal/Prim.java
@@ -52,6 +52,7 @@ import static org.apache.datasketches.memory.internal.UnsafeUtil.SHORT_SHIFT;
*
* @author Lee Rhodes
*/
+@SuppressWarnings("javadoc")
public enum Prim {
BOOLEAN(ARRAY_BOOLEAN_BASE_OFFSET, ARRAY_BOOLEAN_INDEX_SCALE, BOOLEAN_SHIFT),
BYTE(ARRAY_BYTE_BASE_OFFSET, ARRAY_BYTE_INDEX_SCALE, BYTE_SHIFT),
diff --git a/datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/internal/StepBoolean.java b/datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/internal/StepBoolean.java
index b678516..45f81c3 100644
--- a/datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/internal/StepBoolean.java
+++ b/datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/internal/StepBoolean.java
@@ -22,7 +22,7 @@ package org.apache.datasketches.memory.internal;
import java.util.concurrent.atomic.AtomicIntegerFieldUpdater;
/**
- * This is a step boolean function that can change its state only once and is thread-safe.
+ * This is a step boolean function that can change its state only once.
*
* @author Lee Rhodes
*/
@@ -35,6 +35,10 @@ public final class StepBoolean {
private final int initialState;
private volatile int state;
+ /**
+ * Defines the initial state
+ * @param initialState the given initial state
+ */
public StepBoolean(final boolean initialState) {
this.initialState = initialState ? TRUE : FALSE;
state = this.initialState;
diff --git a/datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/internal/UnsafeUtil.java b/datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/internal/UnsafeUtil.java
index d9c352b..1fd3e19 100644
--- a/datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/internal/UnsafeUtil.java
+++ b/datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/internal/UnsafeUtil.java
@@ -29,7 +29,7 @@ import sun.misc.Unsafe;
*
* @author Lee Rhodes
*/
-@SuppressWarnings("restriction")
+@SuppressWarnings({"restriction", "javadoc"})
public final class UnsafeUtil {
public static final Unsafe unsafe;
public static final String JDK; //must be at least "1.8"
diff --git a/datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/internal/Util.java b/datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/internal/Util.java
index 14e932e..f9b1f30 100644
--- a/datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/internal/Util.java
+++ b/datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/internal/Util.java
@@ -34,6 +34,7 @@ import org.apache.datasketches.memory.Memory;
/**
* @author Lee Rhodes
*/
+@SuppressWarnings("javadoc")
public final class Util {
public static final String LS = System.getProperty("line.separator");
diff --git a/datasketches-memory-java9/src/main/java/module-info.java b/datasketches-memory-java9/src/main/java/module-info.java
index 0823348..78c9ce2 100644
--- a/datasketches-memory-java9/src/main/java/module-info.java
+++ b/datasketches-memory-java9/src/main/java/module-info.java
@@ -16,7 +16,7 @@
* specific language governing permissions and limitations
* under the License.
*/
-
+@SuppressWarnings("javadoc")
module org.apache.datasketches.memory {
requires java.base;
requires java.logging;
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@datasketches.apache.org
For additional commands, e-mail: commits-help@datasketches.apache.org