Document Netty configuration

References #269

Author: acogoluegnes

pom.xml

@@ -416,7 +416,7 @@
           <attributes>
             <project-artifact-id>${project.artifactId}</project-artifact-id>
             <project-version>${project.version}</project-version>
-            <protonj-version>${proton-j.version}</protonj-version>
+            <netty-version>${netty.version}</netty-version>
             <build-number>${buildNumber}</build-number>
             <imagesdir>./images</imagesdir>
             <idprefix />

src/docs/asciidoc/advanced-topics.adoc

@@ -0,0 +1,57 @@
+:test-examples: ../../test/java/com/rabbitmq/stream/docs
+
+=== Advanced Topics
+
+==== Using Native `epoll`
+
+The stream Java client uses the https://netty.io/[Netty] network framework and its Java NIO transport implementation by default.
+This should be a reasonable default for most applications.
+
+Netty also allows using https://netty.io/wiki/native-transports.html[JNI transports].
+They are less portable than Java NIO, but they can be more performant for some workloads (even though the RabbitMQ team has not seen any significant improvement in their own tests).
+
+The https://en.wikipedia.org/wiki/Epoll[Linux `epoll` transport] is a popular choice, so we'll see how to configure with the stream Java client.
+Other JNI transports can be configured in the same way.
+
+The native transport dependency must be added to the dependency manager.
+We must pull the native binaries compiled for our OS and architecture, in our example Linux x86-64, so we are using the `linux-x86_64` classifier.
+Here is the declaration for Maven:
+
+.Declaring the Linux x86-64 native `epoll` transport dependency with Maven
+[source,xml,subs="attributes,specialcharacters"]
+----
+<dependencies>
+
+  <dependency>
+    <groupId>io.netty</groupId>
+    <artifactId>netty-transport-native-epoll</artifactId>
+    <version>{netty-version}</version>
+    <classifier>linux-x86_64</classifier>
+  </dependency>
+
+</dependencies>
+----
+
+And for Gradle:
+
+.Declaring the Linux x86-64 native `epoll` transport dependency with Gradle
+[source,groovy,subs="attributes,specialcharacters"]
+----
+dependencies {
+  compile "io.netty:netty-transport-native-epoll:{netty-version}:linux-x86_64"
+}
+----
+
+The native `epoll` transport is set up when the environment is configured:
+
+.Configuring the native `epoll` transport in the environment
+[source,java,indent=0]
+--------
+include::{test-examples}/EnvironmentUsage.java[tag=native-epoll]
+--------
+<1> Create the `epoll` event loop group (don't forget to close it!)
+<2> Use the Netty configuration helper
+<3> Set the event loop group
+<4> Set the channel class to use
+
+Note the event loop group must be closed explicitly: the environment will not close it itself as it is provided externally.

src/docs/asciidoc/api.adoc

@@ -227,6 +227,28 @@ elements that need to be configured.
 |Helper to configure a `SslContext` that trusts all server certificates
 and does not use a client private key. **Only for development**.
 |Disabled by default.
+
+|`netty`
+|Configuration helper for Netty.
+|
+
+|`netty#eventLoopGroup`
+|Netty's event dispatcher.
+It is the developer's responsibility to close the `EventLoopGroup` they provide.
+|`NioEventLoopGroup` instance closed automatically with the `Environment` instance.
+
+|`netty#ByteBufAllocator`
+|`ByteBuf` allocator.
+|ByteBufAllocator.DEFAULT
+
+|`netty#channelCustomizer`
+|Extension point to customize Netty's `Channel` instances used for connections.
+|None
+
+|`netty#bootstrapCustomizer`
+|Extension point to customize Netty's `Bootstrap` instances used to configure connections.
+|None
+
 |===
 
 ===== When a Load Balancer is in Use

src/docs/asciidoc/index.adoc

@@ -24,6 +24,8 @@ include::api.adoc[]
 
 include::super-streams.adoc[]
 
+include::advanced-topics.adoc[]
+
 include::building.adoc[]
 
 include::performance-tool.adoc[]

src/main/java/com/rabbitmq/stream/EnvironmentBuilder.java

@@ -431,7 +431,7 @@ interface NettyConfiguration {
 
     /**
      * An extension point to customize Netty's {@link io.netty.channel.Channel}s used for
-     * connection.
+     * connections.
      *
      * @param channelCustomizer
      * @return the Netty configuration helper

src/test/java/com/rabbitmq/stream/docs/EnvironmentUsage.java

@@ -18,13 +18,20 @@
 import com.rabbitmq.stream.ByteCapacity;
 import com.rabbitmq.stream.Environment;
 
+import com.rabbitmq.stream.EnvironmentBuilder;
+import io.netty.channel.Channel;
+import io.netty.channel.EventLoopGroup;
+import io.netty.channel.epoll.EpollEventLoopGroup;
+import io.netty.channel.epoll.EpollSocketChannel;
 import io.netty.handler.ssl.SslContext;
 import io.netty.handler.ssl.SslContextBuilder;
 import java.io.FileInputStream;
 import java.security.cert.CertificateFactory;
 import java.security.cert.X509Certificate;
 import java.time.Duration;
 import java.util.Arrays;
+import java.util.Set;
+import java.util.concurrent.ConcurrentHashMap;
 
 public class EnvironmentUsage {
 
@@ -134,4 +141,16 @@ void deleteStream() {
         // end::stream-deletion[]
     }
 
+    void nativeEpoll() {
+        // tag::native-epoll[]
+        EventLoopGroup epollEventLoopGroup = new EpollEventLoopGroup();  // <1>
+        Environment environment = Environment.builder()
+            .netty()  // <2>
+                .eventLoopGroup(epollEventLoopGroup)  // <3>
+                .bootstrapCustomizer(b -> b.channel(EpollSocketChannel.class))  // <4>
+                .environmentBuilder()
+            .build();
+        // end::native-epoll[]
+    }
+
 }