0
# RabbitMQ Java Client
1

2
The RabbitMQ Java Client is a comprehensive library that enables Java applications to communicate with RabbitMQ message broker servers. It provides a complete implementation of the AMQP 0-9-1 protocol, offering APIs for connection management, channel operations, message publishing and consuming, queue and exchange management, and advanced messaging patterns.
3

4
## Package Information
5

6
- **Package Name**: com.rabbitmq:amqp-client
7
- **Package Type**: maven
8
- **Language**: Java
9
- **Installation**: `<dependency><groupId>com.rabbitmq</groupId><artifactId>amqp-client</artifactId><version>5.25.0</version></dependency>`
10
- **Requires**: Java 8 or higher
11

12
## Core Imports
13

14
```java
15
import com.rabbitmq.client.ConnectionFactory;
16
import com.rabbitmq.client.Connection;
17
import com.rabbitmq.client.Channel;
18
import com.rabbitmq.client.DeliverCallback;
19
import com.rabbitmq.client.CancelCallback;
20
```
21

22
## Basic Usage
23

24
```java
25
import com.rabbitmq.client.*;
26

27
// Create connection factory and configure
28
ConnectionFactory factory = new ConnectionFactory();
29
factory.setHost("localhost");
30
factory.setPort(5672);
31
factory.setUsername("guest");
32
factory.setPassword("guest");
33
factory.setVirtualHost("/");
34

35
// Create connection and channel
36
Connection connection = factory.newConnection();
37
Channel channel = connection.createChannel();
38

39
// Declare a queue
40
channel.queueDeclare("hello", false, false, false, null);
41

42
// Publish a message
43
String message = "Hello World!";
44
channel.basicPublish("", "hello", null, message.getBytes("UTF-8"));
45

46
// Consume messages
47
DeliverCallback deliverCallback = (consumerTag, delivery) -> {
48
    String receivedMessage = new String(delivery.getBody(), "UTF-8");
49
    System.out.println("Received: " + receivedMessage);
50
};
51
channel.basicConsume("hello", true, deliverCallback, consumerTag -> { });
52

53
// Clean up
54
channel.close();
55
connection.close();
56
```
57

58
## Architecture
59

60
The RabbitMQ Java Client is built around several key components:
61

62
- **Connection Management**: `ConnectionFactory` creates and configures connections to RabbitMQ brokers
63
- **Channel Operations**: `Channel` interface provides all AMQP operations (publish, consume, declare, bind, etc.)
64
- **Message Handling**: Classes for message properties, delivery metadata, and content
65
- **Consumer API**: Interfaces and callbacks for consuming messages asynchronously
66
- **Recovery System**: Automatic connection and topology recovery from network failures
67
- **Configuration**: Extensive configuration options for connections, channels, SSL, authentication
68
- **Observability**: Metrics collection and distributed tracing integration
69

70
## Capabilities
71

72
### Connection and Channel Management
73

74
Core functionality for establishing connections to RabbitMQ brokers and creating channels for AMQP operations.
75

76
```java { .api }
77
// Connection factory for creating connections
78
public class ConnectionFactory implements Cloneable {
79
    public Connection newConnection() throws IOException, TimeoutException;
80
    public void setHost(String host);
81
    public void setPort(int port);
82
    public void setUsername(String username);
83
    public void setPassword(String password);
84
    public void setVirtualHost(String virtualHost);
85
    public void setUri(String uri) throws URISyntaxException, NoSuchAlgorithmException, KeyManagementException;
86
}
87

88
// Connection interface
89
public interface Connection extends Closeable, ShutdownNotifier {
90
    Channel createChannel() throws IOException;
91
    boolean isOpen();
92
    Map<String, Object> getServerProperties();
93
    void addShutdownListener(ShutdownListener listener);
94
    void close() throws IOException;
95
}
96

97
// Channel interface for AMQP operations
98
public interface Channel extends Closeable, ShutdownNotifier {
99
    int getChannelNumber();
100
    Connection getConnection();
101
    boolean isOpen();
102
    void close() throws IOException, TimeoutException;
103
}
104
```
105

