0
# Configuration
1

2
Configuration classes for connection parameters, addressing, authentication, SSL settings, and advanced connection options. These classes provide comprehensive control over how the client connects to and communicates with RabbitMQ brokers.
3

4
## Capabilities
5

6
### Address Resolution
7

8
Classes for specifying and resolving broker addresses, including support for load balancing and high availability.
9

10
```java { .api }
11
/**
12
 * Represents a broker address with host and port
13
 */
14
public class Address {
15
    /**
16
     * Create an Address with host and port
17
     * @param host - Hostname or IP address
18
     * @param port - Port number
19
     */
20
    public Address(String host, int port);
21
    
22
    /**
23
     * Create an Address with host and default port
24
     * @param host - Hostname or IP address
25
     */
26
    public Address(String host);
27
    
28
    /**
29
     * Parse comma-separated list of addresses
30
     * @param addresses - String like "host1:5672,host2:5672,host3"
31
     * @return Array of Address objects
32
     */
33
    public static Address[] parseAddresses(String addresses) throws IOException;
34
    
35
    /**
36
     * Create single Address from string
37
     * @param addressString - Format "host:port" or "host"
38
     * @return Address object
39
     */
40
    public static Address valueOf(String addressString);
41
    
42
    public String getHost();
43
    public int getPort();
44
    
45
    // Standard constants
46
    public static final int USE_DEFAULT_PORT = -1;
47
}
48

49
/**
50
 * Interface for resolving broker addresses dynamically
51
 */
52
public interface AddressResolver {
53
    /**
54
     * Get list of addresses to connect to
55
     * @return List of broker addresses
56
     */
57
    List<Address> getAddresses() throws IOException;
58
}
59

60
/**
61
 * Address resolver using a static list of addresses
62
 */
63
public class ListAddressResolver implements AddressResolver {
64
    /**
65
     * Create resolver with list of addresses
66
     * @param addresses - List of broker addresses
67
     */
68
    public ListAddressResolver(List<Address> addresses);
69
    
70
    /**
71
     * Create resolver from address array
72
     * @param addresses - Array of broker addresses
73
     */
74
    public ListAddressResolver(Address[] addresses);
75
    
76
    public List<Address> getAddresses();
77
}
78

79
/**
80
 * Address resolver using DNS SRV records
81
 */
82
public class DnsSrvRecordAddressResolver implements AddressResolver {
83
    /**
84
     * Create DNS SRV resolver
85
     * @param service - Service name (e.g., "amqp") 
86
     * @param protocol - Protocol (e.g., "tcp")
87
     * @param domain - Domain name
88
     */
89
    public DnsSrvRecordAddressResolver(String service, String protocol, String domain);
90
    
91
    /**
92
     * Create DNS SRV resolver with default AMQP service
93
     * @param domain - Domain name to query
94
     */
95
    public DnsSrvRecordAddressResolver(String domain);
96
    
97
    public List<Address> getAddresses() throws IOException;
98
}
99

100
/**
101
 * Resolves IP addresses from DNS records
102
 */
103
public class DnsRecordIpAddressResolver {
104
    /**
105
     * Create IP address resolver
106
     * @param hostname - Hostname to resolve
107
     * @param port - Port to use for resolved addresses
108
     */
109
    public DnsRecordIpAddressResolver(String hostname, int port);
110
    
111
    /**
112
     * Resolve hostname to list of IP addresses
113
     * @return List of resolved addresses
114
     */
115
    public List<Address> getAddresses() throws IOException;
116
}
117
```
118

119
**Usage Examples:**
120

121
```java
122
// Static address configuration
123
Address[] addresses = Address.parseAddresses("broker1:5672,broker2:5672,broker3:5672");
124
ConnectionFactory factory = new ConnectionFactory();
125
Connection connection = factory.newConnection(addresses);
126
```
127

128
```java
129
// Using address resolver for high availability
130
List<Address> brokerList = Arrays.asList(
131
    new Address("primary.rabbitmq.com", 5672),
132
    new Address("secondary.rabbitmq.com", 5672),
133
    new Address("tertiary.rabbitmq.com", 5672)
134
);
135

136
AddressResolver resolver = new ListAddressResolver(brokerList);
137
ConnectionFactory factory = new ConnectionFactory();
138
Connection connection = factory.newConnection(resolver);
139
```
140

