API Reference¶

Complete reference for all public classes, interfaces, methods, and fields in IgnisMQ.

IQueue¶

The primary interface for interacting with a queue. Generic parameter M is the message type.

Methods¶

IgnisMQManager¶

public final class IgnisMQManager

Central manager for all queue lifecycle operations.

stop() shuts down the control, worker and handler pools, cancels the queue-refresh watcher, and — only when the manager created the storage client itself — closes that client. If you passed your own StorageClient to the constructor, you retain ownership of it and are responsible for closing it. stop() is safe to call more than once, and safe to call when start() never ran.

Constructors¶

public IgnisMQManager(
    String clientId,
    BaseStorage storage,
    ObjectMapper mapper,
    MeterRegistry meterRegistry,
    CuratorFramework curatorFramework,
    String farmId,
    IgnisMQSettings settings
) throws Exception

Creates the manager without an externally provided StorageClient. The client is constructed internally from the storage configuration, and the manager closes it on stop().

public IgnisMQManager(
    String clientId,
    BaseStorage storage,
    ObjectMapper mapper,
    MeterRegistry meterRegistry,
    StorageClient storageClient,
    CuratorFramework curatorFramework,
    String farmId,
    IgnisMQSettings settings
) throws Exception

Creates the manager with an externally managed StorageClient, allowing the caller to share or reuse the underlying database connection. The caller keeps ownership, so stop() leaves the client open.

In both forms settings may be null, which means IgnisMQSettings.defaults(). In the eight-argument form storageClient may also be null, which asks the manager to build and own one - exactly as the seven-argument form does.

Methods¶

initialiseMessageHandlers¶

void initialiseMessageHandlers(Map<String, Map.Entry<Class, MessageHandler>> messageHandlers)

Registers all message handler mappings. Must be called exactly once before any call to createQueue. Subsequent calls will fail. Internally calls refreshQueues() to sync state from the database. Framework integrations may expose getQueueStats() through their metrics system.

[!WARNING] Calling this method more than once will throw an exception. Ensure all handlers are collected into a single map before invoking.

getQueue¶

<M> IQueue<M> getQueue(String name)

Returns the in-memory IQueue instance for the given queue name.

Throws: IgnisMQException with ErrorCode.QUEUE_NOT_FOUND if no queue with that name exists.

getAllQueues¶

Map<String, IQueue<?>> getAllQueues()

Returns the full in-memory map of queue name to IQueue instance.

getAllQueuesFromDB¶

Set<String> getAllQueuesFromDB()

Queries Aerospike and returns the set of all active queue names persisted in the database. Names only; use getStoredQueues when the configuration matters.

getStoredQueues¶

Map<String, QueueEntity> getStoredQueues(boolean active)

Queries Aerospike and returns every queue with the given active flag, each with its stored configuration. Unlike getAllQueues this does not depend on this process having adopted the queue, so it is the cluster-truthful inventory. Pass false to list deactivated queues.

getStoredQueue¶

Optional<QueueEntity> getStoredQueue(String queueName)

The stored definition of one queue, whether or not it is active or served by this process. Empty when no such queue exists.

createQueue¶

void createQueue(CreateQueueRequest queueRequest) throws Exception

Validates the request, creates the underlying Magazine structure, persists a QueueEntity to the database, and schedules this process's consumers and shovels for the queue. It does not schedule sweeps: the sweeper is scheduled once per process by TaskInitializer.start(), not per queue.

Throws: IgnisMQException with ErrorCode.QUEUE_ALREADY_EXISTS if a record with that name exists in storage. This is a bare key-existence check, so a deactivated queue still blocks creation until its record ages out.

deactivateQueue¶

void deactivateQueue(String queueName)

Stops all consumers for the queue, removes it from the in-memory map, and sets active=false in the database.

[!CAUTION] This operation is irreversible. The queue cannot be reactivated after deactivation.

increaseConsumers¶

void increaseConsumers(String queueName, int count)

Schedules count additional consumer tasks for the queue on the shared worker pool, and updates the concurrency value in the database. These are scheduled tasks, not threads and not Timers - java.util.Timer was removed in 2.0.

decreaseConsumers¶

void decreaseConsumers(String queueName, int count)

Cancels count of the queue's scheduled consumer tasks and updates the concurrency value in the database.

