Getting Started with AMPS Queues

To add a simple queue to AMPS, add the following options to your configuration file.

First, create a transaction log that will record the messages for the queue and the state of the queue, as described in Record and Replay Messages. You add the transaction log entry if your AMPS configuration does not already have one. Otherwise, you can simply add a Topic statement or modify an existing Topic statement to record the messages. The sample below captures any JSON messages published to the Work topic, and also tracks the state of the queue itself:

<AMPSConfig>
    ...

    <TransactionLog>
         <JournalDirectory>./journals</JournalDirectory>
         <Topic>
            <Name>Work</Name>
            <MessageType>json</MessageType>
         </Topic>
         <Topic>
            <Name>WorkToDo</Name>
            <MessageType>json</MessageType>
         </Topic>
    </TransactionLog>

   ...
</AMPSConfig>

Next, declare the queue topic itself. Queues are defined in the SOW element of the AMPSConfig file, as shown below:

<AMPSConfig>
    ...

    <SOW>
        <Queue>
            <Name>WorkToDo</Name>
            <MessageType>json</MessageType>
            <Semantics>at-most-once</Semantics>
            <UnderlyingTopic>Work</UnderlyingTopic>
        </Queue>
    </SOW>

    ...
</AMPSConfig>

These simple configuration changes create an AMPS message queue. Notice that the Topic for the queue in this case is WorkToDo, which includes every message published to the underlying topic Work. You could also use a regular expression to include messages to more than one topic, or leave out the UnderlyingTopic to include only messages published to the topic with the same name as the queue.

This simple queue provides each message that arrives for the queue to at most one subscriber. After AMPS delivers the message to one subscriber, AMPS removes the message from the queue without waiting for the subscriber to acknowledge the message.

While it's easy to create a simple queue, AMPS offers a rich queuing model that is designed to meet a wide variety of queuing needs. The options are described in the following sections and the AMPS Configuration Reference.

Queue Replication Types

AMPS supports three different replication types for a queue. The configuration tag used to define a queue specifies the replication type for the queue.

Configuration Tag	Replication Type	Description	Message Ownership
Queue	Distributed queue	Fully distributed queue.	Instance that received the initial publish from an application. Other instances may request ownership.
LocalQueue	Local queue	Queue exists on a single instance, delivery guarantees only apply to that instance. Cannot be replicated.	Instance that contains the queue. No other instance may request ownership.
GroupLocalQueue	Queue replicated to specific instances, most often in the same replication Group	Distributed queue on a specific set of instances. In version 5.3.4 and higher, the instances that contain the queue must all be in the same Group or define the same GroupLocalQueueDomain tag. In earlier versions of AMPS, every queue with the same name in the replication fabric is treated as an instance of the same queue and must have the same definition and the same InitialOwner.	Instance specified in the InitialOwner tag for the queue. Other instances may request ownership.

By default, AMPS queues are distributed queues. That is, if the queue topic or the underlying topics are replicated, AMPS provides the queue delivery guarantees (that is, at-most-once or at-least-once delivery) as though all of the instances were delivering messages from a single queue.

AMPS provides local queues (where each instance has a separate, independent queue) when a queue is defined with the LocalQueue tag. In this case, AMPS does not allow replication of the queue topic, and all management of the queue is local to the individual instance.

AMPS also supports distributed queues that are restricted to a set of instances within a mesh of replicated instances. These queues are defined with the GroupLocalQueue tag, to indicate that the queue is restricted to a subset of the servers involved in replication. In this case, only the servers that define the GroupLocalQueue participate in message delivery for the queue. In addition, the group must choose the instance that will initially own messages for the queue, as described in the section on replicated queues and queue message ownership. In version 5.3.4 and later, the identity of a GroupLocalQueue is defined by the Name of the queue combined with the GroupLocalQueueDomain, if one is set, or the Group of the AMPS instance if the definition does not include a GroupLocalQueueDomain tag. In previous versions of AMPS, the identity of the queue is determined only by the Name of the group local queue, regardless of the instance that defines the queue.

When defining a GroupLocalQueue, the instances that participate in the queue do not need to be in the same replication group: any instance in a replicated mesh that defines the queue can host an instance of the queue, regardless of whether the instance is in the same replication group or not. However, if the instances that host the queue are in different groups, the queue definitions should set the same GroupLocalQueueDomain to be considered to be the same queue.

Each instance of AMPS manages its own subscriptions and backlog, regardless of the replication model. Delivery guarantees are provided by managing the ownership of each message in the queue, as described in the Replicated Queues section. Only messages owned by the current instance will be delivered to subscribers, and only the subscriptions on the current instance are considered for delivery fairness and limits such as MaxBacklog (the overall limit for leases from the queue).