141
```java
142
// DNS-based service discovery
143
AddressResolver dnsResolver = new DnsSrvRecordAddressResolver("amqp", "tcp", "rabbitmq.example.com");
144
ConnectionFactory factory = new ConnectionFactory();
145
Connection connection = factory.newConnection(dnsResolver);
146
```
147

148
### Authentication Configuration
149

150
SASL-based authentication configuration for various authentication mechanisms.
151

152
```java { .api }
153
/**
154
 * Interface for SASL authentication configuration
155
 */
156
public interface SaslConfig {
157
    /**
158
     * Get SASL mechanism for given server mechanisms
159
     * @param serverMechanisms - Array of server-supported mechanisms
160
     * @return SaslMechanism to use, or null if none suitable
161
     */
162
    SaslMechanism getSaslMechanism(String[] serverMechanisms);
163
}
164

165
/**
166
 * Interface for SASL authentication mechanisms
167
 */
168
public interface SaslMechanism {
169
    /**
170
     * Get the name of this SASL mechanism
171
     * @return Mechanism name (e.g., "PLAIN", "EXTERNAL")
172
     */
173
    String getName();
174
    
175
    /**
176
     * Handle authentication challenge from server
177
     * @param challenge - Challenge data from server
178
     * @param username - Username for authentication
179
     * @param password - Password for authentication  
180
     * @return Response data to send to server
181
     */
182
    byte[] handleChallenge(byte[] challenge, String username, String password);
183
}
184

185
/**
186
 * Default SASL configuration supporting PLAIN and AMQPLAIN
187
 */
188
public class DefaultSaslConfig implements SaslConfig {
189
    /**
190
     * Create default SASL config
191
     */
192
    public DefaultSaslConfig();
193
    
194
    public SaslMechanism getSaslMechanism(String[] serverMechanisms);
195
}
196

197
/**
198
 * JDK-based SASL configuration using Java's SASL framework
199
 */
200
public class JDKSaslConfig implements SaslConfig {
201
    /**
202
     * Create JDK SASL config
203
     */
204
    public JDKSaslConfig();
205
    
206
    public SaslMechanism getSaslMechanism(String[] serverMechanisms);
207
}
208
```
209

210
**Usage Examples:**
211

212
```java
213
// Default authentication (PLAIN/AMQPLAIN)
214
ConnectionFactory factory = new ConnectionFactory();
215
factory.setUsername("user");
216
factory.setPassword("password");
217
factory.setSaslConfig(new DefaultSaslConfig());
218
```
219

220
```java
221
// JDK SASL authentication
222
ConnectionFactory factory = new ConnectionFactory();
223
factory.setUsername("user");
224
factory.setPassword("password");
225
factory.setSaslConfig(new JDKSaslConfig());
226
```
227

228
### SSL/TLS Configuration
229

230
Configuration classes for secure connections using SSL/TLS.
231

232
```java { .api }
233
/**
234
 * Interface for creating SSL contexts
235
 */
236
public interface SslContextFactory {
237
    /**
238
     * Create SSL context for the connection
239
     * @param sniServerName - Server name for SNI (Server Name Indication)
240
     * @return Configured SSLContext
241
     */
242
    SSLContext create(String sniServerName) throws GeneralSecurityException;
243
}
244

245
/**
246
 * Interface for configuring SSL engines
247
 */
248
public interface SslEngineConfigurator {
249
    /**
250
     * Configure an SSL engine
251
     * @param sslEngine - SSL engine to configure
252
     */
253
    void configure(SSLEngine sslEngine) throws SSLException;
254
}
255

256
/**
257
 * Utility class for SSL engine configurators
258
 */
259
public class SslEngineConfigurators {
260
    /**
261
     * Get default SSL engine configurator
262
     * @return Default configurator
263
     */
264
    public static SslEngineConfigurator defaultConfigurator();
265
    
266
    /**
267
     * Create SSL engine configurator builder
268
     * @return Builder for creating custom configurators
269
     */
270
    public static SslEngineConfiguratorBuilder builder();
271
}
272

273
/**
274
 * Trust manager that accepts all certificates (for testing only)
275
 */
276
public class TrustEverythingTrustManager implements X509TrustManager {
277
    public void checkClientTrusted(X509Certificate[] chain, String authType);
278
    public void checkServerTrusted(X509Certificate[] chain, String authType);
279
    public X509Certificate[] getAcceptedIssuers();
280
}
281
```
282

283
**Usage Examples:**
284

285
```java
286
// Basic SSL connection
287
ConnectionFactory factory = new ConnectionFactory();
288
factory.setHost("secure.rabbitmq.com");
289
factory.setPort(5671);
290
factory.useSslProtocol();
291
Connection connection = factory.newConnection();
292
```
293

