0
# Embedded Broker
1

2
ActiveMQ provides comprehensive support for embedding message brokers directly within applications. This enables standalone deployments, testing environments, and applications that need to provide messaging services without external broker dependencies.
3

4
## Capabilities
5

6
### Broker Service
7

8
Core broker service implementation for embedding ActiveMQ brokers in applications.
9

10
```java { .api }
11
/**
12
 * Main broker service implementation for embedded brokers
13
 * Provides full broker functionality within applications
14
 */
15
public class BrokerService implements Service {
16
    /** Create new broker service */
17
    public BrokerService();
18
    
19
    /** Start broker service */
20
    public void start() throws Exception;
21
    
22
    /** Stop broker service */
23
    public void stop() throws Exception;
24
    
25
    /** Broker identification */
26
    public void setBrokerName(String brokerName);
27
    public String getBrokerName();
28
    public String getBrokerId();
29
    
30
    /** Transport connectors */
31
    public TransportConnector addConnector(String bindAddress) throws Exception;
32
    public TransportConnector addConnector(URI bindAddress) throws Exception;
33
    public void removeConnector(TransportConnector connector) throws Exception;
34
    public TransportConnector[] getTransportConnectors();
35
    public void setTransportConnectors(List<TransportConnector> transportConnectors) throws Exception;
36
    
37
    /** Network connectors for broker clustering */
38
    public NetworkConnector addNetworkConnector(String discoveryAddress) throws Exception;
39
    public NetworkConnector addNetworkConnector(URI discoveryAddress) throws Exception;
40
    public void removeNetworkConnector(NetworkConnector connector) throws Exception;
41
    public NetworkConnector[] getNetworkConnectors();
42
    public void setNetworkConnectors(List<NetworkConnector> networkConnectors) throws Exception;
43
    
44
    /** Persistence configuration */
45
    public void setPersistenceAdapter(PersistenceAdapter persistenceAdapter);
46
    public PersistenceAdapter getPersistenceAdapter();
47
    public void setPersistent(boolean persistent);
48
    public boolean isPersistent();
49
    
50
    /** Data directory for persistent storage */
51
    public void setDataDirectory(String dataDirectory);
52
    public String getDataDirectory();
53
    public void setDataDirectoryFile(File dataDirectoryFile);
54
    public File getDataDirectoryFile();
55
    
56
    /** JMX management */
57
    public void setUseJmx(boolean useJmx);
58
    public boolean isUseJmx();
59
    public void setJmxDomainName(String jmxDomainName);
60
    public String getJmxDomainName();
61
    public ManagementContext getManagementContext();
62
    public void setManagementContext(ManagementContext managementContext);
63
    
64
    /** Security configuration */
65
    public void setPlugins(BrokerPlugin[] plugins);
66
    public BrokerPlugin[] getPlugins();
67
    public void setSecurityManager(SecurityManager securityManager);
68
    
69
    /** Destination policies */
70
    public void setDestinationPolicy(PolicyMap destinationPolicy);
71
    public PolicyMap getDestinationPolicy();
72
    
73
    /** System usage limits */
74
    public void setSystemUsage(SystemUsage systemUsage);
75
    public SystemUsage getSystemUsage();
76
    
77
    /** Broker configuration */
78
    public void setPopulateJMSXUserID(boolean populateJMSXUserID);
79
    public boolean isPopulateJMSXUserID();
80
    public void setUseAuthenticatedPrincipalForJMSXUserID(boolean useAuthenticatedPrincipalForJMSXUserID);
81
    public boolean isUseAuthenticatedPrincipalForJMSXUserID();
82
    
83
    /** Advisory message support */
84
    public void setAdvisorySupport(boolean advisorySupport);
85
    public boolean isAdvisorySupport();
86
    
87
    /** Administrative view */
88
    public Broker getBroker();
89
    public BrokerView getAdminView() throws Exception;
90
    
91
    /** Wait for broker to stop */
92
    public void waitUntilStopped();
93
    public boolean waitUntilStarted();
94
    public boolean waitUntilStarted(int timeout);
95
}
96
```
97

98
**Usage Examples:**
99

