Skip to content

Commit 2625c98

Browse files
acogoluegnesacogoluegnes
committed
Document the usage of Netty for AMQP 091 Java client
References rabbitmq/rabbitmq-java-client#1663
1 parent 5b29340 commit 2625c98

File tree

3 files changed

+46
-34
lines changed

3 files changed

+46
-34
lines changed

‎client-libraries/java-api-guide.md‎

Lines changed: 36 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -965,42 +965,51 @@ ConnectionFactory cf = new ConnectionFactory();
965965
cf.setThreadFactory(ThreadManager.backgroundThreadFactory());
966966
```
967967

968-
### Support for Java non-blocking IO {#java-nio}
968+
### Use of Netty for Network I/O {#netty}
969969

970-
Version 4.0 of the Java client brings support for Java non-blocking
971-
IO (a.k.a Java NIO). NIO isn't supposed to be faster than blocking IO,
972-
it simply allows to control resources (in this case, threads) more easily.
970+
Version 5.27.0 of the Java client brings support for [Netty](https://netty.io/) for network I/O.
971+
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).
973972

974-
With the default blocking IO mode, each connection uses a thread to read
975-
from the network socket. With the NIO mode, you can control the number of
976-
threads that read and write from/to the network socket.
973+
With the default blocking I/O mode, each connection uses a thread to read from the network socket.
974+
With Netty, you can control the number of threads that read and write from/to the network.
977975

978-
Use the NIO mode if your Java process uses many connections (dozens or hundreds).
979-
You should use fewer threads than with the default blocking mode. With the
980-
appropriate number of threads set, you shouldn't
981-
experience any decrease in performance, especially if the connections are
982-
not so busy.
976+
Use Netty if your Java process uses many connections (dozens or hundreds).
977+
You should use fewer threads than with the default blocking mode.
978+
With the appropriate number of threads set, you shouldn't experience any decrease in performance, especially if the connections are not so busy.
983979

984-
NIO must be enabled explicitly:
980+
Netty is activated and configured with the `ConnectionFactory#netty()` helper.
981+
Netty's `EventLoopGroup` is the most important setting for an application picky about the number of threads.
982+
Here is an example of how to set it with 4 threads:
985983

986984
```java
987-
ConnectionFactory connectionFactory = new ConnectionFactory();
988-
connectionFactory.useNio();
985+
int nbThreads = 4;
986+
IoHandlerFactory ioHandlerFactory = NioIoHandler.newFactory();
987+
EventLoopGroup eventLoopGroup = new MultiThreadIoEventLoopGroup(
988+
nbThreads, ioHandlerFactory
989+
);
990+
connectionFactory.netty().eventLoopGroup(eventLoopGroup);
991+
// ...
992+
// dispose the event loop group after closing all connections
993+
eventLoopGroup.shutdownGracefully();
989994
```
990995

991-
The NIO mode can be configured through the `NioParams` class:
996+
Note the event loop group must be disposed of after the connection closes its connections.
997+
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).
998+
This is far from optimal, this is why setting an `EventLoopGroup` is highly recommended when using Netty.
999+
1000+
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.
1001+
Use `ConnectionFactory.netty().sslContext(SslContext)` instead, along with Netty's `SslContextBuilder` class.
1002+
Here is an example:
9921003

9931004
```java
994-
connectionFactory.setNioParams(new NioParams().setNbIoThreads(4));
1005+
X509Certificate caCertificate = ...;
1006+
connectionFactory.netty()
1007+
.sslContext(SslContextBuilder
1008+
.forClient() // mandatory, do not forget to call
1009+
.trustManager(caCertificate) // pass in certificate directly
1010+
.build());
9951011
```
9961012

997-
The NIO mode uses reasonable defaults, but you may need to change them according
998-
to your own workload. Some of the settings are: the total number of IO
999-
threads used, the size of buffers, a service executor to use for the IO loops,
1000-
parameters for the in-memory write queue (write requests are enqueued before
1001-
being sent on the network). Please read the Javadoc for details and defaults.
1002-
1003-
10041013
## Automatic Recovery From Network Failures {#recovery}
10051014
### Connection Recovery {#connection-recovery}
10061015