294
```java
295
// SSL with custom trust store
296
System.setProperty("javax.net.ssl.trustStore", "/path/to/truststore.jks");
297
System.setProperty("javax.net.ssl.trustStorePassword", "password");
298

299
ConnectionFactory factory = new ConnectionFactory();
300
factory.setHost("secure.rabbitmq.com");
301
factory.setPort(5671);
302
factory.useSslProtocol("TLSv1.2");
303
```
304

305
```java
306
// SSL with custom SSL context
307
SSLContext sslContext = SSLContext.getInstance("TLSv1.2");
308
// ... configure sslContext with key managers, trust managers, etc.
309

310
ConnectionFactory factory = new ConnectionFactory();
311
factory.setHost("secure.rabbitmq.com");
312
factory.setPort(5671);
313
factory.useSslProtocol(sslContext);
314
```
315

316
### Socket Configuration
317

318
Configuration interfaces for customizing socket behavior and NIO channels.
319

320
```java { .api }
321
/**
322
 * Interface for configuring sockets
323
 */
324
public interface SocketConfigurator {
325
    /**
326
     * Configure a socket before use
327
     * @param socket - Socket to configure
328
     */
329
    void configure(Socket socket) throws IOException;
330
}
331

332
/**
333
 * Default socket configurator with standard settings
334
 */
335
public class DefaultSocketConfigurator implements SocketConfigurator {
336
    public void configure(Socket socket) throws IOException;
337
}
338

339
/**
340
 * Interface for configuring NIO socket channels  
341
 */
342
public interface SocketChannelConfigurator {
343
    /**
344
     * Configure a socket channel before use
345
     * @param channel - SocketChannel to configure
346
     */
347
    void configure(SocketChannel channel) throws IOException;
348
}
349

350
/**
351
 * Default socket channel configurator
352
 */
353
public class DefaultSocketChannelConfigurator implements SocketChannelConfigurator {
354
    public void configure(SocketChannel channel) throws IOException;
355
}
356

357
/**
358
 * Utility class for socket configurators
359
 */
360
public class SocketConfigurators {
361
    /**
362
     * Get default socket configurator
363
     * @return Default configurator
364
     */
365
    public static SocketConfigurator defaultConfigurator();
366
    
367
    /**
368
     * Create socket configurator builder
369
     * @return Builder for creating custom configurators
370
     */
371
    public static SocketConfiguratorBuilder builder();
372
}
373

374
/**
375
 * Utility class for socket channel configurators
376
 */
377
public class SocketChannelConfigurators {
378
    /**
379
     * Get default socket channel configurator
380
     * @return Default configurator
381
     */
382
    public static SocketChannelConfigurator defaultConfigurator();
383
    
384
    /**
385
     * Create socket channel configurator builder
386
     * @return Builder for creating custom configurators
387
     */
388
    public static SocketChannelConfiguratorBuilder builder();
389
}
390
```
391

392
**Usage Examples:**
393

394
```java
395
// Custom socket configuration
396
SocketConfigurator socketConfig = socket -> {
397
    socket.setTcpNoDelay(true);
398
    socket.setSoTimeout(30000);
399
    socket.setKeepAlive(true);
400
    socket.setSendBufferSize(64 * 1024);
401
    socket.setReceiveBufferSize(64 * 1024);
402
};
403

404
ConnectionFactory factory = new ConnectionFactory();
405
factory.setSocketConfigurator(socketConfig);
406
```
407

408
```java
409
// Using socket configurator builder
410
SocketConfigurator configurator = SocketConfigurators.builder()
411
    .tcpNoDelay(true)
412
    .keepAlive(true)
413
    .sendBufferSize(128 * 1024)
414
    .receiveBufferSize(128 * 1024)
415
    .soTimeout(60000)
416
    .build();
417

418
ConnectionFactory factory = new ConnectionFactory();
419
factory.setSocketConfigurator(configurator);
420
```
421

422
### Connection Factory Configuration Helper
423

424
Utility class for configuring ConnectionFactory from properties or environment variables.
425