scheduleShoveling¶

void scheduleShoveling(String queueName, ShovelConfig shovelConfig)

Schedules periodic shoveling for the queue using the interval and concurrency defined in shovelConfig.

sweepQueue¶

void sweepQueue(String queueName)

Manually triggers a sweep operation for the specified queue.

refreshQueues¶

void refreshQueues()

Synchronizes the in-memory queue map with the persisted state in the database. Creates or removes queue instances as needed.

getTaskInitializer¶

TaskInitializer getTaskInitializer()

Returns the internal TaskInitializer, which owns leader election and the sweeper schedule. Consumers are not scheduled here - MagazineQueue schedules those on the worker pool.

MessageHandler<M>¶

public interface MessageHandler<M>

User-implemented interface for processing messages consumed from a queue.

Methods¶

CreateQueueRequest¶

@Data
public class CreateQueueRequest

Request object for creating a new queue via IgnisMQManager.createQueue().

Fields¶

[!IMPORTANT] Validation requires queueExpiry >= messageExpiry. Both queueExpiry and messageExpiry must resolve to valid durations within the allowed maximum.

ShovelConfig¶

@Data @Builder @AllArgsConstructor
public class ShovelConfig

Configuration for periodic shoveling of sidelined messages back into the queue.

Fields¶

BatchingConfig¶

@Data @Builder @AllArgsConstructor
public class BatchingConfig

Configuration for batch message consumption.

Fields¶

TimeToLive¶

@Getter
public class TimeToLive

Represents a duration with a unit, used for message and queue expiry.

Fields¶

Methods¶

[!NOTE] Maximum allowed value after conversion is 31,536,000 seconds (1 year).

TimeUnit¶

public enum TimeUnit {
    MINUTE,
    HOUR,
    DAY
}

QueueMetaData¶

@Data @Builder @AllArgsConstructor @NoArgsConstructor
public class QueueMetaData

Fields¶

ShardDepth¶

One shard's share of a queue, using the same pointers QueueMetaData totals.

Fields¶

Obtained from IQueue.getShardDepths(), or over HTTP from the console's GET /ignismq/v1/queues/{name}/shards. Shards are assigned at random on publish, so this is a view of whether any shard is falling behind — not of key distribution, of which there is none.

QueueEntity¶

@Data @Builder @AllArgsConstructor @NoArgsConstructor
public class QueueEntity

Persistent representation of a queue stored in Aerospike.

Fields¶

BaseStorage¶

public abstract sealed class BaseStorage permits AerospikeStorage

Abstract base for storage backends.

Fields¶

Methods¶

AerospikeStorage¶

public final class AerospikeStorage extends BaseStorage

Aerospike-backed storage implementation.

Fields¶

Constructor¶

public AerospikeStorage(AerospikeConfiguration configuration, String namespace)

StorageClient\<T>¶

public interface StorageClient<T>

Generic interface for obtaining a database client handle.

Methods¶

AerospikeStoreClient¶

public final class AerospikeStoreClient implements StorageClient<IAerospikeClient>

Aerospike client wrapper that auto-starts on construction.

Constructor¶

public AerospikeStoreClient(AerospikeConfiguration aerospikeConfiguration)

[!NOTE] The client starts automatically on construction. Write policy is configured with COMMIT_ALL commit level and MASTER_PROLES replica policy.

QueueService¶

public sealed interface QueueService permits AerospikeQueueService

Internal service interface for queue persistence operations.

Methods¶

IgnisMQBundle\<T>¶

public abstract class IgnisMQBundle<T extends Configuration> implements ConfiguredBundle<T>

Dropwizard bundle for integrating IgnisMQ into a Dropwizard application.

Abstract Method¶

IgnisMQContext¶

Built with IgnisMQContext.builder().

Required fields are @NonNull, so a missing one throws NullPointerException when the context is built.

Methods¶

IgnisMQException¶

public class IgnisMQException extends RuntimeException

Fields¶

Static Methods¶

ErrorCode¶

public enum ErrorCode

QueueStat¶

@Data @Builder
public class QueueStat

Fields¶

Constants¶

The constants that affect behaviour a caller can observe. Constants.java also holds set-name formats, sweep batch sizes and fire-history sizing that are internal to the storage layout: