0
# Service Connection API
1

2
Spring Boot's Service Connection API provides a standardized way to define and access connection details for external services. Introduced in Spring Boot 3.1.0, it enables consistent configuration patterns across different service integrations and supports various connection sources including properties, container environments, and cloud platforms.
3

4
## Capabilities
5

6
### Core Connection Interfaces
7

8
Base interfaces that define the service connection contract.
9

10
```java { .api }
11
/**
12
 * Base interface for types that provide connection details to remote services
13
 * Implementation classes can also implement OriginProvider for origin information
14
 */
15
public interface ConnectionDetails {
16
    // Marker interface - specific implementations provide actual connection details
17
}
18

19
/**
20
 * Factory to create ConnectionDetails from a given source
21
 * Implementations should be registered in META-INF/spring.factories
22
 */
23
public interface ConnectionDetailsFactory<S, D extends ConnectionDetails> {
24
    /**
25
     * Get ConnectionDetails from the given source
26
     * @param source the source
27
     * @return the connection details or null
28
     */
29
    D getConnectionDetails(S source);
30
}
31

32
/**
33
 * Utility for finding and creating ConnectionDetails
34
 */
35
public final class ConnectionDetailsFactories {
36
    /**
37
     * Get ConnectionDetails for the given source
38
     * @param source the source
39
     * @return the connection details
40
     * @throws ConnectionDetailsNotFoundException if no details found
41
     */
42
    public static <T extends ConnectionDetails> T getConnectionDetails(Object source);
43
}
44
```
45

46
### Database Connection Details
47

48
Connection details for database services including JDBC data sources and connection pooling.
49

50
```java { .api }
51
/**
52
 * Details required to establish a connection to a JDBC database
53
 */
54
public interface JdbcConnectionDetails extends ConnectionDetails {
55
    /**
56
     * JDBC URL for the database connection
57
     * @return the JDBC URL
58
     */
59
    String getJdbcUrl();
60
    
61
    /**
62
     * Username for database authentication
63
     * @return the username or null
64
     */
65
    default String getUsername() { return null; }
66
    
67
    /**
68
     * Password for database authentication  
69
     * @return the password or null
70
     */
71
    default String getPassword() { return null; }
72
    
73
    /**
74
     * JDBC driver class name
75
     * @return the driver class name or null
76
     */
77
    default String getDriverClassName() { return null; }
78
    
79
    /**
80
     * XA data source class name for distributed transactions
81
     * @return the XA data source class name or null
82
     */
83
    default String getXaDataSourceClassName() { return null; }
84
}
85

86
/**
87
 * Details required for Flyway database migration connections
88
 */
89
public interface FlywayConnectionDetails extends ConnectionDetails {
90
    /**
91
     * JDBC URL for Flyway migrations
92
     * @return the JDBC URL
93
     */
94
    String getJdbcUrl();
95
    
96
    /**
97
     * Username for Flyway database authentication
98
     * @return the username or null
99
     */
100
    default String getUsername() { return null; }
101
    
102
    /**
103
     * Password for Flyway database authentication
104
     * @return the password or null
105
     */
106
    default String getPassword() { return null; }
107
}
108
```
109

110
### Messaging Connection Details
111

112
Connection details for messaging systems including RabbitMQ, Apache Kafka, JMS providers, and Apache Pulsar.
113

