com.rabbitmq.client.amqp.Management Maven / Gradle / Ivy
Show all versions of amqp-client Show documentation
// Copyright (c) 2024 Broadcom. All Rights Reserved.
// The term "Broadcom" refers to Broadcom Inc. and/or its subsidiaries.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
//
// If you have any questions regarding licensing, please contact us at
// [email protected].
package com.rabbitmq.client.amqp;
import java.time.Duration;
import java.util.List;
import java.util.Map;
/**
* API to manage AMQ 0.9.1 model topology (exchanges, queues, and bindings).
*
* @see AMQ 0.9.1 Model
*/
public interface Management extends AutoCloseable {
/**
* Start queue specification.
*
* @return the queue specification
*/
QueueSpecification queue();
/**
* Start queue specification.
*
* @param name the name of the queue
* @return the queue specification
*/
QueueSpecification queue(String name);
/**
* Query information on a queue.
*
* @param name the name of the queue
* @return the queue information
*/
QueueInfo queueInfo(String name);
/**
* Delete a queue.
*
* @return the queue deletion
*/
QueueDeletion queueDeletion();
/**
* Start exchange specification.
*
* @return the exchange specification
*/
ExchangeSpecification exchange();
/**
* Start exchange specification.
*
* @param name the name of the exchange
* @return the exchange specification
*/
ExchangeSpecification exchange(String name);
/**
* Delete an exchange.
*
* @return the exchange deletion
*/
ExchangeDeletion exchangeDeletion();
/**
* Start binding specification.
*
* @return the binding definition
*/
BindingSpecification binding();
/**
* Start unbinding specification.
*
* @return the unbinding specification
*/
UnbindSpecification unbind();
/** Close the management instance and release its resources. */
@Override
void close();
/**
* Specification to create a queue.
*
* @see Queues
*/
interface QueueSpecification {
/**
* The name of the queue.
*
* The library will generate a random name if no name is specified.
*
* @param name name
* @return the queue specification
*/
QueueSpecification name(String name);
/**
* Whether the queue is exclusive or not.
*
* @param exclusive exclusive flag
* @return the queue specification
* @see Queue Properties
*/
QueueSpecification exclusive(boolean exclusive);
/**
* Whether the queue get automatically deleted when its last consumer unsubscribes.
*
* @param autoDelete auto-delete flag
* @return the queue specification
* @see Queue Properties
*/
QueueSpecification autoDelete(boolean autoDelete);
/**
* The type of the queue.
*
* @param type queue type
* @return the queue specification
* @see Queue Arguments
*/
QueueSpecification type(QueueType type);
/**
* The dead letter exchange.
*
* @param dlx dead letter exchange
* @return the queue specification
* @see Dead Letter Exchange
*/
QueueSpecification deadLetterExchange(String dlx);
/**
* The dead letter routing key.
*
* @param dlrk dead letter exchange
* @return the queue specification
* @see Dead Letter Exchange
*/
QueueSpecification deadLetterRoutingKey(String dlrk);
/**
* The overflow strategy (as a string).
*
* @param overflow the overflow strategy
* @return the queue specification
* @see TTL and Length Limit
*/
QueueSpecification overflowStrategy(String overflow);
/**
* The overflow strategy.
*
* @param overflow overflow strategy
* @return the queue specification
* @see TTL and Length Limit
* @see Overflow
* Behavior
*/
QueueSpecification overflowStrategy(OverFlowStrategy overflow);
/**
* Set TTL for a queue.
*
* @param expiration expiration
* @return the queue specification
* @see Queue TTL
*/
QueueSpecification expires(Duration expiration);
/**
* Maximum length for a queue.
*
* @param maxLength maximum length
* @return the queue specification
* @see Queue Length Limit
*/
QueueSpecification maxLength(long maxLength);
/**
* Maximum length in bytes for a queue.
*
* @param maxLengthBytes maximum length in bytes
* @return the queue specification
* @see Queue Length Limit
*/
QueueSpecification maxLengthBytes(ByteCapacity maxLengthBytes);
/**
* Activate "single active consumer" on the queue.
*
* @param singleActiveConsumer activation flag
* @return the queue specification
* @see Single Active
* Consumer
*/
QueueSpecification singleActiveConsumer(boolean singleActiveConsumer);
/**
* Set the message TTL for the queue.
*
* @param ttl message TTL
* @return the queue specification
* @see Message TTL for
* Queues
*/
QueueSpecification messageTtl(Duration ttl);
/**
* Leader-locator strategy (replica placement) for the queue.
*
* @param locator locator strategy
* @return the queue specification
* @see Replica
* Placement
*/
QueueSpecification leaderLocator(QueueLeaderLocator locator);
/**
* Set the type to {@link QueueType#QUORUM} and return quorum-queue-specific specification.
*
* @return quorum queue specification
* @see Quorum Queues
*/
QuorumQueueSpecification quorum();
/**
* Set the type to {@link QueueType#CLASSIC} and return classic-queue-specific specification.
*
* @return classic queue specification
* @see Classic Queues
*/
ClassicQueueSpecification classic();
/**
* Set the type to {@link QueueType#STREAM} and return stream-specific specification.
*
* @return stream specification
* @see Streams
*/
StreamSpecification stream();
/**
* Set a queue argument.
*
* @param key argument name
* @param value argument value
* @return the queue specification
* @see Queue Arguments
*/
QueueSpecification argument(String key, Object value);
/**
* Declare the queue.
*
* @return information on the queue
*/
QueueInfo declare();
}
/**
* Specification of a quorum queue.
*
* @see Quorum Queues
*/
interface QuorumQueueSpecification {
/**
* The dead letter strategy (as a string).
*
* @param strategy dead letter strategy
* @return quorum queue specification
* @see Quorum Queue Dead
* Lettering
*/
QuorumQueueSpecification deadLetterStrategy(String strategy);
/**
* The dead letter strategy.
*
* @param strategy dead letter strategy
* @return quorum queue specification
* @see Quorum Queue Dead
* Lettering
*/
QuorumQueueSpecification deadLetterStrategy(QuorumQueueDeadLetterStrategy strategy);
/**
* Set the delivery limit (for poison message handling).
*
* @param limit delivery limit
* @return quorum queue specification
* @see Poison
* Message Handling
*/
QuorumQueueSpecification deliveryLimit(int limit);
/**
* Set the number of quorum queue members.
*
* @param size group size
* @return quorum queue specification
* @see Initial
* Replication Factor
*/
QuorumQueueSpecification quorumInitialGroupSize(int size);
/**
* Go back to the queue specification.
*
* @return queue specification
*/
QueueSpecification queue();
}
/**
* Specification of a classic queue.
*
* @see Classic Queues
*/
interface ClassicQueueSpecification {
/**
* Declare a priority queue and set the maximum priority.
*
* @param maxPriority maximum priority
* @return classic queue specification
* @see Priority Queue
*/
ClassicQueueSpecification maxPriority(int maxPriority);
/**
* Set the version of the classic queue implementation.
*
* @param version implementation version
* @return classic queue specification
* @see Classic
* Queue Version 2
* @see Classic Queue
* Version
*/
ClassicQueueSpecification version(ClassicQueueVersion version);
/**
* Go back to the queue specification.
*
* @return queue specification
*/
QueueSpecification queue();
}
/**
* Specification of a stream.
*
* @see Streams
*/
interface StreamSpecification {
/**
* Set the maximum age of a stream before it gets truncated.
*
* @param maxAge maximum age
* @return the stream specification
* @see Data Retention
*/
StreamSpecification maxAge(Duration maxAge);
/**
* Set the maximum size for the stream segment files.
*
* @param maxSegmentSize
* @return the stream specification
* @see Declaring a Stream
*/
StreamSpecification maxSegmentSizeBytes(ByteCapacity maxSegmentSize);
/**
* Set the number of nodes the initial stream cluster should span.
*
* @param initialClusterSize initial number of nodes
* @return the stream specification
* @see Initial Replication
* Factor
*/
StreamSpecification initialClusterSize(int initialClusterSize);
/**
* Go back to the queue specification.
*
* @return queue specification
*/
QueueSpecification queue();
}
/**
* Dead letter strategy for quorum queues.
*
* @see Quorum Queue Dead
* Lettering
* @see Dead Lettering Safety
*/
enum QuorumQueueDeadLetterStrategy {
/**
* At-most-once strategy, dead-lettered messages can be lost in transit.
*
*
The default strategy.
*/
AT_MOST_ONCE("at-most-once"),
/**
* At-least-once strategy, guarantees for the message transfer between queues (with some
* caveats).
*
* @see At-least-once
* Dead Lettering
* @see Limitions
* @see Caveats
*/
AT_LEAST_ONCE("at-least-once");
private final String strategy;
QuorumQueueDeadLetterStrategy(String strategy) {
this.strategy = strategy;
}
public String strategy() {
return strategy;
}
}
/**
* Overflow strategy (when a queue reaches its maximum length limit).
*
* @see Overflow Behavior
*/
enum OverFlowStrategy {
/** Drop the messages at the head of the queue. The default strategy. */
DROP_HEAD("drop-head"),
/** Discard the most recent published messages. */
REJECT_PUBLISH("reject-publish"),
/** Discard the most recent published messages and dead-letter them. */
REJECT_PUBLISH_DLX("reject-publish-dlx");
private final String strategy;
OverFlowStrategy(String strategy) {
this.strategy = strategy;
}
public String strategy() {
return strategy;
}
}
/** Queue Type. */
enum QueueType {
/**
* Quorum queue.
*
* @see Quorum Queues
*/
QUORUM,
/**
* Classic queue.
*
* @see Classic Queues
*/
CLASSIC,
/**
* Stream.
*
* @see Streams
*/
STREAM
}
/**
* Queue leader locator.
*
* @see Replica Placement
*/
enum QueueLeaderLocator {
/**
* Pick the node the client is connected to.
*
*
The default.
*/
CLIENT_LOCAL("client-local"),
/**
* Takes into account the number of queues/leaders already running on each node in the cluster.
*/
BALANCED("balanced");
private final String locator;
QueueLeaderLocator(String locator) {
this.locator = locator;
}
public String locator() {
return locator;
}
}
/**
* Classic queue version.
*
* @see Classic
* Queue Version 2
* @see Classic Queue
* Version
*/
enum ClassicQueueVersion {
/** Classic queue version 1. */
V1(1),
/** Classic queue version 2. */
V2(2);
private final int version;
ClassicQueueVersion(int version) {
this.version = version;
}
public int version() {
return version;
}
}
/** Queue deletion. */
interface QueueDeletion {
/**
* Delete the queue.
*
* @param name queue name
*/
void delete(String name);
}
/**
* Specification of an exchange.
*
* @see Exchanges
*/
interface ExchangeSpecification {
/**
* The name of the exchange.
*
* @param name exchange name
* @return the exchange specification
*/
ExchangeSpecification name(String name);
/**
* Whether the exchange is deleted when last queue is unbound from it.
*
* @param autoDelete auto-delete flag.
* @return the exchange specification
*/
ExchangeSpecification autoDelete(boolean autoDelete);
/**
* Type of the exchange.
*
* @param type exchange type
* @return the exchange specification
*/
ExchangeSpecification type(ExchangeType type);
/**
* Type of the exchange (as a string, for non-built-in exchange types).
*
* @param type exchange type
* @return the exchange specification
*/
ExchangeSpecification type(String type);
/**
* Exchange argument.
*
* @param key argument name
* @param value argument value
* @return the exchange specification
*/
ExchangeSpecification argument(String key, Object value);
/** Declare the exchange. */
void declare();
}
/**
* Exchange type.
*
* @see Exchange Types
*/
enum ExchangeType {
/**
* Direct exchange type.
*
* @see Direct
* Exchange Type
*/
DIRECT,
/**
* Fanout exchange type.
*
* @see Fanout
* exchange type
*/
FANOUT,
/**
* Topic exchange type.
*
* @see Topic Exchange
* Type
*/
TOPIC,
/**
* Headers Exchange Type.
*
* @see Headers
* Exchange Type
*/
HEADERS
}
/** Exchange deletion. */
interface ExchangeDeletion {
/**
* Delete the exchange.
*
* @param name exchange name
*/
void delete(String name);
}
/**
* Specification of a binding.
*
* @see Bindings
* @see Exchange-to-exchange binding
*/
interface BindingSpecification {
/**
* The source exchange.
*
* @param exchange exchange
* @return the binding specification
*/
BindingSpecification sourceExchange(String exchange);
/**
* The destination queue.
*
* @param queue queue
* @return the binding specification
*/
BindingSpecification destinationQueue(String queue);
/**
* The destination exchange.
*
* @param exchange exchange
* @return the binding specification
* @see Exchange-to-exchange binding
*/
BindingSpecification destinationExchange(String exchange);
/**
* The binding key.
*
* @param key binding key
* @return the binding specification
*/
BindingSpecification key(String key);
/**
* Binding argument.
*
* @param key argument name
* @param value argument value
* @return the binding specification
*/
BindingSpecification argument(String key, Object value);
/**
* Binding arguments.
*
* @param arguments arguments
* @return the binding specification
*/
BindingSpecification arguments(Map arguments);
/** Create the binding. */
void bind();
}
/** Unbind specification. */
interface UnbindSpecification {
/**
* The source exchange.
*
* @param exchange exchange
* @return the unbind specification
*/
UnbindSpecification sourceExchange(String exchange);
/**
* The destination queue.
*
* @param queue queue
* @return the unbind specification
*/
UnbindSpecification destinationQueue(String queue);
/**
* The destination exchange.
*
* @param exchange
* @return the unbind specification
* @see Exchange-to-exchange binding
*/
UnbindSpecification destinationExchange(String exchange);
/**
* The binding key.
*
* @param key binding key
* @return the unbind specification
*/
UnbindSpecification key(String key);
/**
* A binding argument.
*
* @param key argument name
* @param value argument value
* @return the unbind specification
*/
UnbindSpecification argument(String key, Object value);
/**
* Binding arguments.
*
* @param arguments arguments
* @return the unbind specification
*/
UnbindSpecification arguments(Map arguments);
/** Delete the binding. */
void unbind();
}
/**
* Queue information.
*
* @see Queues
* @see Queue Properties
*/
interface QueueInfo {
/**
* The name of the queue.
*
* @return queue name
*/
String name();
/**
* Whether the queue is durable (will survive a server restart).
*
* @return the durable flag
*/
boolean durable();
/**
* Whether the queue is deleted when last consumer unsubscribes.
*
* @return the auto-delete flag
*/
boolean autoDelete();
/**
* Whether the queue is used by only one connection and will be deleted when that connection
* closes.
*
* @return the exclusive flag
*/
boolean exclusive();
/**
* The type of the queue.
*
* @return the queue type
*/
QueueType type();
/**
* The arguments of the queue.
*
* @return the queue arguments
*/
Map arguments();
/**
* The node the leader of the queue is on.
*
* @return the node of the queue leader
*/
String leader();
/**
* The nodes the queue has replicas (members) on.
*
* @return the nodes of the queue replicas (members)
*/
List replicas();
/**
* The number of messages in the queue.
*
* @return the queue message count
*/
long messageCount();
/**
* The number of consumers the queue has.
*
* @return the queue consumer count
*/
int consumerCount();
}
}