426
```java { .api }
427
/**
428
 * Utility for configuring ConnectionFactory from external properties
429
 */
430
public class ConnectionFactoryConfigurator {
431
    /**
432
     * Configure factory from system properties
433
     * @param connectionFactory - Factory to configure
434
     * @param prefix - Property prefix (e.g., "rabbitmq.")
435
     */
436
    public static void load(ConnectionFactory connectionFactory, String prefix);
437
    
438
    /**
439
     * Configure factory from properties map
440
     * @param connectionFactory - Factory to configure
441
     * @param properties - Properties map
442
     * @param prefix - Property prefix
443
     */
444
    public static void load(ConnectionFactory connectionFactory, Map<String, String> properties, String prefix);
445
    
446
    /**
447
     * Configure factory from Properties object
448
     * @param connectionFactory - Factory to configure
449
     * @param properties - Properties object
450
     * @param prefix - Property prefix
451
     */
452
    public static void load(ConnectionFactory connectionFactory, Properties properties, String prefix);
453
}
454
```
455

456
**Usage Examples:**
457

458
```java
459
// Configure from system properties
460
// Set system properties: -Drabbitmq.host=localhost -Drabbitmq.port=5672
461
ConnectionFactory factory = new ConnectionFactory();
462
ConnectionFactoryConfigurator.load(factory, "rabbitmq.");
463
```
464

465
```java
466
// Configure from properties file
467
Properties props = new Properties();
468
props.load(new FileInputStream("rabbitmq.properties"));
469

470
ConnectionFactory factory = new ConnectionFactory();
471
ConnectionFactoryConfigurator.load(factory, props, "");
472
```
473

474
```java
475
// Configure from environment-like map
476
Map<String, String> config = Map.of(
477
    "rabbitmq.host", "broker.example.com",
478
    "rabbitmq.port", "5672",
479
    "rabbitmq.username", "myuser",
480
    "rabbitmq.password", "mypass",
481
    "rabbitmq.virtualHost", "/prod"
482
);
483

484
ConnectionFactory factory = new ConnectionFactory();
485
ConnectionFactoryConfigurator.load(factory, config, "rabbitmq.");
486
```
487

488
## Types
489

490
### Configuration-Related Types
491

492
```java { .api }
493
// Resolved internet address wrapper
494
public class ResolvedInetAddress {
495
    public InetAddress getAddress();
496
    public String getHostname();
497
}
498

499
// Address information
500
public class Address {
501
    public String getHost();
502
    public int getPort();
503
    public boolean equals(Object obj);
504
    public int hashCode();
505
    public String toString();
506
}
507
```
508

509
### Configuration Examples
510

511
**Complete Connection Setup:**
512

513
```java
514
public ConnectionFactory createProductionConnectionFactory() {
515
    ConnectionFactory factory = new ConnectionFactory();
516
    
517
    // Basic connection settings
518
    factory.setHost("rabbitmq.prod.example.com");
519
    factory.setPort(5671); // SSL port
520
    factory.setUsername("prod-user");
521
    factory.setPassword("secure-password");
522
    factory.setVirtualHost("/production");
523
    
524
    // SSL configuration
525
    factory.useSslProtocol("TLSv1.2");
526
    
527
    // Timeouts and limits
528
    factory.setConnectionTimeout(30000);
529
    factory.setHandshakeTimeout(10000);
530
    factory.setRequestedHeartbeat(30);
531
    factory.setRequestedChannelMax(100);
532
    
533
    // Recovery settings
534
    factory.setAutomaticRecoveryEnabled(true);
535
    factory.setNetworkRecoveryInterval(5000);
536
    
537
    // Socket configuration
538
    SocketConfigurator socketConfig = socket -> {
539
        socket.setTcpNoDelay(true);
540
        socket.setKeepAlive(true);
541
        socket.setSendBufferSize(128 * 1024);
542
        socket.setReceiveBufferSize(128 * 1024);
543
    };
544
    factory.setSocketConfigurator(socketConfig);
545
    
546
    return factory;
547
}
548
```
549

550
**High Availability Setup:**
551

552
```java
553
public Connection createHAConnection() throws IOException, TimeoutException {
554
    // Multiple broker addresses for failover
555
    Address[] addresses = {
556
        new Address("rabbitmq1.example.com", 5672),
557
        new Address("rabbitmq2.example.com", 5672),
558
        new Address("rabbitmq3.example.com", 5672)
559
    };
560
    
561
    ConnectionFactory factory = new ConnectionFactory();
562
    factory.setUsername("ha-user");
563
    factory.setPassword("ha-password");
564
    factory.setAutomaticRecoveryEnabled(true);
565
    factory.setNetworkRecoveryInterval(2000);
566
    
567
    // Connection will try addresses in order until one succeeds
568
    return factory.newConnection(addresses);
569
}
570
```