0
# Spring Boot ActiveMQ Starter
1

2
Spring Boot starter for JMS messaging using Apache ActiveMQ. This starter provides auto-configuration for ActiveMQ connection factories, JMS templates, and essential messaging infrastructure with minimal configuration requirements.
3

4
## Package Information
5

6
- **Package Name**: spring-boot-starter-activemq
7
- **Package Type**: maven
8
- **Language**: Java
9
- **Installation**: Add to your `pom.xml` or `build.gradle`
10

11
Maven:
12
```xml
13
<dependency>
14
  <groupId>org.springframework.boot</groupId>
15
  <artifactId>spring-boot-starter-activemq</artifactId>
16
  <version>3.5.3</version>
17
</dependency>
18
```
19

20
Gradle:
21
```groovy
22
implementation 'org.springframework.boot:spring-boot-starter-activemq:3.5.3'
23
```
24

25
## Core Imports
26

27
```java
28
import org.springframework.boot.autoconfigure.jms.activemq.ActiveMQProperties;
29
import org.springframework.boot.autoconfigure.jms.activemq.ActiveMQConnectionFactoryCustomizer;
30
import org.springframework.boot.autoconfigure.jms.activemq.ActiveMQConnectionDetails;
31
import org.springframework.jms.core.JmsTemplate;
32
import jakarta.jms.ConnectionFactory;
33
```
34

35
## Basic Usage
36

37
```java
38
import org.springframework.boot.SpringApplication;
39
import org.springframework.boot.autoconfigure.SpringBootApplication;
40
import org.springframework.jms.core.JmsTemplate;
41
import org.springframework.stereotype.Component;
42

43
@SpringBootApplication
44
public class ActiveMQApplication {
45
    public static void main(String[] args) {
46
        SpringApplication.run(ActiveMQApplication.class, args);
47
    }
48
}
49

50
@Component
51
public class MessageService {
52
    private final JmsTemplate jmsTemplate;
53
    
54
    public MessageService(JmsTemplate jmsTemplate) {
55
        this.jmsTemplate = jmsTemplate;
56
    }
57
    
58
    public void sendMessage(String destination, String message) {
59
        jmsTemplate.convertAndSend(destination, message);
60
    }
61
    
62
    public String receiveMessage(String destination) {
63
        return (String) jmsTemplate.receiveAndConvert(destination);
64
    }
65
}
66
```
67

68
## Configuration Properties
69

70
Application properties for ActiveMQ configuration:
71

72
```properties
73
# Basic connection settings
74
spring.activemq.broker-url=tcp://localhost:61616
75
spring.activemq.user=admin
76
spring.activemq.password=secret
77

78
# Connection behavior
79
spring.activemq.close-timeout=15s
80
spring.activemq.send-timeout=0ms
81
spring.activemq.non-blocking-redelivery=false
82

83
# Embedded broker settings
84
spring.activemq.embedded.enabled=true
85

86
# Connection pooling
87
spring.activemq.pool.enabled=false
88
spring.activemq.pool.max-connections=1
89
spring.activemq.pool.max-sessions-per-connection=500
90
spring.activemq.pool.idle-timeout=30s
91

92
# Package trust settings
93
spring.activemq.packages.trust-all=false
94
spring.activemq.packages.trusted=com.example.messages
95
```
96

97
## Capabilities
98

99
### ActiveMQ Configuration Properties
100

101
Centralized configuration for ActiveMQ connection settings and broker behavior.
102

