0
# Core API and Configuration
1

2
The core API provides fundamental classes for queue configuration, high-performance string handling, buffer operations, and message routing in Apache ActiveMQ Artemis.
3

4
## Capabilities
5

6
### Queue Configuration
7

8
`QueueConfiguration` is the central class for defining queue properties with a fluent API and JSON serialization support.
9

10
```java { .api }
11
class QueueConfiguration implements Serializable {
12
    // Factory methods
13
    static QueueConfiguration of(String name);
14
    static QueueConfiguration of(SimpleString name);
15
    static QueueConfiguration of(QueueConfiguration queueConfiguration);
16
    static QueueConfiguration fromJSON(String jsonString);
17
    
18
    // Core configuration setters (all return QueueConfiguration for chaining)
19
    QueueConfiguration setName(SimpleString name);
20
    QueueConfiguration setAddress(SimpleString address);
21
    QueueConfiguration setRoutingType(RoutingType routingType);
22
    QueueConfiguration setFilterString(SimpleString filterString);
23
    QueueConfiguration setDurable(Boolean durable);
24
    QueueConfiguration setAutoDelete(Boolean autoDelete);
25
    QueueConfiguration setMaxConsumers(Integer maxConsumers);
26
    QueueConfiguration setExclusive(Boolean exclusive);
27
    QueueConfiguration setRingSize(Long ringSize);
28
    QueueConfiguration setUser(SimpleString user);
29
    QueueConfiguration setUser(String user);
30
    
31
    // Group management setters
32
    QueueConfiguration setGroupRebalance(Boolean groupRebalance);
33
    QueueConfiguration setGroupRebalancePauseDispatch(Boolean groupRebalancePauseDispatch);
34
    QueueConfiguration setGroupBuckets(Integer groupBuckets);
35
    QueueConfiguration setGroupFirstKey(SimpleString groupFirstKey);
36
    QueueConfiguration setGroupFirstKey(String groupFirstKey);
37
    
38
    // Last value queue setters
39
    QueueConfiguration setLastValue(Boolean lastValue);
40
    QueueConfiguration setLastValueKey(SimpleString lastValueKey);
41
    QueueConfiguration setLastValueKey(String lastValueKey);
42
    
43
    // Advanced behavior setters
44
    QueueConfiguration setNonDestructive(Boolean nonDestructive);
45
    QueueConfiguration setPurgeOnNoConsumers(Boolean purgeOnNoConsumers);
46
    QueueConfiguration setEnabled(Boolean enabled);
47
    QueueConfiguration setConsumersBeforeDispatch(Integer consumersBeforeDispatch);
48
    QueueConfiguration setDelayBeforeDispatch(Long delayBeforeDispatch);
49
    QueueConfiguration setConsumerPriority(Integer consumerPriority);
50
    
51
    // Auto-delete configuration setters
52
    QueueConfiguration setAutoDeleteDelay(Long autoDeleteDelay);
53
    QueueConfiguration setAutoDeleteMessageCount(Long autoDeleteMessageCount);
54
    
55
    // Management and lifecycle setters
56
    QueueConfiguration setConfigurationManaged(Boolean configurationManaged);
57
    QueueConfiguration setTemporary(Boolean temporary);
58
    QueueConfiguration setAutoCreateAddress(Boolean autoCreateAddress);
59
    QueueConfiguration setInternal(Boolean internal);
60
    QueueConfiguration setTransient(Boolean transient);
61
    QueueConfiguration setAutoCreated(Boolean autoCreated);
62
    
63
    // Generic key-value setter
64
    QueueConfiguration set(String key, String value);
65
    
66
    // Core property getters
67
    SimpleString getName();
68
    SimpleString getAddress();
69
    RoutingType getRoutingType();
70
    SimpleString getFilterString();
71
    Boolean getDurable();
72
    Boolean isAutoDelete();
73
    Integer getMaxConsumers();
74
    Boolean getExclusive();
75
    Long getRingSize();
76
    Long getId();
77
    SimpleString getUser();
78
    
79
    // Group management getters
80
    Boolean isGroupRebalance();
81
    Boolean isGroupRebalancePauseDispatch();
82
    Integer getGroupBuckets();
83
    SimpleString getGroupFirstKey();
84
    
85
    // Last value queue getters
86
    Boolean isLastValue();
87
    SimpleString getLastValueKey();
88
    
89
    // Advanced behavior getters
90
    Boolean isNonDestructive();
91
    Boolean isPurgeOnNoConsumers();
92
    Boolean isEnabled();
93
    Integer getConsumersBeforeDispatch();
94
    Long getDelayBeforeDispatch();
95
    Integer getConsumerPriority();
96
    
97
    // Auto-delete configuration getters
98
    Long getAutoDeleteDelay();
99
    Long getAutoDeleteMessageCount();
100
    
101
    // Management and lifecycle getters
102
    Boolean isConfigurationManaged();
103
    Boolean isTemporary();
104
    Boolean isAutoCreateAddress();
105
    Boolean isInternal();
106
    Boolean isTransient();
107
    Boolean isAutoCreated();
108
    
109
    // Utility methods
110
    boolean isAddressNull();
111
    boolean isMirrorQueue();
112
    
113
    // Object methods
114
    boolean equals(Object obj);
115
    int hashCode();
116
    String toString();
117
    
118
    // JSON serialization
119
    String toJSON();
120
}
121
```
122