114
```java { .api }
115
/**
116
 * Details required to establish a connection to a RabbitMQ service
117
 */
118
public interface RabbitConnectionDetails extends ConnectionDetails {
119
    /**
120
     * Login user to authenticate to the broker
121
     * @return the login user or null
122
     */
123
    default String getUsername() { return null; }
124
    
125
    /**
126
     * Login password to authenticate against the broker
127
     * @return the password or null
128
     */
129
    default String getPassword() { return null; }
130
    
131
    /**
132
     * Virtual host to use when connecting to the broker
133
     * @return the virtual host or null
134
     */
135
    default String getVirtualHost() { return null; }
136
    
137
    /**
138
     * List of addresses to which the client should connect
139
     * @return the list of addresses (must contain at least one)
140
     */
141
    List<Address> getAddresses();
142
    
143
    /**
144
     * Returns the first address
145
     * @return the first address
146
     * @throws IllegalStateException if address list is empty
147
     */
148
    default Address getFirstAddress();
149
    
150
    /**
151
     * SSL bundle to use for secure connections
152
     * @return the SSL bundle or null
153
     */
154
    default SslBundle getSslBundle() { return null; }
155
    
156
    /**
157
     * A RabbitMQ address containing host and port
158
     */
159
    record Address(String host, int port) {}
160
}
161

162
/**
163
 * Details required to establish a connection to Apache Kafka
164
 */
165
public interface KafkaConnectionDetails extends ConnectionDetails {
166
    /**
167
     * List of Kafka bootstrap server addresses
168
     * @return the bootstrap servers list
169
     */
170
    List<String> getBootstrapServers();
171
    
172
    /**
173
     * Consumer group ID for Kafka consumers
174
     * @return the consumer group ID or null
175
     */
176
    default String getConsumerGroupId() { return null; }
177
    
178
    /**
179
     * Streams application ID for Kafka Streams
180
     * @return the streams application ID or null
181
     */
182
    default String getStreamsApplicationId() { return null; }
183
}
184

185
/**
186
 * Details required to establish a connection to ActiveMQ
187
 */
188
public interface ActiveMQConnectionDetails extends ConnectionDetails {
189
    /**
190
     * ActiveMQ broker URL
191
     * @return the broker URL
192
     */
193
    String getBrokerUrl();
194
    
195
    /**
196
     * Username for broker authentication
197
     * @return the username or null
198
     */
199
    default String getUser() { return null; }
200
    
201
    /**
202
     * Password for broker authentication
203
     * @return the password or null
204
     */
205
    default String getPassword() { return null; }
206
}
207

208
/**
209
 * Details required to establish a connection to Apache Pulsar
210
 */
211
public interface PulsarConnectionDetails extends ConnectionDetails {
212
    /**
213
     * Pulsar service URL
214
     * @return the service URL
215
     */
216
    String getServiceUrl();
217
    
218
    /**
219
     * Pulsar admin service URL
220
     * @return the admin service URL
221
     */
222
    String getAdminUrl();
223
}
224
```
225

226
### NoSQL Connection Details
227

228
Connection details for NoSQL databases including Redis, MongoDB, Cassandra, and Couchbase.
229

230
```java { .api }
231
/**
232
 * Details required to establish a connection to a Redis server
233
 */
234
public interface RedisConnectionDetails extends ConnectionDetails {
235
    /**
236
     * Get the Redis standalone configuration
237
     * @return the standalone configuration or null
238
     */
239
    default Standalone getStandalone() { return null; }
240
    
241
    /**
242
     * Get the Redis Sentinel configuration
243
     * @return the sentinel configuration or null
244
     */
245
    default Sentinel getSentinel() { return null; }
246
    
247
    /**
248
     * Get the Redis Cluster configuration
249
     * @return the cluster configuration or null
250
     */
251
    default Cluster getCluster() { return null; }
252
    
253
    /**
254
     * Username for Redis authentication
255
     * @return the username or null
256
     */
257
    default String getUsername() { return null; }
258
    
259
    /**
260
     * Password for Redis authentication
261
     * @return the password or null
262
     */
263
    default String getPassword() { return null; }
264
    
265
    /**
266
     * Redis database index
267
     * @return the database index
268
     */
269
    default int getDatabase() { return 0; }
270
    
271
    /**
272
     * Redis standalone server configuration
273
     */
274
    interface Standalone {
275
        String getHost();
276
        int getPort();
277
    }
278
    
279
    /**
280
     * Redis Sentinel configuration
281
     */
282
    interface Sentinel {
283
        String getMaster();
284
        List<Node> getNodes();
285
        String getPassword();
286
    }
287
    
288
    /**
289
     * Redis Cluster configuration
290
     */
291
    interface Cluster {
292
        List<Node> getNodes();
293
    }
294
    
295
    /**
296
     * A Redis node with host and port
297
     */
298
    record Node(String host, int port) {}
299
}
300

301
/**
302
 * Details required to establish a connection to MongoDB
303
 */
304
public interface MongoConnectionDetails extends ConnectionDetails {
305
    /**
306
     * MongoDB connection string
307
     * @return the connection string
308
     */
309
    String getConnectionString();
310
    
311
    /**
312
     * GridFS database name
313
     * @return the GridFS database name or null
314
     */
315
    default String getGridFsDatabase() { return null; }
316
}
317

318
/**
319
 * Details required to establish a connection to Couchbase
320
 */
321
public interface CouchbaseConnectionDetails extends ConnectionDetails {
322
    /**
323
     * Couchbase connection string
324
     * @return the connection string
325
     */
326
    String getConnectionString();
327
    
328
    /**
329
     * Username for Couchbase authentication
330
     * @return the username
331
     */
332
    String getUsername();
333
    
334
    /**
335
     * Password for Couchbase authentication
336
     * @return the password
337
     */
338
    String getPassword();
339
}
340
```
341

