Deprecate Stream-related API

Adds:

* TransportSettings abstract class
* NettyTransportSettings subclass of TransportSettings
* A new method on MongoClientSettings to configure TransportSettings

Deprecates:

* MongoClientSettings#streamFactoryFactory
* NettyStreamFactoryFactory
* NettyStreamFactory
* AsynchronousSocketChannelStreamFactory
* AsynchronousSocketChannelStreamFactoryFactory
* BufferProvider
* SocketStreamFactory
* Stream
* StreamFactory
* StreamFactoryFactory
* TlsChannelStreamFactoryFactory

JAVA-5051

Author: jyemin

driver-core/src/main/com/mongodb/MongoClientSettings.java

@@ -27,6 +27,7 @@
 import com.mongodb.connection.SocketSettings;
 import com.mongodb.connection.SslSettings;
 import com.mongodb.connection.StreamFactoryFactory;
+import com.mongodb.connection.TransportSettings;
 import com.mongodb.event.CommandListener;
 import com.mongodb.lang.Nullable;
 import com.mongodb.spi.dns.DnsClient;
@@ -62,6 +63,7 @@
  *
  * @since 3.7
  */
+@SuppressWarnings("deprecation")
 @Immutable
 public final class MongoClientSettings {
     private static final CodecRegistry DEFAULT_CODEC_REGISTRY =
@@ -89,6 +91,7 @@ public final class MongoClientSettings {
     private final boolean retryReads;
     private final ReadConcern readConcern;
     private final MongoCredential credential;
+    private final TransportSettings transportSettings;
     private final StreamFactoryFactory streamFactoryFactory;
     private final List<CommandListener> commandListeners;
     private final CodecRegistry codecRegistry;
@@ -209,6 +212,7 @@ public static final class Builder {
         private boolean retryReads = true;
         private ReadConcern readConcern = ReadConcern.DEFAULT;
         private CodecRegistry codecRegistry = MongoClientSettings.getDefaultCodecRegistry();
+        private TransportSettings transportSettings;
         private StreamFactoryFactory streamFactoryFactory;
         private List<CommandListener> commandListeners = new ArrayList<>();
 
@@ -252,6 +256,7 @@ private Builder(final MongoClientSettings settings) {
             serverApi = settings.getServerApi();
             dnsClient = settings.getDnsClient();
             inetAddressResolver = settings.getInetAddressResolver();
+            transportSettings = settings.getTransportSettings();
             streamFactoryFactory = settings.getStreamFactoryFactory();
             autoEncryptionSettings = settings.getAutoEncryptionSettings();
             contextProvider = settings.getContextProvider();
@@ -490,12 +495,29 @@ public Builder codecRegistry(final CodecRegistry codecRegistry) {
          * @param streamFactoryFactory the stream factory factory
          * @return this
          * @see #getStreamFactoryFactory()
+         * @deprecated Prefer {@link #transportSettings(TransportSettings)}
          */
+        @Deprecated
         public Builder streamFactoryFactory(final StreamFactoryFactory streamFactoryFactory) {
             this.streamFactoryFactory = notNull("streamFactoryFactory", streamFactoryFactory);
             return this;
         }
 
+        /**
+         * Sets the {@link TransportSettings} to apply.
+         *
+         * <p>
+         * If transport settings are applied, application of {@link #streamFactoryFactory} is ignored.
+         * </p>
+         *
+         * @param transportSettings the transport settings
+         * @return this
+         */
+        public Builder transportSettings(final TransportSettings transportSettings) {
+            this.transportSettings = notNull("transportSettings", transportSettings);
+            return this;
+        }
+
         /**
          * Adds the given command listener.
          *
@@ -771,12 +793,27 @@ public CodecRegistry getCodecRegistry() {
      *
      * @return the stream factory factory
      * @see Builder#streamFactoryFactory(StreamFactoryFactory)
+     * @deprecated  Prefer {@link #getTransportSettings()}
      */
+    @Deprecated
     @Nullable
     public StreamFactoryFactory getStreamFactoryFactory() {
         return streamFactoryFactory;
     }
 
+    /**
+     * Gets the settings for the underlying transport implementation
+     *
+     * @return the settings for the underlying transport implementation
+     *
+     * @since 4.11
+     * @see Builder#transportSettings(TransportSettings)
+     */
+    @Nullable
+    public TransportSettings getTransportSettings() {
+        return transportSettings;
+    }
+
     /**
      * Gets the list of added {@code CommandListener}.
      *
@@ -978,6 +1015,7 @@ public boolean equals(final Object o) {
                 && Objects.equals(writeConcern, that.writeConcern)
                 && Objects.equals(readConcern, that.readConcern)
                 && Objects.equals(credential, that.credential)
+                && Objects.equals(transportSettings, that.transportSettings)
                 && Objects.equals(streamFactoryFactory, that.streamFactoryFactory)
                 && Objects.equals(commandListeners, that.commandListeners)
                 && Objects.equals(codecRegistry, that.codecRegistry)
@@ -1000,11 +1038,11 @@ public boolean equals(final Object o) {
 
     @Override
     public int hashCode() {
-        return Objects.hash(readPreference, writeConcern, retryWrites, retryReads, readConcern, credential, streamFactoryFactory,
-                commandListeners, codecRegistry, loggerSettings, clusterSettings, socketSettings, heartbeatSocketSettings,
-                connectionPoolSettings, serverSettings, sslSettings, applicationName, compressorList, uuidRepresentation, serverApi,
-                autoEncryptionSettings, heartbeatSocketTimeoutSetExplicitly, heartbeatConnectTimeoutSetExplicitly, dnsClient,
-                inetAddressResolver, contextProvider);
+        return Objects.hash(readPreference, writeConcern, retryWrites, retryReads, readConcern, credential, transportSettings,
+                streamFactoryFactory, commandListeners, codecRegistry, loggerSettings, clusterSettings, socketSettings,
+                heartbeatSocketSettings, connectionPoolSettings, serverSettings, sslSettings, applicationName, compressorList,
+                uuidRepresentation, serverApi, autoEncryptionSettings, heartbeatSocketTimeoutSetExplicitly,
+                heartbeatConnectTimeoutSetExplicitly, dnsClient, inetAddressResolver, contextProvider);
     }
 
     @Override
@@ -1016,6 +1054,7 @@ public String toString() {
                 + ", retryReads=" + retryReads
                 + ", readConcern=" + readConcern
                 + ", credential=" + credential
+                + ", transportSettings=" + transportSettings
                 + ", streamFactoryFactory=" + streamFactoryFactory
                 + ", commandListeners=" + commandListeners
                 + ", codecRegistry=" + codecRegistry
@@ -1044,6 +1083,7 @@ private MongoClientSettings(final Builder builder) {
         retryReads = builder.retryReads;
         readConcern = builder.readConcern;
         credential = builder.credential;
+        transportSettings = builder.transportSettings;
         streamFactoryFactory = builder.streamFactoryFactory;
         codecRegistry = builder.codecRegistry;
         commandListeners = builder.commandListeners;

driver-core/src/main/com/mongodb/annotations/Evolving.java

@@ -18,7 +18,6 @@
 
 package com.mongodb.annotations;
 
-import com.mongodb.connection.StreamFactoryFactory;
 import org.bson.conversions.Bson;
 
 import java.lang.annotation.Documented;
@@ -51,11 +50,6 @@
  *     <td>Not applicable.</td>
  *   </tr>
  *   <tr>
- *     <td>Doing so allows customizing API behavior.</td>
- *     <td>{@link StreamFactoryFactory}</td>
- *     <td>Not applicable.</td>
- *   </tr>
- *   <tr>
  *     <td>Doing so facilitates writing application unit tests by creating a fake implementation.</td>
  *     <td>{@code com.mongodb.client.MongoClient}</td>
  *     <td>Applicable.</td>

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

@@ -29,7 +29,9 @@
  * Factory to create a Stream that's an AsynchronousSocketChannelStream. Throws an exception if SSL is enabled.
  *
  * @since 3.0
+ * @deprecated There is no replacement for this class.
  */
+@Deprecated
 public class AsynchronousSocketChannelStreamFactory implements StreamFactory {
     private final PowerOfTwoBufferPool bufferProvider = PowerOfTwoBufferPool.DEFAULT;
     private final SocketSettings settings;

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

@@ -23,7 +23,9 @@
  *
  * @see java.nio.channels.AsynchronousSocketChannel
  * @since 3.1
+ * @deprecated There is no replacement for this class.
  */
+@Deprecated
 public final class AsynchronousSocketChannelStreamFactoryFactory implements StreamFactoryFactory {
     private final AsynchronousChannelGroup group;
 

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

@@ -23,7 +23,9 @@
  * A provider of instances of ByteBuf.
  *
  * @since 3.0
+ * @deprecated There is no replacement for this interface.
  */
+@Deprecated
 @ThreadSafe
 public interface BufferProvider {
     /**

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

@@ -0,0 +1,207 @@
+/*
+ * 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.
+ */
+
+package com.mongodb.connection;
+
+import com.mongodb.annotations.Immutable;
+import com.mongodb.lang.Nullable;
+import io.netty.buffer.ByteBufAllocator;
+import io.netty.channel.EventLoopGroup;
+import io.netty.channel.socket.SocketChannel;
+import io.netty.handler.ssl.ReferenceCountedOpenSslClientContext;
+import io.netty.handler.ssl.SslContext;
+import io.netty.handler.ssl.SslContextBuilder;
+import io.netty.handler.ssl.SslProvider;
+
+import java.security.Security;
+
+import static com.mongodb.assertions.Assertions.isTrueArgument;
+import static com.mongodb.assertions.Assertions.notNull;
+
+/**
+ * A {@code TransportSettings} implementation for a <a href="http://netty.io/">Netty</a>-based transport implementation.
+ *
+ * @since 4.11
+ */
+@Immutable
+public final class NettyTransportSettings extends TransportSettings {
+
+    private final EventLoopGroup eventLoopGroup;
+    private final Class<? extends SocketChannel> socketChannelClass;
+    private final ByteBufAllocator allocator;
+    private final SslContext sslContext;
+
+    /**
+     * Gets a builder for an instance of {@code NettyStreamFactoryFactory}.
+     * @return the builder
+     */
+    static Builder builder() {
+        return new Builder();
+    }
+
+    /**
+     * A builder for an instance of {@code NettyStreamFactoryFactory}.
+     */
+    public static final class Builder {
+        private ByteBufAllocator allocator;
+        private Class<? extends SocketChannel> socketChannelClass;
+        private EventLoopGroup eventLoopGroup;
+        private SslContext sslContext;
+
+        private Builder() {
+        }
+
+        /**
+         * Sets the allocator.
+         *
+         * @param allocator the allocator to use for ByteBuf instances
+         * @return this
+         */
+        public Builder allocator(final ByteBufAllocator allocator) {
+            this.allocator = notNull("allocator", allocator);
+            return this;
+        }
+
+        /**
+         * Sets the socket channel class
+         *
+         * @param socketChannelClass the socket channel class
+         * @return this
+         */
+        public Builder socketChannelClass(final Class<? extends SocketChannel> socketChannelClass) {
+            this.socketChannelClass = notNull("socketChannelClass", socketChannelClass);
+            return this;
+        }
+
+        /**
+         * Sets the event loop group.
+         *
+         * <p>It is highly recommended to supply your own event loop group and manage its shutdown.  Otherwise, the event
+         * loop group created by default will not be shutdown properly.</p>
+         *
+         * @param eventLoopGroup the event loop group that all channels created by this factory will be a part of
+         * @return this
+         */
+        public Builder eventLoopGroup(final EventLoopGroup eventLoopGroup) {
+            this.eventLoopGroup = notNull("eventLoopGroup", eventLoopGroup);
+            return this;
+        }
+
+        /**
+         * Sets a {@linkplain SslContextBuilder#forClient() client-side} {@link SslContext io.netty.handler.ssl.SslContext},
+         * which overrides the standard {@link SslSettings#getContext()}.
+         * By default, it is {@code null} and {@link SslSettings#getContext()} is at play.
+         * <p>
+         * This option may be used as a convenient way to utilize
+         * <a href="https://www.openssl.org/">OpenSSL</a> as an alternative to the TLS/SSL protocol implementation in a JDK.
+         * To achieve this, specify {@link SslProvider#OPENSSL} TLS/SSL protocol provider via
+         * {@link SslContextBuilder#sslProvider(SslProvider)}. Note that doing so adds a runtime dependency on
+         * <a href="https://netty.io/wiki/forked-tomcat-native.html">netty-tcnative</a>, which you must satisfy.
+         * <p>
+         * Notes:
+         * <ul>
+         *    <li>Netty {@link SslContext} may not examine some
+         *    {@linkplain Security security}/{@linkplain System#getProperties() system} properties that are used to
+         *    <a href="https://docs.oracle.com/javase/8/docs/technotes/guides/security/jsse/JSSERefGuide.html#Customization">
+         *    customize JSSE</a>. Therefore, instead of using them you may have to apply the equivalent configuration programmatically,
+         *    if both the {@link SslContextBuilder} and the TLS/SSL protocol provider of choice support it.
+         *    </li>
+         *    <li>Only {@link SslProvider#JDK} and {@link SslProvider#OPENSSL} TLS/SSL protocol providers are supported.
+         *    </li>
+         * </ul>
+         *
+         * @param sslContext The Netty {@link SslContext}, which must be created via {@linkplain SslContextBuilder#forClient()}.
+         * @return {@code this}.
+         */
+        public Builder sslContext(final SslContext sslContext) {
+            this.sslContext = notNull("sslContext", sslContext);
+            isTrueArgument("sslContext must be client-side", sslContext.isClient());
+            isTrueArgument("sslContext must use either SslProvider.JDK or SslProvider.OPENSSL TLS/SSL protocol provider",
+                    !(sslContext instanceof ReferenceCountedOpenSslClientContext));
+
+            return this;
+        }
+
+        /**
+         * Build an instance of {@code NettyStreamFactoryFactory}.
+         * @return factory of the netty stream factory
+         */
+        public NettyTransportSettings build() {
+            return new NettyTransportSettings(this);
+        }
+    }
+
+    /**
+     * Gets the event loop group.
+     *
+     * @return the event loop group
+     * @see Builder#eventLoopGroup(EventLoopGroup)
+     */
+    @Nullable
+    public EventLoopGroup getEventLoopGroup() {
+        return eventLoopGroup;
+    }
+
+    /**
+     * Gets the socket channel class.
+     *
+     * @return the socket channel class
+     * @see Builder#socketChannelClass(Class)
+     */
+    @Nullable
+    public Class<? extends SocketChannel> getSocketChannelClass() {
+        return socketChannelClass;
+    }
+
+    /**
+     * Gets the allocator.
+     *
+     * @return the allocator
+     * @see Builder#allocator(ByteBufAllocator)
+     */
+    @Nullable
+    public ByteBufAllocator getAllocator() {
+        return allocator;
+    }
+
+    /**
+     * Gets the SSL Context.
+     *
+     * @return the SSL context
+     * @see Builder#sslContext(SslContext)
+     */
+    @Nullable
+    public SslContext getSslContext() {
+        return sslContext;
+    }
+
+    @Override
+    public String toString() {
+        return "NettyTransportSettings{"
+                + "eventLoopGroup=" + eventLoopGroup
+                + ", socketChannelClass=" + socketChannelClass
+                + ", allocator=" + allocator
+                + ", sslContext=" + sslContext
+                + '}';
+    }
+
+    private NettyTransportSettings(final Builder builder) {
+        allocator = builder.allocator;
+        socketChannelClass = builder.socketChannelClass;
+        eventLoopGroup = builder.eventLoopGroup;
+        sslContext = builder.sslContext;
+    }
+}