106
[Connection and Channel Management](./connection-channel.md)
107

108
### Message Publishing and Exchange Operations
109

110
Operations for publishing messages to exchanges and managing exchange topology.
111

112
```java { .api }
113
// Basic message publishing
114
void basicPublish(String exchange, String routingKey, BasicProperties props, byte[] body) throws IOException;
115

116
// Exchange operations
117
Exchange.DeclareOk exchangeDeclare(String exchange, String type) throws IOException;
118
Exchange.DeclareOk exchangeDeclare(String exchange, String type, boolean durable, boolean autoDelete, Map<String, Object> arguments) throws IOException;
119
Exchange.DeleteOk exchangeDelete(String exchange) throws IOException;
120
Exchange.BindOk exchangeBind(String destination, String source, String routingKey) throws IOException;
121
```
122

123
[Message Publishing](./publishing.md)
124

125
### Message Consuming and Queue Operations
126

127
Operations for consuming messages from queues and managing queue topology.
128

129
```java { .api }
130
// Queue operations
131
Queue.DeclareOk queueDeclare(String queue, boolean durable, boolean exclusive, boolean autoDelete, Map<String, Object> arguments) throws IOException;
132
Queue.DeleteOk queueDelete(String queue) throws IOException;
133
Queue.BindOk queueBind(String queue, String exchange, String routingKey) throws IOException;
134

135
// Message consuming
136
String basicConsume(String queue, boolean autoAck, DeliverCallback deliverCallback, CancelCallback cancelCallback) throws IOException;
137
GetResponse basicGet(String queue, boolean autoAck) throws IOException;
138
void basicAck(long deliveryTag, boolean multiple) throws IOException;
139
void basicNack(long deliveryTag, boolean multiple, boolean requeue) throws IOException;
140
```
141

142
[Message Consuming](./consuming.md)
143

144
### Consumer API and Callbacks
145

146
Interfaces and implementations for consuming messages asynchronously with callbacks.
147

148
```java { .api }
149
// Functional interfaces for consumers
150
@FunctionalInterface
151
public interface DeliverCallback {
152
    void handle(String consumerTag, Delivery delivery) throws IOException;
153
}
154

155
@FunctionalInterface
156
public interface CancelCallback {
157
    void handle(String consumerTag) throws IOException;
158
}
159

160
// Consumer interface
161
public interface Consumer {
162
    void handleDelivery(String consumerTag, Envelope envelope, AMQP.BasicProperties properties, byte[] body) throws IOException;
163
    void handleCancel(String consumerTag) throws IOException;
164
    String getConsumerTag();
165
}
166
```
167

168
[Consumer API](./consumer-api.md)
169

170
### Configuration and Connection Settings
171

172
Configuration classes for connection parameters, addressing, authentication, and SSL settings.
173

174
```java { .api }
175
// Address and resolver classes
176
public class Address {
177
    public static Address[] parseAddresses(String addresses) throws IOException;
178
    public String getHost();
179
    public int getPort();
180
}
181

182
public interface AddressResolver {
183
    List<Address> getAddresses() throws IOException;
184
}
185

186
// Authentication configuration
187
public interface SaslConfig {
188
    SaslMechanism getSaslMechanism(String[] serverMechanisms);
189
}
190
```
191

192
[Configuration](./configuration.md)
193

194
### Error Handling and Recovery
195

196
Exception classes and automatic recovery mechanisms for handling network failures and errors.
197

198
```java { .api }
199
// Core exception types
200
public class ShutdownSignalException extends RuntimeException {
201
    public Object getReason();
202
    public boolean isHardError();
203
    public boolean isInitiatedByApplication();
204
}
205

206
// Recovery interfaces
207
public interface RecoverableConnection extends Connection {
208
    void addRecoveryListener(RecoveryListener listener);
209
    boolean isOpen();
210
}
211

212
public interface RecoveryListener {
213
    void handleRecovery(Recoverable recoverable);
214
    void handleRecoveryStarted(Recoverable recoverable);
215
}
216
```
217