100
```java
101
// Basic embedded broker
102
BrokerService broker = new BrokerService();
103
broker.setBrokerName("embedded-broker");
104
broker.addConnector("tcp://localhost:61616");
105
broker.setPersistent(false); // Use memory persistence
106
broker.start();
107

108
// Use the broker...
109
ConnectionFactory factory = new ActiveMQConnectionFactory("tcp://localhost:61616");
110

111
// Stop broker
112
broker.stop();
113

114
// Broker with persistence
115
BrokerService persistentBroker = new BrokerService();
116
persistentBroker.setBrokerName("persistent-broker");
117
persistentBroker.setDataDirectory("./activemq-data");
118
persistentBroker.addConnector("tcp://localhost:61617");
119
persistentBroker.start();
120

121
// Broker with multiple connectors
122
BrokerService multiBroker = new BrokerService();
123
multiBroker.setBrokerName("multi-transport-broker");
124
multiBroker.addConnector("tcp://localhost:61616");
125
multiBroker.addConnector("stomp://localhost:61613");
126
multiBroker.addConnector("mqtt://localhost:1883");
127
multiBroker.start();
128
```
129

130
### Broker Factory
131

132
Factory classes for creating brokers from configuration URIs.
133

134
```java { .api }
135
/**
136
 * Factory for creating brokers from URI configurations
137
 */
138
public class BrokerFactory {
139
    /** Create broker from URI configuration */
140
    public static BrokerService createBroker(URI config) throws Exception;
141
    
142
    /** Create broker from URI string */
143
    public static BrokerService createBroker(String uri) throws Exception;
144
    
145
    /** Create broker and start it */
146
    public static BrokerService createBrokerFromURI(String uri) throws Exception;
147
    
148
    /** Register broker factory handler */
149
    public static void registerBrokerFactoryHandler(String scheme, BrokerFactoryHandler handler);
150
    
151
    /** Get broker factory handler */
152
    public static BrokerFactoryHandler createBrokerFactoryHandler(String type);
153
}
154

155
/**
156
 * Interface for broker factory handlers
157
 */
158
public interface BrokerFactoryHandler {
159
    /** Create broker from URI */
160
    BrokerService createBroker(URI uri) throws Exception;
161
}
162
```
163

164
**Usage Examples:**
165

166
```java
167
// Create broker from URI
168
BrokerService broker = BrokerFactory.createBroker("broker:(tcp://localhost:61616)?persistent=false");
169
broker.start();
170

171
// Create and start broker in one step
172
BrokerService autoStartBroker = BrokerFactory.createBrokerFromURI(
173
    "broker:(tcp://localhost:61616,stomp://localhost:61613)?persistent=false"
174
);
175

176
// VM transport for embedded usage
177
BrokerService vmBroker = BrokerFactory.createBroker("broker:vm://embedded?persistent=false");
178
```
179

180
### Transport Connectors
181

182
Transport connector implementations for different protocols.
183

184
```java { .api }
185
/**
186
 * Transport connector for accepting client connections
187
 */
188
public class TransportConnector implements Service {
189
    /** Start accepting connections */
190
    public void start() throws Exception;
191
    
192
    /** Stop accepting connections */
193
    public void stop() throws Exception;
194
    
195
    /** Connector configuration */
196
    public void setUri(URI uri);
197
    public URI getUri();
198
    public void setName(String name);
199
    public String getName();
200
    
201
    /** Connection limits */
202
    public void setMaximumConnections(int maximumConnections);
203
    public int getMaximumConnections();
204
    public int getConnectionCount();
205
    
206
    /** Security configuration */
207
    public void setDiscoveryAgent(DiscoveryAgent discoveryAgent);
208
    public DiscoveryAgent getDiscoveryAgent();
209
    
210
    /** Get connect URI for clients */
211
    public URI getConnectUri() throws Exception;
212
    public URI getPublishableConnectURI() throws Exception;
213
    
214
    /** Connection statistics */
215
    public TransportConnectorStatistics getStatistics();
216
    public void resetStatistics();
217
}
218

219
/**
220
 * SSL transport connector with security features
221
 */
222
public class SslTransportConnector extends TransportConnector {
223
    /** Set key store configuration */
224
    public void setKeyStore(String keyStore);
225
    public String getKeyStore();
226
    public void setKeyStorePassword(String keyStorePassword);
227
    
228
    /** Set trust store configuration */
229
    public void setTrustStore(String trustStore);
230
    public String getTrustStore();
231
    public void setTrustStorePassword(String trustStorePassword);
232
    
233
    /** SSL protocol configuration */
234
    public void setWantClientAuth(boolean wantClientAuth);
235
    public boolean getWantClientAuth();
236
    public void setNeedClientAuth(boolean needClientAuth);
237
    public boolean getNeedClientAuth();
238
}
239
```
240

241
### Network Connectors
242

243
Network connectors for creating broker-to-broker connections.
244

