0
# Apache ActiveMQ Artemis Commons
1

2
Apache ActiveMQ Artemis Commons provides essential common utilities, API classes, exception definitions, and shared functionality for the Apache ActiveMQ Artemis message broker ecosystem. This library serves as the foundational layer containing core APIs, utility classes, JSON processing capabilities, and shared data structures that other Artemis components depend upon.
3

4
## Package Information
5

6
- **Package Name**: org.apache.activemq:artemis-commons
7
- **Package Type**: maven
8
- **Language**: Java
9
- **Installation**: Add to Maven POM:
10
  ```xml
11
  <dependency>
12
    <groupId>org.apache.activemq</groupId>
13
    <artifactId>artemis-commons</artifactId>
14
    <version>2.42.0</version>
15
  </dependency>
16
  ```
17

18
## Core Imports
19

20
```java
21
// Core API classes
22
import org.apache.activemq.artemis.api.core.QueueConfiguration;
23
import org.apache.activemq.artemis.api.core.SimpleString;
24
import org.apache.activemq.artemis.api.core.ActiveMQBuffer;
25
import org.apache.activemq.artemis.api.core.RoutingType;
26

27
// Exception handling
28
import org.apache.activemq.artemis.api.core.ActiveMQException;
29
import org.apache.activemq.artemis.api.core.ActiveMQExceptionType;
30

31
// Utilities
32
import org.apache.activemq.artemis.utils.ByteUtil;
33
import org.apache.activemq.artemis.utils.ActiveMQThreadFactory;
34
import org.apache.activemq.artemis.utils.FileUtil;
35
import org.apache.activemq.artemis.utils.TimeUtils;
36
import org.apache.activemq.artemis.utils.UTF8Util;
37
import org.apache.activemq.artemis.utils.UUID;
38
import org.apache.activemq.artemis.utils.UUIDGenerator;
39

40
// Collections
41
import org.apache.activemq.artemis.utils.collections.TypedProperties;
42
import org.apache.activemq.artemis.utils.collections.ConcurrentLongHashMap;
43
import org.apache.activemq.artemis.utils.collections.ConcurrentHashSet;
44
import org.apache.activemq.artemis.utils.collections.LinkedListImpl;
45

46
// Actor Framework
47
import org.apache.activemq.artemis.utils.actors.Actor;
48
import org.apache.activemq.artemis.utils.actors.ThresholdActor;
49
import org.apache.activemq.artemis.utils.actors.OrderedExecutor;
50

51
// JSON API (shaded)
52
import org.apache.activemq.artemis.json.JsonObject;
53
import org.apache.activemq.artemis.json.JsonArray;
54
import org.apache.activemq.artemis.utils.JsonLoader;
55
```
56

57
## Basic Usage
58

59
```java
60
import org.apache.activemq.artemis.api.core.QueueConfiguration;
61
import org.apache.activemq.artemis.api.core.SimpleString;
62
import org.apache.activemq.artemis.api.core.RoutingType;
63

64
// Create a queue configuration with fluent API
65
QueueConfiguration queueConfig = QueueConfiguration.of("myQueue")
66
    .setAddress(SimpleString.of("myAddress"))
67
    .setRoutingType(RoutingType.ANYCAST)
68
    .setDurable(true)
69
    .setMaxConsumers(10);
70

71
// Convert to JSON
72
String jsonString = queueConfig.toJSON();
73

74
// Create from JSON
75
QueueConfiguration fromJson = QueueConfiguration.fromJSON(jsonString);
76

77
// Work with SimpleString for performance
78
SimpleString address = SimpleString.of("my.address.name");
79
boolean isMatch = address.startsWith(SimpleString.of("my."));
80
```
81

82
## Architecture
83

84
Artemis Commons is organized into several key architectural layers:
85

86
- **Core API Layer** (`org.apache.activemq.artemis.api.core`): Primary API classes for queue configuration, buffer operations, and core data types
87
- **Utilities Layer** (`org.apache.activemq.artemis.utils`): Threading, pooling, validation, and general-purpose utilities
88
- **JSON Layer** (`org.apache.activemq.artemis.json`): Complete shaded JSON API based on Jakarta JSON and Apache Johnzon
89
- **Exception Layer**: Comprehensive typed exception hierarchy for different error conditions
90
- **Logging Layer** (`org.apache.activemq.artemis.logs`): Internationalized logging with audit capabilities
91

92
Key design principles:
93
- **Performance Focus**: Extensive use of object pooling and optimized data structures like SimpleString
94
- **Type Safety**: Strong typing with comprehensive exception hierarchy
95
- **Fluent APIs**: Builder and chain patterns for configuration classes
96
- **Zero Dependencies**: Self-contained with shaded JSON dependencies
97

