Hop is a Java client for the RabbitMQ HTTP API.

Hop is designed to be easy to use from other JVM languages, primarily Groovy, Scala, and Kotlin.

N.B. that Clojure already includes an HTTP API client as part of Langohr, and you should use Langohr instead.

As of Hop 2.1.0, a new reactive, non-blocking IO client based on Reactor Netty is available. Note the original blocking IO client remains available.

This project is mature and covers all key RabbitMQ HTTP API endpoints.

Meaningful breaking API changes are reflected in the version. User documentation is currently kept in this README.

As of 4.0, Hop requires Java 11 or later.

Project artifacts are available from Maven Central.

For milestones and release candidates, declare the milestone repository in your dependency manager.

Dependency Manager Configuration

<dependency>
  <groupId>com.rabbitmq</groupId>
  <artifactId>http-client</artifactId>
  <version>5.0.0</version>
</dependency>
<dependency>
  <groupId>com.fasterxml.jackson.core</groupId>
  <artifactId>jackson-databind</artifactId>
  <version>2.15.2</version>
</dependency>

compile "com.rabbitmq:http-client:5.0.0"
compile "com.fasterxml.jackson.core:jackson-databind:2.15.2"

<dependency>
  <groupId>com.rabbitmq</groupId>
  <artifactId>http-client</artifactId>
  <version>5.0.0</version>
</dependency>
<dependency>
  <groupId>io.projectreactor.netty</groupId>
  <artifactId>reactor-netty</artifactId>
  <version>1.1.0</version>
</dependency>
<dependency>
  <groupId>com.fasterxml.jackson.core</groupId>
  <artifactId>jackson-databind</artifactId>
  <version>2.15.2</version>
</dependency>

compile "com.rabbitmq:http-client:5.0.0"
compile "io.projectreactor.netty:reactor-netty:1.1.0"
compile "com.fasterxml.jackson.core:jackson-databind:2.15.2"

Milestones and Release Candidates

<repositories>
  <repository>
    <id>packagecloud-rabbitmq-maven-milestones</id>
    <url>https://packagecloud.io/rabbitmq/maven-milestones/maven2</url>
    <releases>
      <enabled>true</enabled>
    </releases>
    <snapshots>
      <enabled>false</enabled>
    </snapshots>
  </repository>
</repositories>

repositories {
  maven {
    url "https://packagecloud.io/rabbitmq/maven-milestones/maven2"
  }
}

Snapshots

<dependency>
  <groupId>com.rabbitmq</groupId>
  <artifactId>http-client</artifactId>
  <version>5.1.0-SNAPSHOT</version>
</dependency>
<dependency>
  <groupId>com.fasterxml.jackson.core</groupId>
  <artifactId>jackson-databind</artifactId>
  <version>2.15.2</version>
</dependency>

compile "com.rabbitmq:http-client:5.1.0-SNAPSHOT"
compile "com.fasterxml.jackson.core:jackson-databind:2.15.2"

<repositories>
  <repository>
    <id>ossrh</id>
    <url>https://oss.sonatype.org/content/repositories/snapshots</url>
    <snapshots>
      <enabled>true</enabled>
    </snapshots>
    <releases>
      <enabled>false</enabled>
    </releases>
  </repository>
</repositories>

repositories {
  maven { url 'https://oss.sonatype.org/content/repositories/snapshots' }
  mavenCentral()
}

Instantiating a Client

import com.rabbitmq.http.client.Client;
import com.rabbitmq.http.client.ClientParameters;

Client c = new Client(
  new ClientParameters()
    .url("http://127.0.0.1:15672/api/")
    .username("guest")
    .password("guest")
);

HTTP Layer (Synchronous Client)

HttpLayerFactory httpLayerFactory =
  JdkHttpClientHttpLayer.configure()  // (1)
    .clientBuilderConsumer(
      clientBuilder ->  // (2)
        clientBuilder
          .connectTimeout(Duration.ofSeconds(10)))
    .requestBuilderConsumer(
      requestBuilder ->  // (3)
        requestBuilder
          .timeout(Duration.ofSeconds(10))
          .setHeader("Authorization", authorization("guest", "guest")))
    .create();  // (4)

Client c =
    new Client(
        new ClientParameters()
            .url("http://127.0.0.1:15672/api/")
            .username("guest")
            .password("guest")
            .httpLayerFactory(httpLayerFactory));  // (5)

SSLContext sslContext = SSLContext.getInstance("TLSv1.3");  // (1)
sslContext.init(kmf.getKeyManagers(), tmf.getTrustManagers(), random);  // (2)
HttpLayerFactory factory =
  JdkHttpClientHttpLayer.configure()
    .clientBuilderConsumer(builder -> builder.sslContext(sslContext))  // (3)
    .create();

Getting Overview

c.getOverview();

Node and Cluster Status

// list cluster nodes
c.getNodes();

// get status and metrics of individual node
c.getNode("[email protected]");

Operations on Connections

// list client connections
c.getConnections();

// get status and metrics of individual connection
c.getConnection("127.0.0.1:61779 -> 127.0.0.1:5672");

// forcefully close connection
c.closeConnection("127.0.0.1:61779 -> 127.0.0.1:5672");

Operations on Channels

// list all channels
c.getChannels();

// list channels on individual connection
c.getChannels("127.0.0.1:61779 -> 127.0.0.1:5672");

// list detailed channel info
c.getChannel("127.0.0.1:61779 -> 127.0.0.1:5672 (3)");

Operations on Vhosts

// get status and metrics of individual vhost
c.getVhost("/");

Managing Users

Managing Permissions

Operations on Exchanges

Operations on Queues

// list all queues
c.getQueues();

// list all queues in a vhost
c.getQueues();

// declare a queue that's not durable, auto-delete,
// and non-exclusive
c.declareQueue("/", "queue1", new QueueInfo(false, true, false));

// bind a queue
c.bindQueue("/", "queue1", "amq.fanout", "routing-key");

// delete a queue
c.deleteQueue("/", "queue1");

Operations on Bindings

// list bindings where exchange "an.exchange" is source
// (other things are bound to it)
c.getBindingsBySource("/", "an.exchange");

// list bindings where exchange "an.exchange" is destination
// (it is bound to other exchanges)
c.getBindingsByDestination("/", "an.exchange");

Start the broker:

Configure the broker for the test suite:

Launch the test suite:

To run the suite against a specific RabbitMQ node, export HOP_RABBITMQCTL and HOP_RABBITMQ_PLUGINS to point at rabbitmqctl and rabbitmq-plugins from the installation.

Then set up the node that is assumed to be running:

This will enable several plugins used by the test suite and configure the node to use a much shorter event refresh interval so that HTTP API reflects system state changes with less of a delay.

To run the tests:

The test suite assumes RabbitMQ is running locally with stock settings and a few plugins are enabled:

• rabbitmq_management (listening on port 15672)

• rabbitmq_shovel_management

• rabbitmq_federation_management

To run the suite against a specific RabbitMQ node, export HOP_RABBITMQCTL and HOP_RABBITMQ_PLUGINS to point at rabbitmqctl and rabbitmq-plugins from the installation.

The test suite can use a different port than 15672 by specifying it with the rabbitmq.management.port system property:

This library uses semantic versioning.

See the RabbitMQ Java libraries support page for the support timeline of this library.

Apache 2.0.

Michael Klishin, 2014-2016.

VMware, Inc. or its affiliates, 2014-2022.