245
```java { .api }
246
/**
247
 * Base network connector for broker clustering
248
 */
249
public abstract class NetworkConnector extends DefaultBrokerService implements Service {
250
    /** Network connector configuration */
251
    public void setUri(URI uri);
252
    public URI getUri();
253
    public void setDiscoveryUri(URI discoveryUri);
254
    public URI getDiscoveryUri();
255
    
256
    /** Network behavior */
257
    public void setDuplex(boolean duplex);
258
    public boolean isDuplex();
259
    public void setNetworkTTL(int networkTTL);
260
    public int getNetworkTTL();
261
    
262
    /** Message flow control */
263
    public void setConduitSubscriptions(boolean conduitSubscriptions);
264
    public boolean isConduitSubscriptions();
265
    public void setDynamicOnly(boolean dynamicOnly);
266
    public boolean isDynamicOnly();
267
    
268
    /** Bridge configuration */
269
    public void setBridgeTempDestinations(boolean bridgeTempDestinations);
270
    public boolean isBridgeTempDestinations();
271
    public void setDecreaseNetworkConsumerPriority(boolean decreaseNetworkConsumerPriority);
272
    public boolean isDecreaseNetworkConsumerPriority();
273
    
274
    /** Network filters */
275
    public void setExcludedDestinations(ActiveMQDestination[] excludedDestinations);
276
    public ActiveMQDestination[] getExcludedDestinations();
277
    public void setDynamicallyIncludedDestinations(ActiveMQDestination[] dynamicallyIncludedDestinations);
278
    public ActiveMQDestination[] getDynamicallyIncludedDestinations();
279
    public void setStaticallyIncludedDestinations(ActiveMQDestination[] staticallyIncludedDestinations);
280
    public ActiveMQDestination[] getStaticallyIncludedDestinations();
281
    
282
    /** Start network connector */
283
    public void start() throws Exception;
284
    
285
    /** Stop network connector */
286
    public void stop() throws Exception;
287
}
288

289
/**
290
 * Discovery-based network connector
291
 */
292
public class DiscoveryNetworkConnector extends NetworkConnector {
293
    /** Set discovery agent for finding brokers */
294
    public void setDiscoveryAgent(DiscoveryAgent discoveryAgent);
295
    public DiscoveryAgent getDiscoveryAgent();
296
}
297

298
/**
299
 * Multicast network connector
300
 */
301
public class MulticastNetworkConnector extends DiscoveryNetworkConnector {
302
    /** Multicast configuration */
303
    public void setMulticastGroup(String multicastGroup);
304
    public String getMulticastGroup();
305
    public void setMulticastPort(int multicastPort);
306
    public int getMulticastPort();
307
}
308
```
309

310
### Broker Plugins
311

312
Plugin system for extending broker functionality.
313

314
```java { .api }
315
/**
316
 * Interface for broker plugins
317
 */
318
public interface BrokerPlugin {
319
    /** Install plugin into broker */
320
    Broker installPlugin(Broker broker) throws Exception;
321
}
322

323
/**
324
 * Statistics collection plugin
325
 */
326
public class StatisticsBrokerPlugin implements BrokerPlugin {
327
    public Broker installPlugin(Broker broker) throws Exception;
328
}
329

330
/**
331
 * Authentication plugin for security
332
 */
333
public class SimpleAuthenticationPlugin implements BrokerPlugin {
334
    /** Set user/password authentication */
335
    public void setUsers(Map<String, String> users);
336
    public Map<String, String> getUsers();
337
    
338
    /** Set group memberships */
339
    public void setGroups(Map<String, Set<String>> groups);
340
    public Map<String, Set<String>> getGroups();
341
    
342
    public Broker installPlugin(Broker broker) throws Exception;
343
}
344

345
/**
346
 * Authorization plugin for access control
347
 */
348
public class AuthorizationPlugin implements BrokerPlugin {
349
    /** Set authorization map */
350
    public void setMap(AuthorizationMap map);
351
    public AuthorizationMap getMap();
352
    
353
    public Broker installPlugin(Broker broker) throws Exception;
354
}
355
```
356

357
**Usage Examples:**
358

359
```java
360
// Broker with authentication
361
BrokerService broker = new BrokerService();
362

363
// Configure authentication plugin
364
SimpleAuthenticationPlugin authPlugin = new SimpleAuthenticationPlugin();
365
Map<String, String> users = new HashMap<>();
366
users.put("admin", "password");
367
users.put("user", "userpass");
368
authPlugin.setUsers(users);
369

370
// Configure authorization plugin
371
AuthorizationPlugin authzPlugin = new AuthorizationPlugin();
372
DefaultAuthorizationMap authMap = new DefaultAuthorizationMap();
373
// Configure authorization rules...
374
authzPlugin.setMap(authMap);
375

376
// Install plugins
377
broker.setPlugins(new BrokerPlugin[]{authPlugin, authzPlugin});
378
broker.start();
379
```
380