123
#### Usage Examples
124

125
```java
126
// Create queue configuration with fluent API
127
QueueConfiguration config = QueueConfiguration.of("orderQueue")
128
    .setAddress(SimpleString.of("orders"))
129
    .setRoutingType(RoutingType.ANYCAST)
130
    .setDurable(true)
131
    .setMaxConsumers(5)
132
    .setFilterString(SimpleString.of("priority > 5"));
133

134
// Serialize to JSON
135
String json = config.toJSON();
136

137
// Create from JSON
138
QueueConfiguration restored = QueueConfiguration.fromJSON(json);
139

140
// Copy configuration
141
QueueConfiguration copy = QueueConfiguration.of(config)
142
    .setName(SimpleString.of("newQueueName"));
143
```
144

145
### High-Performance String Handling
146

147
`SimpleString` provides an efficient string implementation that stores data as byte arrays, minimizing object allocation and copying.
148

149
```java { .api }
150
final class SimpleString implements CharSequence, Serializable, Comparable<SimpleString> {
151
    // Constants
152
    static final SimpleString EMPTY;
153
    
154
    // Factory methods
155
    static SimpleString of(String string);
156
    static SimpleString of(byte[] data);
157
    static SimpleString of(char c);
158
    static SimpleString of(String string, StringSimpleStringPool pool);
159
    
160
    // Buffer I/O operations
161
    static SimpleString readNullableSimpleString(ByteBuf buffer);
162
    static SimpleString readSimpleString(ByteBuf buffer);
163
    static SimpleString readNullableSimpleString(ByteBuf buffer, ByteBufSimpleStringPool pool);
164
    static SimpleString readSimpleString(ByteBuf buffer, ByteBufSimpleStringPool pool);
165
    static void writeNullableSimpleString(ByteBuf buffer, SimpleString val);
166
    static void writeSimpleString(ByteBuf buffer, SimpleString val);
167
    
168
    // Static utility methods
169
    static int sizeofString(SimpleString str);
170
    static int sizeofNullableString(SimpleString str);
171
    
172
    // Core data access
173
    byte[] getData();
174
    int sizeof();
175
    
176
    // String validation
177
    boolean isBlank();
178
    boolean isEmpty();
179
    
180
    // Comparison methods
181
    int compareTo(SimpleString o);
182
    boolean equals(Object obj);
183
    boolean equals(ByteBuf byteBuf, int offset, int length);
184
    int hashCode();
185
    
186
    // String operations
187
    boolean startsWith(SimpleString other);
188
    boolean startsWith(char other);
189
    boolean contains(char c);
190
    SimpleString[] split(char delim);
191
    SimpleString concat(String toAdd);
192
    SimpleString concat(SimpleString toAdd);
193
    SimpleString concat(char c);
194
    SimpleString subSeq(int start, int end);
195
    String[] getPaths(char separator);
196
    
197
    // Character array operations
198
    void getChars(int srcBegin, int srcEnd, char[] dst, int dstPos);
199
    
200
    // CharSequence implementation
201
    int length();
202
    char charAt(int index);
203
    CharSequence subSequence(int start, int end);
204
    String toString();
205
}
206
```
207

208
#### Inner Classes
209

210
```java { .api }
211
// Pool for reading SimpleString from ByteBuf with performance optimization
212
static final class ByteBufSimpleStringPool extends AbstractByteBufPool<SimpleString> {
213
    // Constructors
214
    ByteBufSimpleStringPool();
215
    ByteBufSimpleStringPool(int capacity);
216
    ByteBufSimpleStringPool(int capacity, int maxCharsLength);
217
    
218
    // Pool operations
219
    boolean isEqual(SimpleString entry, ByteBuf byteBuf, int offset, int length);
220
    boolean canPool(ByteBuf byteBuf, int length);
221
    SimpleString create(ByteBuf byteBuf, int length);
222
}
223

224
// Pool for creating SimpleString from String with performance optimization
225
static final class StringSimpleStringPool extends AbstractPool<String, SimpleString> {
226
    // Constructors
227
    StringSimpleStringPool();
228
    StringSimpleStringPool(int capacity);
229
    
230
    // Pool operations
231
    SimpleString create(String value);
232
    boolean isEqual(SimpleString entry, String value);
233
}
234
```
235