218
[Error Handling and Recovery](./error-recovery.md)
219

220
### Publisher Confirms and Returns
221

222
Mechanisms for reliable message publishing with publisher confirms and handling returned messages.
223

224
```java { .api }
225
// Publisher confirms
226
void confirmSelect() throws IOException;
227
boolean waitForConfirms() throws InterruptedException;
228
void addConfirmListener(ConfirmListener listener);
229

230
@FunctionalInterface
231
public interface ConfirmCallback {
232
    void handle(long deliveryTag, boolean multiple) throws IOException;
233
}
234

235
// Returns handling
236
void addReturnListener(ReturnListener listener);
237

238
@FunctionalInterface
239
public interface ReturnCallback {
240
    void handle(Return returnMessage) throws IOException;
241
}
242
```
243

244
[Publisher Confirms and Returns](./confirms-returns.md)
245

246
### RPC Support
247

248
Remote Procedure Call (RPC) patterns over AMQP for request-response messaging.
249

250
```java { .api }
251
// RPC client for making calls
252
public class RpcClient {
253
    public RpcClient(Channel channel, String exchange, String routingKey) throws IOException;
254
    public byte[] primitiveCall(byte[] message) throws IOException, ShutdownSignalException, TimeoutException;
255
    public String stringCall(String message) throws IOException, ShutdownSignalException, TimeoutException;
256
    public void close() throws IOException;
257
}
258

259
// RPC server for handling calls
260
public abstract class RpcServer {
261
    public abstract byte[] handleCall(byte[] requestBody, AMQP.BasicProperties replyProperties);
262
    public void mainloop() throws IOException;
263
}
264
```
265

266
[RPC Support](./rpc.md)
267

268
### Observability and Metrics
269

270
Interfaces for collecting metrics and integrating with observability systems.
271

272
```java { .api }
273
// Metrics collection interface
274
public interface MetricsCollector {
275
    void newConnection(Connection connection);
276
    void closeConnection(Connection connection);
277
    void newChannel(Channel channel);
278
    void closeChannel(Channel channel);
279
    void basicPublish(Channel channel);
280
    void basicConsume(Channel channel, String queue, boolean autoAck);
281
}
282
```
283

284
[Observability](./observability.md)
285

286
## Types
287

288
### Core Data Types
289

290
```java { .api }
291
// Message delivery information
292
public class Delivery {
293
    public Envelope getEnvelope();
294
    public AMQP.BasicProperties getProperties();
295
    public byte[] getBody();
296
}
297

298
// Envelope contains routing information
299
public class Envelope {
300
    public long getDeliveryTag();
301
    public boolean isRedeliver();
302
    public String getExchange();
303
    public String getRoutingKey();
304
}
305

306
// Message properties
307
public class AMQP.BasicProperties {
308
    public String getContentType();
309
    public String getContentEncoding();
310
    public Map<String, Object> getHeaders();
311
    public Integer getDeliveryMode();
312
    public Integer getPriority();
313
    public String getCorrelationId();
314
    public String getReplyTo();
315
    public String getExpiration();
316
    public String getMessageId();
317
    public Date getTimestamp();
318
    public String getType();
319
    public String getUserId();
320
    public String getAppId();
321
}
322

323
// Queue information response
324
public class GetResponse {
325
    public Envelope getEnvelope();
326
    public AMQP.BasicProperties getProps();
327
    public byte[] getBody();
328
    public int getMessageCount();
329
}
330

331
// Returned message information
332
public class Return {
333
    public int getReplyCode();
334
    public String getReplyText();
335
    public String getExchange();
336
    public String getRoutingKey();
337
    public AMQP.BasicProperties getProperties();
338
    public byte[] getBody();
339
}
340
```