Reorganize NettyBufferProvider, NettyByteBuf and improve docs

driver-core/src/main/com/mongodb/connection/BufferProvider.java

@@ -16,13 +16,15 @@
 
 package com.mongodb.connection;
 
+import com.mongodb.annotations.ThreadSafe;
 import org.bson.ByteBuf;
 
 /**
  * A provider of instances of ByteBuf.
  *
  * @since 3.0
  */
+@ThreadSafe
 public interface BufferProvider {
     /**
      * Gets a buffer with the givens capacity.

driver-core/src/main/com/mongodb/connection/netty/NettyStream.java

@@ -29,6 +29,7 @@
 import com.mongodb.connection.SocketSettings;
 import com.mongodb.connection.SslSettings;
 import com.mongodb.connection.Stream;
+import com.mongodb.internal.connection.netty.NettyByteBuf;
 import com.mongodb.lang.Nullable;
 import io.netty.bootstrap.Bootstrap;
 import io.netty.buffer.ByteBufAllocator;

driver-core/src/main/com/mongodb/connection/netty/NettyByteBuf.java → driver-core/src/main/com/mongodb/internal/connection/netty/NettyByteBuf.java

@@ -14,29 +14,41 @@
  * limitations under the License.
  */
 
-package com.mongodb.connection.netty;
+package com.mongodb.internal.connection.netty;
 
 import org.bson.ByteBuf;
 
 import java.nio.ByteBuffer;
 import java.nio.ByteOrder;
 
-final class NettyByteBuf implements ByteBuf {
+/**
+ * <p>This class is not part of the public API and may be removed or changed at any time</p>
+ */
+public final class NettyByteBuf implements ByteBuf {
 
     private io.netty.buffer.ByteBuf proxied;
     private boolean isWriting = true;
 
+    /**
+     * @param proxied This constructor stores a reference to {@code proxied} in the heap memory
+     * but does not {@linkplain io.netty.buffer.ByteBuf#retain() retain} {@code proxied}.
+     * A caller may have to do that depending on the
+     * <a href="https://jira.mongodb.org/browse/JAVA-3964">reference counting approach</a> he uses.
+     */
     @SuppressWarnings("deprecation")
-    NettyByteBuf(final io.netty.buffer.ByteBuf proxied) {
+    public NettyByteBuf(final io.netty.buffer.ByteBuf proxied) {
         this.proxied = proxied.order(ByteOrder.LITTLE_ENDIAN);
     }
 
-    NettyByteBuf(final io.netty.buffer.ByteBuf proxied, final boolean isWriting) {
+    /**
+     * @param proxied See {@link #NettyByteBuf(io.netty.buffer.ByteBuf)}.
+     */
+    private NettyByteBuf(final io.netty.buffer.ByteBuf proxied, final boolean isWriting) {
         this(proxied);
         this.isWriting = isWriting;
     }
 
-    io.netty.buffer.ByteBuf asByteBuf() {
+    public io.netty.buffer.ByteBuf asByteBuf() {
         return proxied;
     }
 

driver-core/src/main/com/mongodb/internal/connection/netty/package-info.java

@@ -0,0 +1,23 @@
+/*
+ * Copyright 2008-present MongoDB, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * Contains <a href="https://netty.io/">Netty</a>-specific program elements.
+ */
+@NonNullApi
+package com.mongodb.internal.connection.netty;
+
+import com.mongodb.lang.NonNullApi;

driver-core/src/test/unit/com/mongodb/connection/netty/ByteBufSpecification.groovy

@@ -16,6 +16,7 @@
 
 package com.mongodb.connection.netty
 
+import com.mongodb.internal.connection.netty.NettyByteBuf
 import io.netty.buffer.ByteBufAllocator
 import org.bson.ByteBufNIO
 import spock.lang.Specification

driver-core/src/test/unit/com/mongodb/internal/connection/ByteBufSpecification.groovy

@@ -16,7 +16,11 @@
 
 package com.mongodb.internal.connection
 
-import com.mongodb.connection.netty.NettyBufferProvider
+import com.mongodb.connection.BufferProvider
+import com.mongodb.internal.connection.netty.NettyByteBuf
+import io.netty.buffer.ByteBufAllocator
+import io.netty.buffer.PooledByteBufAllocator
+import org.bson.ByteBuf
 import spock.lang.Specification
 
 class ByteBufSpecification extends Specification {
@@ -234,4 +238,22 @@ class ByteBufSpecification extends Specification {
         where:
         provider << [new NettyBufferProvider(), new SimpleBufferProvider()]
     }
+
+    static final class NettyBufferProvider implements BufferProvider {
+        private final ByteBufAllocator allocator
+
+        NettyBufferProvider() {
+            allocator = PooledByteBufAllocator.DEFAULT
+        }
+
+        @Override
+        ByteBuf getBuffer(final int size) {
+            io.netty.buffer.ByteBuf buffer = allocator.directBuffer(size, size)
+            try {
+                new NettyByteBuf(buffer.retain())
+            } finally {
+                buffer.release();
+            }
+        }
+    }
 }