@@ -1475,6 +1484,9 @@ the [TLS guide](/docs/ssl). If you only want to configure
14751484
the Java client (especially the peer verification and trust manager parts),
14761485
read [the appropriate section](/docs/ssl#java-client) of the TLS guide.
14771486

1487+
Note Netty requires to use its own `SslContext` API when it is used for network I/O.
1488+
See the [Netty](#netty) section for more details.
1489+
14781490
## OAuth 2 Support {#oauth2-support}
14791491

14801492
The client can authenticate against an OAuth 2 server like [UAA](https://github.com/cloudfoundry/uaa).

‎client-libraries/java-client.md‎

Lines changed: 9 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -53,7 +53,7 @@ library.
5353

5454
### Latest Version
5555

56-
The current release of the RabbitMQ Java client is `5.26.0`.
56+
The current release of the RabbitMQ Java client is `5.27.0`.
5757

5858
### Adding Library Dependency
5959

@@ -66,15 +66,15 @@ If you're using Maven, add this dependency to the POM file of your project:
6666
<dependency>
6767
<groupId>com.rabbitmq</groupId>
6868
<artifactId>amqp-client</artifactId>
69-
<version>5.26.0</version>
69+
<version>5.27.0</version>
7070
</dependency>
7171
```
7272

7373
If using Gradle:
7474

7575
```groovy
7676
dependencies {
77-
compile 'com.rabbitmq:amqp-client:5.26.0'
77+
compile 'com.rabbitmq:amqp-client:5.27.0'
7878
}
7979
```
8080

@@ -102,20 +102,20 @@ source.
102102
<tr>
103103
<td>Binary, compiled for JDK 8 (Android 7.0) or newer</td>
104104
<td>
105-
<a href="https://repo1.maven.org/maven2/com/rabbitmq/amqp-client/5.26.0/amqp-client-5.26.0.jar">amqp-client-5.26.0.jar</a>
105+
<a href="https://repo1.maven.org/maven2/com/rabbitmq/amqp-client/5.27.0/amqp-client-5.27.0.jar">amqp-client-5.27.0.jar</a>
106106
</td>
107107
<td>
108-
<a href="https://repo1.maven.org/maven2/com/rabbitmq/amqp-client/5.26.0/amqp-client-5.26.0.jar.asc">Signature file</a>
108+
<a href="https://repo1.maven.org/maven2/com/rabbitmq/amqp-client/5.27.0/amqp-client-5.27.0.jar.asc">Signature file</a>
109109
</td>
110110
</tr>
111111

112112
<tr>
113113
<td>Source code</td>
114114
<td>
115-
<a href="https://repo1.maven.org/maven2/com/rabbitmq/amqp-client/5.26.0/amqp-client-5.26.0-sources.jar">amqp-client-5.26.0-sources.jar</a>
115+
<a href="https://repo1.maven.org/maven2/com/rabbitmq/amqp-client/5.27.0/amqp-client-5.27.0-sources.jar">amqp-client-5.27.0-sources.jar</a>
116116
</td>
117117
<td>
118-
<a href="https://repo1.maven.org/maven2/com/rabbitmq/amqp-client/5.26.0/amqp-client-5.26.0-sources.jar.asc">Signature file</a>
118+
<a href="https://repo1.maven.org/maven2/com/rabbitmq/amqp-client/5.27.0/amqp-client-5.27.0-sources.jar.asc">Signature file</a>
119119
</td>
120120
</tr>
121121
</table>
@@ -141,10 +141,10 @@ download it for off-line use:
141141
<tr>
142142
<td> A JAR file containing generated Javadoc documentation </td>
143143
<td>
144-
<a href="https://repo1.maven.org/maven2/com/rabbitmq/amqp-client/5.26.0/amqp-client-5.26.0-javadoc.jar">amqp-client-5.26.0-javadoc.jar</a>
144+
<a href="https://repo1.maven.org/maven2/com/rabbitmq/amqp-client/5.27.0/amqp-client-5.27.0-javadoc.jar">amqp-client-5.27.0-javadoc.jar</a>
145145
</td>
146146
<td>
147-
<a href="https://repo1.maven.org/maven2/com/rabbitmq/amqp-client/5.26.0/amqp-client-5.26.0-javadoc.jar.asc">Signature file</a>
147+
<a href="https://repo1.maven.org/maven2/com/rabbitmq/amqp-client/5.27.0/amqp-client-5.27.0-javadoc.jar.asc">Signature file</a>
148148
</td>
149149
</tr>
150150
</table>

‎docusaurus.config.js‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -221,7 +221,7 @@ const config = {
221221
},
222222

223223
// Client releases.
224-
java: '5.26.0',
224+
java: '5.27.0',
225225
dotnet: '7.0.0',
226226
},
227227
},

0 commit comments

Comments
 (0)