342
### Cache Connection Details
343

344
Connection details for caching providers.
345

346
```java { .api }
347
/**
348
 * Details required to establish a connection to Hazelcast
349
 */
350
public interface HazelcastConnectionDetails extends ConnectionDetails {
351
    /**
352
     * Hazelcast network configuration
353
     * @return the network configuration
354
     */
355
    Network getNetwork();
356
    
357
    /**
358
     * Hazelcast network configuration
359
     */
360
    interface Network {
361
        /**
362
         * List of Hazelcast member addresses
363
         * @return the member addresses
364
         */
365
        List<String> getAddresses();
366
    }
367
}
368
```
369

370
## Usage Examples
371

372
### Using Connection Details in Auto-Configuration
373

374
```java
375
@AutoConfiguration
376
@ConditionalOnClass(DataSource.class)
377
public class DataSourceAutoConfiguration {
378
    
379
    @Bean
380
    @ConditionalOnMissingBean
381
    public DataSource dataSource(JdbcConnectionDetails connectionDetails) {
382
        HikariDataSource dataSource = new HikariDataSource();
383
        dataSource.setJdbcUrl(connectionDetails.getJdbcUrl());
384
        dataSource.setUsername(connectionDetails.getUsername());
385
        dataSource.setPassword(connectionDetails.getPassword());
386
        if (connectionDetails.getDriverClassName() != null) {
387
            dataSource.setDriverClassName(connectionDetails.getDriverClassName());
388
        }
389
        return dataSource;
390
    }
391
}
392
```
393

394
### Creating Custom Connection Details
395

396
```java
397
@Component
398
public class CustomDatabaseConnectionDetails implements JdbcConnectionDetails {
399
    
400
    @Override
401
    public String getJdbcUrl() {
402
        return "jdbc:postgresql://localhost:5432/mydb";
403
    }
404
    
405
    @Override
406
    public String getUsername() {
407
        return "myuser";
408
    }
409
    
410
    @Override
411
    public String getPassword() {
412
        return "mypassword";
413
    }
414
    
415
    @Override
416
    public String getDriverClassName() {
417
        return "org.postgresql.Driver";
418
    }
419
}
420
```
421

422
### Property-Based Connection Details
423

424
```java
425
@ConfigurationProperties(prefix = "app.redis")
426
public class PropertiesRedisConnectionDetails implements RedisConnectionDetails {
427
    
428
    private String host = "localhost";
429
    private int port = 6379;
430
    private String password;
431
    private int database = 0;
432
    
433
    @Override
434
    public Standalone getStandalone() {
435
        return () -> new Standalone() {
436
            @Override
437
            public String getHost() { return host; }
438
            
439
            @Override  
440
            public int getPort() { return port; }
441
        };
442
    }
443
    
444
    @Override
445
    public String getPassword() {
446
        return password;
447
    }
448
    
449
    @Override
450
    public int getDatabase() {
451
        return database;
452
    }
453
    
454
    // Getters and setters for configuration properties
455
}
456
```
457

458
### Connection Details Factory
459

460
```java
461
public class DockerComposeRedisConnectionDetailsFactory 
462
        implements ConnectionDetailsFactory<DockerComposeService, RedisConnectionDetails> {
463
    
464
    @Override
465
    public RedisConnectionDetails getConnectionDetails(DockerComposeService source) {
466
        if (!"redis".equals(source.getName())) {
467
            return null;
468
        }
469
        
470
        return new RedisConnectionDetails() {
471
            @Override
472
            public Standalone getStandalone() {
473
                return new Standalone() {
474
                    @Override
475
                    public String getHost() {
476
                        return source.getHost();
477
                    }
478
                    
479
                    @Override
480
                    public int getPort() {
481
                        return source.getMappedPort(6379);
482
                    }
483
                };
484
            }
485
        };
486
    }
487
}
488
```