Merge acf93c4 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/WritableBuffer.java

@@ -385,13 +385,19 @@ 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. 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
+   * extending the MemoryRequestServer interface and set using the following method:
+   * <ul>
+   * <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.
    */
   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
+   * extending 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