103
```java { .api }
104
@ConfigurationProperties("spring.activemq")
105
public class ActiveMQProperties {
106
    
107
    /** URL of the ActiveMQ broker. Auto-generated by default. */
108
    public String getBrokerUrl();
109
    public void setBrokerUrl(String brokerUrl);
110
    
111
    /** Login user of the broker. */
112
    public String getUser();
113
    public void setUser(String user);
114
    
115
    /** Login password of the broker. */
116
    public String getPassword();
117
    public void setPassword(String password);
118
    
119
    /** Time to wait before considering a close complete. Default: 15s */
120
    public Duration getCloseTimeout();
121
    public void setCloseTimeout(Duration closeTimeout);
122
    
123
    /** Whether to stop message delivery before re-delivering messages from rolled back transaction. Default: false */
124
    public boolean isNonBlockingRedelivery();
125
    public void setNonBlockingRedelivery(boolean nonBlockingRedelivery);
126
    
127
    /** Time to wait on message sends for a response. Set to 0 to wait forever. Default: 0ms */
128
    public Duration getSendTimeout();
129
    public void setSendTimeout(Duration sendTimeout);
130
    
131
    /** Embedded broker configuration */
132
    public Embedded getEmbedded();
133
    
134
    /** Connection pool configuration */
135
    public JmsPoolConnectionFactoryProperties getPool();
136
    
137
    /** Package trust configuration */
138
    public Packages getPackages();
139
    
140
    /** Determines effective broker URL based on configuration and embedded settings */
141
    String determineBrokerUrl();
142
    
143
    /** Configuration for embedded ActiveMQ broker */
144
    public static class Embedded {
145
        /** Whether to enable embedded mode if ActiveMQ Broker is available. Default: true */
146
        public boolean isEnabled();
147
        public void setEnabled(boolean enabled);
148
    }
149
    
150
    /** Configuration for package trust settings */
151
    public static class Packages {
152
        /** Whether to trust all packages */
153
        public Boolean getTrustAll();
154
        public void setTrustAll(Boolean trustAll);
155
        
156
        /** List of specific packages to trust when not trusting all packages */
157
        public List<String> getTrusted();
158
        public void setTrusted(List<String> trusted);
159
    }
160
}
161
```
162

163
### Connection Details Interface
164

165
Interface providing connection details for ActiveMQ service connections.
166

167
```java { .api }
168
public interface ActiveMQConnectionDetails extends ConnectionDetails {
169
    
170
    /** Broker URL to use */
171
    String getBrokerUrl();
172
    
173
    /** Login user to authenticate to the broker, or null */
174
    String getUser();
175
    
176
    /** Login password to authenticate against the broker, or null */
177
    String getPassword();
178
}
179
```
180

181
### Connection Factory Customization
182

183
Interface for customizing ActiveMQ connection factories while retaining auto-configuration.
184

185
```java { .api }
186
@FunctionalInterface
187
public interface ActiveMQConnectionFactoryCustomizer {
188
    
189
    /**
190
     * Customize the ActiveMQConnectionFactory
191
     * @param factory the factory to customize
192
     */
193
    void customize(ActiveMQConnectionFactory factory);
194
}
195
```
196

197
### Auto-Configuration Classes
198

199
#### ActiveMQ Auto-Configuration
200

201
Primary auto-configuration class that enables ActiveMQ integration.
202

203
```java { .api }
204
@AutoConfiguration(before = JmsAutoConfiguration.class, after = JndiConnectionFactoryAutoConfiguration.class)
205
@ConditionalOnClass({ConnectionFactory.class, ActiveMQConnectionFactory.class})
206
@ConditionalOnMissingBean(ConnectionFactory.class)
207
@EnableConfigurationProperties({ActiveMQProperties.class, JmsProperties.class})
208
@Import({ActiveMQXAConnectionFactoryConfiguration.class, ActiveMQConnectionFactoryConfiguration.class})
209
public class ActiveMQAutoConfiguration {
210
    
211
    /** Creates ActiveMQConnectionDetails bean from properties */
212
    @Bean
213
    @ConditionalOnMissingBean
214
    ActiveMQConnectionDetails activemqConnectionDetails(ActiveMQProperties properties);
215
}
216
```
217

218
#### Connection Factory Configuration
219

