Merge a12f600 into bcc87ff

datasketches-memory-java8-tests/src/test/java/org/apache/datasketches/memory/test/MemoryTest.java

@@ -352,7 +352,7 @@ public void checkMonitorDirectStats() throws Exception {
     int bytes = 1024;
     long curAllocations = BaseState.getCurrentDirectMemoryAllocations();
     long curAllocated   = BaseState.getCurrentDirectMemoryAllocated();
-    System.err.println(curAllocations + " should be zero!");
+    if (curAllocations != 0) { System.err.println(curAllocations + " should be zero!"); }
     WritableHandle wh1 = WritableMemory.allocateDirect(bytes);
     WritableHandle wh2 = WritableMemory.allocateDirect(bytes);
     assertEquals(BaseState.getCurrentDirectMemoryAllocations(), 2L + curAllocations);

datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/Memory.java

@@ -35,7 +35,7 @@
 
 public interface Memory extends BaseState {
 
-  //BYTE BUFFERf
+  //BYTE BUFFER
 
   /**
    * Accesses the given <i>ByteBuffer</i> for read-only operations. The returned <i>Memory</i> object has

datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/MemoryRequestServer.java

@@ -20,10 +20,8 @@
 package org.apache.datasketches.memory;
 
 /**
- * The MemoryRequestServer is a callback interface to provide a means for a direct (off-heap),
- * dynamic WritableMemory object to request more memory from the owner of the
- * {@link WritableHandle}. Refer to {@link DefaultMemoryRequestServer} for how this can be
- * used.
+ * The MemoryRequestServer is a callback interface to provide a means for direct (off-heap), heap and ByteBuffer
+ * backed resources to request more memory.
  *
  * @author Lee Rhodes
  */
@@ -40,7 +38,8 @@ public interface MemoryRequestServer {
   WritableMemory request(WritableMemory currentWritableMemory, long capacityBytes);
 
   /**
-   * Request close the AutoCloseable resource.
+   * Request close the AutoCloseable resource. This only applies to resources allocated using
+   * WritableMemory.allocateDirect(...).
    * This may be ignored depending on the application implementation.
    * @param memToClose the relevant WritbleMemory to be considered for closing. It must be non-null.
    * @param newMemory the newly allocated WritableMemory. It must be non-null.

datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/WritableBuffer.java

@@ -385,13 +385,20 @@ void putBooleanArray(boolean[] srcArray, int srcOffsetBooleans,
 
   //OTHER WRITABLE API METHODS
   /**
-   * For ByteBuffer and Direct Memory backed resources only. Heap and Map backed resources will return null.
-   * Gets the MemoryRequestServer object used by dynamic Memory-backed objects
-   * to request additional memory.  To customize the actions of the MemoryRequestServer,
-   * extend the MemoryRequestServer interfact and
-   * set using {@link WritableMemory#allocateDirect(long, ByteOrder, MemoryRequestServer)}.
-   * If not explicity set, this returns the {@link DefaultMemoryRequestServer}.
-   * @return the MemoryRequestServer object (if direct memory) or null.
+   * WritableBuffer enables this for ByteBuffer backed resources. However, the object returned is in the form of
+   * a WritableMemory. To convert to WritableBuffer use asWritableBuffer(). To enable for Heap and Direct Memory
+   * resources, use the WritableMemory to configure and then call asWritableBuffer().
+   * Map backed resources will always return null.
+   * Gets the MemoryRequestServer object, if set, for the above resources to request additional memory.
+   * The user must customize the actions of the MemoryRequestServer by
+   * implementing the MemoryRequestServer interface and set using the following method:
+   * <ul>
+   * <li>{@link WritableBuffer#writableWrap(ByteBuffer, ByteOrder, MemoryRequestServer)}</li>
+   * </ul>
+   * Simple implementation examples include the DefaultMemoryRequestServer in the main tree, as well as
+   * the ExampleMemoryRequestServerTest and the use with ByteBuffer documented in the DruidIssue11544Test
+   * in the test tree.
+   * @return the MemoryRequestServer object or null.
    */
   public MemoryRequestServer getMemoryRequestServer();
 

datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/WritableMemory.java

@@ -617,11 +617,18 @@ static WritableMemory writableWrap(double[] array) {
 
   //OTHER WRITABLE API METHODS
   /**
-   * For ByteBuffer and Direct Memory backed resources only. Heap and Map backed resources will return null.
-   * Gets the MemoryRequestServer object used by dynamic Memory-backed objects
-   * to request additional memory.  To customize the actions of the MemoryRequestServer,
-   * extend the MemoryRequestServer interface and
-   * set using {@link WritableMemory#allocateDirect(long, ByteOrder, MemoryRequestServer)}.
+   * WritableMemory enables this for ByteBuffer, Heap and Direct Memory backed resources.
+   * Map backed resources will always return null.
+   * Gets the MemoryRequestServer object, if set, for the above resources to request additional memory.
+   * The user must customize the actions of the MemoryRequestServer by
+   * implementing the MemoryRequestServer interface and set using one of these methods:
+   * <ul><li>{@link WritableMemory#allocateDirect(long, ByteOrder, MemoryRequestServer)}</li>
+   * <li>{@link WritableMemory#allocate(int, ByteOrder, MemoryRequestServer)}</li>
+   * <li>{@link WritableMemory#writableWrap(ByteBuffer, ByteOrder, MemoryRequestServer)}</li>
+   * </ul>
+   * Simple implementation examples include the DefaultMemoryRequestServer in the main tree, as well as
+   * the ExampleMemoryRequestServerTest and the use with ByteBuffer documented in the DruidIssue11544Test
+   * in the test tree.
    * @return the MemoryRequestServer object or null.
    */
   MemoryRequestServer getMemoryRequestServer();

datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/internal/BaseStateImpl.java

@@ -162,7 +162,8 @@ public final long getCumulativeOffset(final long offsetBytes) {
     return cumBaseOffset_ + offsetBytes;
   }
 
-  //made public in WritableMemoryImpl and WritableBufferImpl, only implemented in Direct Leafs
+  //Documented in WritableMemory and WritableBuffer interfaces.
+  //Implemented in the Leaf nodes; Required here by toHex(...).
   abstract MemoryRequestServer getMemoryRequestServer();
 
   //Overridden by ByteBuffer, Direct and Map leafs