diff --git a/client-libraries/java-api-guide.md b/client-libraries/java-api-guide.md index 35a5ff732..aeea6602b 100644 --- a/client-libraries/java-api-guide.md +++ b/client-libraries/java-api-guide.md @@ -965,42 +965,51 @@ ConnectionFactory cf = new ConnectionFactory(); cf.setThreadFactory(ThreadManager.backgroundThreadFactory()); ``` -### Support for Java non-blocking IO {#java-nio} +### Use of Netty for Network I/O {#netty} -Version 4.0 of the Java client brings support for Java non-blocking -IO (a.k.a Java NIO). NIO isn't supposed to be faster than blocking IO, -it simply allows to control resources (in this case, threads) more easily. +Version 5.27.0 of the Java client brings support for [Netty](https://netty.io/) for network I/O. +Netty isn't supposed to be faster than blocking I/O, it gives more control on resources (e.g. threads) and provides advanced networking options, like [TLS with OpenSSL](https://netty.io/wiki/forked-tomcat-native.html) and [native transports](https://netty.io/wiki/native-transports.html) (epoll, io_uring, kqueue). -With the default blocking IO mode, each connection uses a thread to read -from the network socket. With the NIO mode, you can control the number of -threads that read and write from/to the network socket. +With the default blocking I/O mode, each connection uses a thread to read from the network socket. +With Netty, you can control the number of threads that read and write from/to the network. -Use the NIO mode if your Java process uses many connections (dozens or hundreds). -You should use fewer threads than with the default blocking mode. With the -appropriate number of threads set, you shouldn't -experience any decrease in performance, especially if the connections are -not so busy. +Use Netty if your Java process uses many connections (dozens or hundreds). +You should use fewer threads than with the default blocking mode. +With the appropriate number of threads set, you shouldn't experience any decrease in performance, especially if the connections are not so busy. -NIO must be enabled explicitly: +Netty is activated and configured with the `ConnectionFactory#netty()` helper. +Netty's `EventLoopGroup` is the most important setting for an application picky about the number of threads. +Here is an example of how to set it with 4 threads: ```java -ConnectionFactory connectionFactory = new ConnectionFactory(); -connectionFactory.useNio(); +int nbThreads = 4; +IoHandlerFactory ioHandlerFactory = NioIoHandler.newFactory(); +EventLoopGroup eventLoopGroup = new MultiThreadIoEventLoopGroup( + nbThreads, ioHandlerFactory +); +connectionFactory.netty().eventLoopGroup(eventLoopGroup); +// ... +// dispose the event loop group after closing all connections +eventLoopGroup.shutdownGracefully(); ``` -The NIO mode can be configured through the `NioParams` class: +Note the event loop group must be disposed of after the connection closes its connections. +If no event loop group is set, each connection will use its own, 1-thread event loop group (and will take care of closing it). +This is far from optimal, this is why setting an `EventLoopGroup` is highly recommended when using Netty. + +Netty uses its own `SslContext` API for [TLS](#tls) configuration (_not_ JDK's `SSLContext`), so the `ConnectionFactory#useSslProtocol()` methods have no effect when Netty is activated. +Use `ConnectionFactory.netty().sslContext(SslContext)` instead, along with Netty's `SslContextBuilder` class. +Here is an example: ```java - connectionFactory.setNioParams(new NioParams().setNbIoThreads(4)); +X509Certificate caCertificate = ...; +connectionFactory.netty() + .sslContext(SslContextBuilder + .forClient() // mandatory, do not forget to call + .trustManager(caCertificate) // pass in certificate directly + .build()); ``` -The NIO mode uses reasonable defaults, but you may need to change them according -to your own workload. Some of the settings are: the total number of IO -threads used, the size of buffers, a service executor to use for the IO loops, -parameters for the in-memory write queue (write requests are enqueued before -being sent on the network). Please read the Javadoc for details and defaults. - - ## Automatic Recovery From Network Failures {#recovery} ### Connection Recovery {#connection-recovery} @@ -1475,6 +1484,9 @@ the [TLS guide](/docs/ssl). If you only want to configure the Java client (especially the peer verification and trust manager parts), read [the appropriate section](/docs/ssl#java-client) of the TLS guide. +Note Netty requires to use its own `SslContext` API when it is used for network I/O. +See the [Netty](#netty) section for more details. + ## OAuth 2 Support {#oauth2-support} The client can authenticate against an OAuth 2 server like [UAA](https://github.com/cloudfoundry/uaa). diff --git a/client-libraries/java-client.md b/client-libraries/java-client.md index cd7b42d94..795ef6ecf 100644 --- a/client-libraries/java-client.md +++ b/client-libraries/java-client.md @@ -53,7 +53,7 @@ library. ### Latest Version -The current release of the RabbitMQ Java client is `5.26.0`. +The current release of the RabbitMQ Java client is `5.27.0`. ### Adding Library Dependency @@ -66,7 +66,7 @@ If you're using Maven, add this dependency to the POM file of your project: com.rabbitmq amqp-client - 5.26.0 + 5.27.0 ``` @@ -74,7 +74,7 @@ If using Gradle: ```groovy dependencies { - compile 'com.rabbitmq:amqp-client:5.26.0' + compile 'com.rabbitmq:amqp-client:5.27.0' } ``` @@ -102,20 +102,20 @@ source. Binary, compiled for JDK 8 (Android 7.0) or newer - amqp-client-5.26.0.jar + amqp-client-5.27.0.jar - Signature file + Signature file Source code - amqp-client-5.26.0-sources.jar + amqp-client-5.27.0-sources.jar - Signature file + Signature file @@ -141,10 +141,10 @@ download it for off-line use: A JAR file containing generated Javadoc documentation - amqp-client-5.26.0-javadoc.jar + amqp-client-5.27.0-javadoc.jar - Signature file + Signature file diff --git a/docusaurus.config.js b/docusaurus.config.js index dbce265ca..5ffb2e4c2 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -221,7 +221,7 @@ const config = { }, // Client releases. - java: '5.26.0', + java: '5.27.0', dotnet: '7.0.0', }, },