220
Configuration for ActiveMQ ConnectionFactory instances with support for simple, cached, and pooled connections.
221

222
```java { .api }
223
@Configuration(proxyBeanMethods = false)
224
@ConditionalOnMissingBean(ConnectionFactory.class)
225
class ActiveMQConnectionFactoryConfiguration {
226
    
227
    /** Simple connection factory configuration (default) */
228
    static class SimpleConnectionFactoryConfiguration {
229
        
230
        /** Creates non-cached ActiveMQConnectionFactory */
231
        @Bean
232
        @ConditionalOnBooleanProperty(name = "spring.jms.cache.enabled", havingValue = false)
233
        ActiveMQConnectionFactory jmsConnectionFactory(
234
            ActiveMQProperties properties,
235
            ObjectProvider<ActiveMQConnectionFactoryCustomizer> factoryCustomizers,
236
            ActiveMQConnectionDetails connectionDetails
237
        );
238
        
239
        /** Cached connection factory configuration */
240
        static class CachingConnectionFactoryConfiguration {
241
            
242
            /** Creates cached ActiveMQConnectionFactory */
243
            @Bean
244
            CachingConnectionFactory jmsConnectionFactory(
245
                JmsProperties jmsProperties,
246
                ActiveMQProperties properties,
247
                ObjectProvider<ActiveMQConnectionFactoryCustomizer> factoryCustomizers,
248
                ActiveMQConnectionDetails connectionDetails
249
            );
250
        }
251
    }
252
    
253
    /** Pooled connection factory configuration */
254
    static class PooledConnectionFactoryConfiguration {
255
        
256
        /** Creates pooled JmsConnectionFactory */
257
        @Bean(destroyMethod = "stop")
258
        @ConditionalOnBooleanProperty("spring.activemq.pool.enabled")
259
        JmsPoolConnectionFactory jmsConnectionFactory(
260
            ActiveMQProperties properties,
261
            ObjectProvider<ActiveMQConnectionFactoryCustomizer> factoryCustomizers,
262
            ActiveMQConnectionDetails connectionDetails
263
        );
264
    }
265
}
266
```
267

268
#### XA Connection Factory Configuration
269

270
Configuration for ActiveMQ XA (distributed transaction) ConnectionFactory support.
271

272
```java { .api }
273
@Configuration(proxyBeanMethods = false)
274
@ConditionalOnClass(TransactionManager.class)
275
@ConditionalOnBean(XAConnectionFactoryWrapper.class)
276
@ConditionalOnMissingBean(ConnectionFactory.class)
277
class ActiveMQXAConnectionFactoryConfiguration {
278
    
279
    /** Creates XA-capable JMS connection factory */
280
    @Primary
281
    @Bean(name = {"jmsConnectionFactory", "xaJmsConnectionFactory"})
282
    ConnectionFactory jmsConnectionFactory(
283
        ActiveMQProperties properties,
284
        ObjectProvider<ActiveMQConnectionFactoryCustomizer> factoryCustomizers,
285
        XAConnectionFactoryWrapper wrapper,
286
        ActiveMQConnectionDetails connectionDetails
287
    ) throws Exception;
288
    
289
    /** Creates non-XA connection factory for non-transactional operations */
290
    @Bean
291
    @ConditionalOnBooleanProperty(name = "spring.activemq.pool.enabled", havingValue = false, matchIfMissing = true)
292
    ActiveMQConnectionFactory nonXaJmsConnectionFactory(
293
        ActiveMQProperties properties,
294
        ObjectProvider<ActiveMQConnectionFactoryCustomizer> factoryCustomizers,
295
        ActiveMQConnectionDetails connectionDetails
296
    );
297
}
298
```
299

300
### Connection Factory Configurer
301

302
Internal class that configures ActiveMQ connection factories from properties and customizers.
303