236
#### Usage Examples
237

238
```java
239
// Create SimpleString instances
240
SimpleString name = SimpleString.of("user.queue.name");
241
SimpleString shortName = SimpleString.of('Q');
242

243
// String operations
244
boolean isUserQueue = name.startsWith(SimpleString.of("user."));
245
SimpleString[] parts = name.split('.');
246
SimpleString combined = name.concat(".backup");
247

248
// Performance optimizations with pooling
249
StringSimpleStringPool pool = new StringSimpleStringPool();
250
SimpleString pooled = SimpleString.of("frequently.used.name", pool);
251

252
// Buffer operations (typically used internally)
253
ByteBuf buffer = /* ... */;
254
SimpleString.writeSimpleString(buffer, name);
255
SimpleString restored = SimpleString.readSimpleString(buffer);
256

257
// Character array operations
258
char[] chars = new char[name.length()];
259
name.getChars(0, name.length(), chars, 0);
260
```
261

262
### Message Routing
263

264
Defines the routing behavior for messages in ActiveMQ Artemis.
265

266
```java { .api }
267
enum RoutingType {
268
    MULTICAST(0),  // Publish-subscribe semantics
269
    ANYCAST(1);    // Point-to-point semantics
270
    
271
    byte getType();
272
    static RoutingType getType(byte type);
273
}
274
```
275

276
### Buffer Operations
277

278
`ActiveMQBuffer` provides a comprehensive interface for buffer operations, wrapping Netty's ByteBuf.
279

280
```java { .api }
281
interface ActiveMQBuffer extends DataInput {
282
    // Core buffer access
283
    ByteBuf byteBuf();
284
    
285
    // Buffer capacity and position
286
    int capacity();
287
    int readerIndex();
288
    int writerIndex();
289
    ActiveMQBuffer setIndex(int readerIndex, int writerIndex);
290
    
291
    // Buffer state
292
    int readableBytes();
293
    int writableBytes();
294
    boolean readable();
295
    boolean writable();
296
    ActiveMQBuffer clear();
297
    
298
    // Mark and reset operations
299
    ActiveMQBuffer markReaderIndex();
300
    ActiveMQBuffer resetReaderIndex();
301
    ActiveMQBuffer markWriterIndex();
302
    ActiveMQBuffer resetWriterIndex();
303
    
304
    // Random access get operations
305
    byte getByte(int index);
306
    short getShort(int index);
307
    int getInt(int index);
308
    long getLong(int index);
309
    char getChar(int index);
310
    float getFloat(int index);
311
    double getDouble(int index);
312
    
313
    // Random access set operations
314
    ActiveMQBuffer setByte(int index, byte value);
315
    ActiveMQBuffer setShort(int index, short value);
316
    ActiveMQBuffer setInt(int index, int value);
317
    ActiveMQBuffer setLong(int index, long value);
318
    ActiveMQBuffer setChar(int index, char value);
319
    ActiveMQBuffer setFloat(int index, float value);
320
    ActiveMQBuffer setDouble(int index, double value);
321
    
322
    // Sequential read operations
323
    byte readByte();
324
    short readShort();
325
    int readInt();
326
    long readLong();
327
    char readChar();
328
    float readFloat();
329
    double readDouble();
330
    boolean readBoolean();
331
    
332
    // Sequential write operations
333
    ActiveMQBuffer writeByte(byte value);
334
    ActiveMQBuffer writeShort(short value);
335
    ActiveMQBuffer writeInt(int value);
336
    ActiveMQBuffer writeLong(long value);
337
    ActiveMQBuffer writeChar(char value);
338
    ActiveMQBuffer writeFloat(float value);
339
    ActiveMQBuffer writeDouble(double value);
340
    ActiveMQBuffer writeBoolean(boolean value);
341
    
342
    // SimpleString operations
343
    SimpleString readNullableSimpleString();
344
    SimpleString readSimpleString();
345
    ActiveMQBuffer writeNullableSimpleString(SimpleString value);
346
    ActiveMQBuffer writeSimpleString(SimpleString value);
347
    
348
    // Nullable primitive operations
349
    int readNullableInt();
350
    long readNullableLong();
351
    boolean readNullableBoolean();
352
    ActiveMQBuffer writeNullableInt(Integer value);
353
    ActiveMQBuffer writeNullableLong(Long value);
354
    ActiveMQBuffer writeNullableBoolean(Boolean value);
355
    
356
    // String operations
357
    String readString();
358
    String readNullableString();
359
    String readUTF();
360
    ActiveMQBuffer writeString(String value);
361
    ActiveMQBuffer writeUTF(String value);
362
    
363
    // Buffer management
364
    ActiveMQBuffer copy();
365
    ActiveMQBuffer slice();
366
    ActiveMQBuffer duplicate();
367
    ByteBuffer toByteBuffer();
368
    void release();
369
    
370
    // Bulk transfer operations (multiple overloads)
371
    ActiveMQBuffer getBytes(int index, byte[] dst);
372
    ActiveMQBuffer setBytes(int index, byte[] src);
373
    ActiveMQBuffer readBytes(byte[] dst);
374
    ActiveMQBuffer writeBytes(byte[] src);
375
}
376
```
377