98
## Capabilities
99

100
### Core API and Configuration
101

102
Central configuration classes and core data types for queue management, message routing, and buffer operations.
103

104
```java { .api }
105
// Queue configuration with fluent API
106
QueueConfiguration config = QueueConfiguration.of("queueName")
107
    .setAddress(SimpleString.of("address"))
108
    .setRoutingType(RoutingType.ANYCAST);
109

110
// High-performance string handling
111
SimpleString str = SimpleString.of("text");
112
byte[] data = str.getData();
113

114
// Buffer operations
115
ActiveMQBuffer buffer = /* ... */;
116
buffer.writeSimpleString(str);
117
```
118

119
[Core API and Configuration](./core-api.md)
120

121
### Collections Utilities
122

123
Specialized high-performance collection implementations for concurrent operations, primitive types, and type-safe properties.
124

125
```java { .api }
126
// Concurrent collections with no boxing overhead
127
ConcurrentLongHashMap<Message> messages = new ConcurrentLongHashMap<>(1000);
128
messages.put(messageId, message);
129

130
// Type-safe properties with JMS-compliant conversions
131
TypedProperties props = new TypedProperties();
132
props.putIntProperty(SimpleString.of("priority"), 5);
133
```
134

135
[Collections Utilities](./collections.md)
136

137
### Actor Framework
138

139
Asynchronous message processing framework with guaranteed ordering, backpressure management, and sophisticated state control.
140

141
```java { .api }
142
// Create actor for ordered message processing
143
Actor<String> actor = new Actor<>(executor, message -> processMessage(message));
144
actor.act("message");
145

146
// Threshold-based flow control
147
ThresholdActor<Buffer> bufferActor = new ThresholdActor<>(
148
    executor, this::processBuffer, maxSize, Buffer::size, 
149
    this::applyBackpressure, this::releaseBackpressure);
150
```
151

152
[Actor Framework](./actors.md)
153

154
### Exception Handling
155

156
Comprehensive exception hierarchy with 40+ specific exception types for different error conditions in ActiveMQ Artemis.
157

158
```java { .api }
159
try {
160
    // ActiveMQ operations
161
} catch (ActiveMQException e) {
162
    ActiveMQExceptionType type = e.getType();
163
    // Handle based on specific exception type
164
}
165
```
166

167
[Exception Handling](./exceptions.md)
168

169
### Utility Classes
170

171
Threading, pooling, validation, environment access, and general-purpose utilities for Artemis components.
172

173
```java { .api }
174
// Thread factory with proper naming
175
ActiveMQThreadFactory factory = new ActiveMQThreadFactory("MyGroup", true, classLoader);
176
Thread thread = factory.newThread(runnable);
177

178
// Byte utilities
179
byte[] bytes = ByteUtil.hexStringToByteArray("48656c6c6f");
180
String hex = ByteUtil.bytesToHex(bytes);
181
```
182

183
[Utility Classes](./utilities.md)
184

185
### JSON Processing
186

187
Complete JSON API implementation with object/array builders, providing Jakarta JSON compatibility through shaded dependencies.
188

189
```java { .api }
190
// Create JSON objects
191
JsonObject obj = JsonLoader.createObjectBuilder()
192
    .add("name", "value")
193
    .add("number", 42)
194
    .build();
195

196
// Parse JSON
197
JsonObject parsed = JsonLoader.readObject(new StringReader(jsonString));
198
String value = parsed.getString("name");
199
```
200

201
[JSON Processing](./json-api.md)
202

203
### Logging and Audit
204

205
Internationalized logging framework with audit capabilities for system events and operations.
206

207
```java { .api }
208
// Access logging interfaces
209
ActiveMQUtilLogger logger = /* ... */;
210
AuditLogger.log(event, details);
211
```
212

213
[Logging and Audit](./logging.md)
214

215
## Types
216

217
```java { .api }
218
// Core routing types
219
enum RoutingType {
220
    MULTICAST(0),
221
    ANYCAST(1);
222
    
223
    byte getType();
224
    static RoutingType getType(byte type);
225
}
226

227
// Generic pair utility
228
class Pair<A, B> implements Serializable {
229
    public A a;
230
    public B b;
231
    
232
    public Pair(A a, B b);
233
}
234

235
// Object + long combination
236
class ObjLongPair<A> {
237
    public A obj;
238
    public long longValue;
239
    
240
    public ObjLongPair(A obj, long longValue);
241
}
242
```