304
```java { .api }
305
class ActiveMQConnectionFactoryConfigurer {
306
    
307
    /**
308
     * Create a configurer instance
309
     * @param properties the ActiveMQ properties
310
     * @param factoryCustomizers list of connection factory customizers
311
     */
312
    ActiveMQConnectionFactoryConfigurer(
313
        ActiveMQProperties properties,
314
        List<ActiveMQConnectionFactoryCustomizer> factoryCustomizers
315
    );
316
    
317
    /**
318
     * Configure the given ActiveMQ connection factory
319
     * @param factory the factory to configure
320
     */
321
    void configure(ActiveMQConnectionFactory factory);
322
}
323
```
324

325
### Connection Pool Factory
326

327
Factory for creating pooled JMS connection factories.
328

329
```java { .api }
330
public class JmsPoolConnectionFactoryFactory {
331
    
332
    /**
333
     * Create a factory instance
334
     * @param properties the pool connection factory properties
335
     */
336
    public JmsPoolConnectionFactoryFactory(JmsPoolConnectionFactoryProperties properties);
337
    
338
    /**
339
     * Create a pooled connection factory based on the specified connection factory
340
     * @param connectionFactory the connection factory to wrap
341
     * @return a pooled connection factory
342
     */
343
    public JmsPoolConnectionFactory createPooledConnectionFactory(ConnectionFactory connectionFactory);
344
}
345
```
346

347
## Usage Examples
348

349
### Custom Connection Factory Configuration
350

351
```java
352
@Configuration
353
public class ActiveMQConfig {
354
    
355
    @Bean
356
    public ActiveMQConnectionFactoryCustomizer connectionFactoryCustomizer() {
357
        return factory -> {
358
            factory.setTrustedPackages(Arrays.asList("com.example.messages"));
359
            factory.setCloseTimeout(5000);
360
            factory.setOptimizeAcknowledge(true);
361
        };
362
    }
363
}
364
```
365

366
### Message Producer and Consumer
367

368
```java
369
@Component
370
public class OrderService {
371
    
372
    private final JmsTemplate jmsTemplate;
373
    
374
    public OrderService(JmsTemplate jmsTemplate) {
375
        this.jmsTemplate = jmsTemplate;
376
    }
377
    
378
    public void processOrder(Order order) {
379
        // Send order to processing queue
380
        jmsTemplate.convertAndSend("orders.processing", order);
381
    }
382
    
383
    @JmsListener(destination = "orders.completed")
384
    public void handleCompletedOrder(Order order) {
385
        // Handle completed order
386
        System.out.println("Order completed: " + order.getId());
387
    }
388
}
389
```
390

391
### Connection Pool Configuration
392

393
For high-throughput applications, enable connection pooling:
394

395
```properties
396
spring.activemq.pool.enabled=true
397
spring.activemq.pool.max-connections=10
398
spring.activemq.pool.max-sessions-per-connection=100
399
spring.activemq.pool.idle-timeout=30s
400
```
401

402
### Embedded Broker Configuration
403

404
For development and testing, use embedded ActiveMQ:
405

406
```properties
407
spring.activemq.embedded.enabled=true
408
# Embedded broker uses vm://localhost by default
409
```
410

411
### External Broker Configuration
412

413
For production, configure external ActiveMQ broker:
414

415
```properties
416
spring.activemq.broker-url=tcp://activemq.production.com:61616
417
spring.activemq.user=myapp
418
spring.activemq.password=${ACTIVEMQ_PASSWORD}
419
spring.activemq.embedded.enabled=false
420

421
# Connection pooling for production
422
spring.activemq.pool.enabled=true
423
spring.activemq.pool.max-connections=20
424
```
425

426
## Types
427