378
### Buffer Factory
379

380
Factory methods for creating various types of `ActiveMQBuffer` instances.
381

382
```java { .api }
383
class ActiveMQBuffers {
384
    // Dynamic buffers that can grow as needed
385
    static ActiveMQBuffer dynamicBuffer(int size);
386
    static ActiveMQBuffer dynamicBuffer(byte[] bytes);
387
    
388
    // Pooled buffers for performance optimization
389
    static ActiveMQBuffer pooledBuffer(int size);
390
    
391
    // Fixed-size buffers
392
    static ActiveMQBuffer fixedBuffer(int size);
393
    
394
    // Wrapped buffer implementations
395
    static ActiveMQBuffer wrappedBuffer(ByteBuffer underlying);
396
    static ActiveMQBuffer wrappedBuffer(ByteBuf underlying);
397
    static ActiveMQBuffer wrappedBuffer(byte[] underlying);
398
}
399
```
400

401
## Core Data Types
402

403
### Generic Pair Classes
404

405
```java { .api }
406
// Generic pair for two related values
407
class Pair<A, B> implements Serializable {
408
    public A a;
409
    public B b;
410
    
411
    public Pair(A a, B b);
412
    // Standard equals, hashCode, toString methods
413
}
414

415
// Optimized pair for object + long combinations
416
class ObjLongPair<A> {
417
    public A obj;
418
    public long longValue;
419
    
420
    public ObjLongPair(A obj, long longValue);
421
    // Standard equals, hashCode, toString methods
422
}
423
```
424

425
### Address and Queue Attributes
426

427
```java { .api }
428
// Container for queue attribute information
429
class QueueAttributes {
430
    // Queue attribute data and methods
431
}
432

433
// Address with parameters for advanced routing
434
class ParameterisedAddress {
435
    // Parameterized address functionality
436
}
437

438
// Result information for auto-created queues/addresses
439
class AutoCreateResult {
440
    // Auto-creation result data
441
}
442

443
// Reasons for client disconnections
444
enum DisconnectReason {
445
    // Disconnection reason constants
446
}
447
```
448

449
## Usage Patterns
450

451
### Configuration Chain Pattern
452

453
```java
454
// Build complex configurations with method chaining
455
QueueConfiguration config = QueueConfiguration.of("processQueue")
456
    .setAddress(SimpleString.of("process.orders"))
457
    .setRoutingType(RoutingType.ANYCAST)
458
    .setDurable(true)
459
    .setMaxConsumers(3)
460
    .setFilterString(SimpleString.of("priority >= 7"))
461
    .setRingSize(1000L);
462
```
463

464
### Performance-Optimized String Handling
465

466
```java
467
// Use SimpleString for frequent operations to avoid string allocation
468
SimpleString baseName = SimpleString.of("queue.");
469
SimpleString fullName = baseName.concat("user.orders");
470

471
// Split once, reuse results
472
String[] paths = fullName.getPaths('.');
473
// paths = ["queue", "user", "orders"]
474
```
475

476
### Buffer Processing Pattern
477

478
```java
479
// Create different types of buffers based on needs
480
ActiveMQBuffer dynamicBuffer = ActiveMQBuffers.dynamicBuffer(512);  // Can grow
481
ActiveMQBuffer pooledBuffer = ActiveMQBuffers.pooledBuffer(1024);   // From pool
482
ActiveMQBuffer fixedBuffer = ActiveMQBuffers.fixedBuffer(2048);     // Fixed size
483

484
// Wrap existing data
485
ActiveMQBuffer wrappedBuffer = ActiveMQBuffers.wrappedBuffer(existingByteArray);
486

487
// Write structured data
488
dynamicBuffer.writeSimpleString(SimpleString.of("header"));
489
dynamicBuffer.writeInt(messageCount);
490
dynamicBuffer.writeLong(timestamp);
491

492
// Read back structured data
493
dynamicBuffer.resetReaderIndex();
494
SimpleString header = dynamicBuffer.readSimpleString();
495
int count = dynamicBuffer.readInt();
496
long time = dynamicBuffer.readLong();
497
```