381
### System Usage Configuration
382

383
Configuration for broker resource usage limits.
384

385
```java { .api }
386
/**
387
 * System usage configuration for resource management
388
 */
389
public class SystemUsage {
390
    /** Memory usage limits */
391
    public void setMemoryUsage(MemoryUsage memoryUsage);
392
    public MemoryUsage getMemoryUsage();
393
    
394
    /** Store usage limits */
395
    public void setStoreUsage(StoreUsage storeUsage);
396
    public StoreUsage getStoreUsage();
397
    
398
    /** Temporary usage limits */
399
    public void setTempUsage(TempUsage tempUsage);
400
    public TempUsage getTempUsage();
401
    
402
    /** Job scheduler usage limits */
403
    public void setJobSchedulerUsage(JobSchedulerUsage jobSchedulerUsage);
404
    public JobSchedulerUsage getJobSchedulerUsage();
405
    
406
    /** Check if usage exceeds limits */
407
    public boolean isFull();
408
    
409
    /** Wait for usage to drop below limits */
410
    public void waitForSpace() throws InterruptedException;
411
    public boolean waitForSpace(long timeout) throws InterruptedException;
412
}
413

414
/**
415
 * Memory usage tracking and limits
416
 */
417
public class MemoryUsage extends Usage<MemoryUsage> {
418
    /** Set memory limit in bytes */
419
    public void setLimit(long limit);
420
    public long getLimit();
421
    
422
    /** Get current usage */
423
    public long getUsage();
424
    public int getPercentUsage();
425
    
426
    /** Check usage status */
427
    public boolean isFull();
428
}
429

430
/**
431
 * Store usage tracking and limits
432
 */
433
public class StoreUsage extends Usage<StoreUsage> {
434
    /** Set store size limit */
435
    public void setLimit(long limit);
436
    public long getLimit();
437
    
438
    /** Get current store usage */
439
    public long getUsage();
440
    public int getPercentUsage();
441
    
442
    /** Set store directory */
443
    public void setDirectory(File directory);
444
    public File getDirectory();
445
}
446
```
447

448
**Usage Examples:**
449

450
```java
451
// Configure system usage limits
452
BrokerService broker = new BrokerService();
453

454
SystemUsage systemUsage = new SystemUsage();
455

456
// Set memory limit to 512MB
457
MemoryUsage memoryUsage = new MemoryUsage();
458
memoryUsage.setLimit(512 * 1024 * 1024);
459
systemUsage.setMemoryUsage(memoryUsage);
460

461
// Set store limit to 10GB
462
StoreUsage storeUsage = new StoreUsage();
463
storeUsage.setLimit(10L * 1024 * 1024 * 1024);
464
systemUsage.setStoreUsage(storeUsage);
465

466
broker.setSystemUsage(systemUsage);
467
broker.start();
468
```
469

470
## Types
471

472
```java { .api }
473
/**
474
 * Broker plugin support base class
475
 */
476
public class BrokerPluginSupport extends BrokerFilter implements BrokerPlugin {
477
    public Broker installPlugin(Broker broker) throws Exception;
478
}
479

480
/**
481
 * Management context for JMX integration
482
 */
483
public class ManagementContext {
484
    /** JMX configuration */
485
    public void setJmxDomainName(String jmxDomainName);
486
    public String getJmxDomainName();
487
    public void setCreateConnector(boolean createConnector);
488
    public boolean isCreateConnector();
489
    
490
    /** Start JMX services */
491
    public void start() throws IOException;
492
    
493
    /** Stop JMX services */
494
    public void stop() throws IOException;
495
}
496

497
/**
498
 * Policy map for destination-specific configurations
499
 */
500
public class PolicyMap extends BaseDestination {
501
    /** Set default policy entry */
502
    public void setDefaultEntry(PolicyEntry defaultEntry);
503
    public PolicyEntry getDefaultEntry();
504
    
505
    /** Set queue-specific policies */
506
    public void setQueueEntries(List<DestinationMapEntry> queueEntries);
507
    public List<DestinationMapEntry> getQueueEntries();
508
    
509
    /** Set topic-specific policies */
510
    public void setTopicEntries(List<DestinationMapEntry> topicEntries);
511
    public List<DestinationMapEntry> getTopicEntries();
512
}
513
```