428
```java { .api }
429
/** Standard Java types */
430
import java.time.Duration;
431
import java.util.List;
432
import jakarta.jms.Connection;
433
import jakarta.jms.JMSException;
434
import jakarta.jms.XAConnection;
435
import jakarta.jms.XAConnectionFactory;
436
import jakarta.transaction.TransactionManager;
437
import org.springframework.boot.autoconfigure.service.connection.ConnectionDetails;
438
import org.springframework.boot.jms.XAConnectionFactoryWrapper;
439

440
/** Standard Jakarta JMS types */
441
interface ConnectionFactory {
442
    Connection createConnection() throws JMSException;
443
    Connection createConnection(String userName, String password) throws JMSException;
444
}
445

446
/** Apache ActiveMQ connection factory */
447
class ActiveMQConnectionFactory implements ConnectionFactory {
448
    public ActiveMQConnectionFactory();
449
    public ActiveMQConnectionFactory(String brokerURL);
450
    public ActiveMQConnectionFactory(String userName, String password, String brokerURL);
451
    
452
    public void setBrokerURL(String brokerURL);
453
    public void setUserName(String userName);
454
    public void setPassword(String password);
455
    public void setCloseTimeout(int closeTimeout);
456
    public void setNonBlockingRedelivery(boolean nonBlockingRedelivery);
457
    public void setSendTimeout(int sendTimeout);
458
    public void setTrustedPackages(List<String> trustedPackages);
459
    public void setTrustAllPackages(boolean trustAllPackages);
460
}
461

462
/** Apache ActiveMQ XA connection factory */
463
class ActiveMQXAConnectionFactory extends ActiveMQConnectionFactory implements XAConnectionFactory {
464
    public XAConnection createXAConnection() throws JMSException;
465
    public XAConnection createXAConnection(String userName, String password) throws JMSException;
466
}
467

468
/** Spring JMS cached connection factory */
469
class CachingConnectionFactory implements ConnectionFactory {
470
    public void setCacheConsumers(boolean cacheConsumers);
471
    public void setCacheProducers(boolean cacheProducers);
472
    public void setSessionCacheSize(int sessionCacheSize);
473
}
474

475
/** Pooled JMS connection factory */
476
class JmsPoolConnectionFactory implements ConnectionFactory {
477
    public void setMaxConnections(int maxConnections);
478
    public void setIdleTimeout(Duration idleTimeout);
479
    public void setMaxSessionsPerConnection(int maxSessionsPerConnection);
480
    public void stop();
481
}
482

483
/** Configuration properties for connection factory pooling */
484
class JmsPoolConnectionFactoryProperties {
485
    /** Whether a JmsPoolConnectionFactory should be created instead of regular ConnectionFactory */
486
    public boolean isEnabled();
487
    public void setEnabled(boolean enabled);
488
    
489
    /** Whether to block when connection requested and pool is full */
490
    public boolean isBlockIfFull();
491
    public void setBlockIfFull(boolean blockIfFull);
492
    
493
    /** Blocking period before throwing exception if pool still full */
494
    public Duration getBlockIfFullTimeout();
495
    public void setBlockIfFullTimeout(Duration blockIfFullTimeout);
496
    
497
    /** Connection idle timeout */
498
    public Duration getIdleTimeout();
499
    public void setIdleTimeout(Duration idleTimeout);
500
    
501
    /** Maximum number of pooled connections */
502
    public int getMaxConnections();
503
    public void setMaxConnections(int maxConnections);
504
    
505
    /** Maximum number of pooled sessions per connection */
506
    public int getMaxSessionsPerConnection();
507
    public void setMaxSessionsPerConnection(int maxSessionsPerConnection);
508
    
509
    /** Time between idle connection eviction thread runs */
510
    public Duration getTimeBetweenExpirationCheck();
511
    public void setTimeBetweenExpirationCheck(Duration timeBetweenExpirationCheck);
512
    
513
    /** Whether to use only one anonymous MessageProducer instance */
514
    public boolean isUseAnonymousProducers();
515
    public void setUseAnonymousProducers(boolean useAnonymousProducers);
516
}
517
```