rabbitmq / Hop
Programming Languages
Projects that are alternatives of or similar to Hop
:rabbitmq-version: 3.8.9 :hop-version: 3.9.0.RELEASE :spring-version: 5.3.0 :jackson-version: 2.11.3 :reactor-netty-version: 1.0.0 :http-client-version: 4.5.13 :okhttp-version: 3.14.9
= Hop, Java Client for the RabbitMQ HTTP API
image:https://github.com/rabbitmq/hop/workflows/Build%20(Linux)/badge.svg?branch=master["Build Status", link="https://github.com/rabbitmq/hop/actions?query=workflow%3A%22Build+%28Linux%29%22+branch%3Amaster"]
Hop is a Java client for the https://raw.githack.com/rabbitmq/rabbitmq-management/v{rabbitmq-version}/priv/www/api/index.html[RabbitMQ HTTP API].
== Polyglot
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 http://clojurerabbitmq.info[Langohr], and you should use Langohr instead.
== Reactive
As of Hop 2.1.0, a new reactive, non-blocking IO client based on https://projectreactor.io/[Reactor Netty] is available. Note the original blocking IO client remains available.
== Project Maturity
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.
== Maven Artifacts
image:https://maven-badges.herokuapp.com/maven-central/com.rabbitmq/http-client/badge.svg["Maven Central", link="https://maven-badges.herokuapp.com/maven-central/com.rabbitmq/http-client"]
Project artifacts are available from Maven Central and https://repo.spring.io[repo.spring.io].
=== Maven
If you want to use the blocking IO client, add the following dependencies:
com.rabbitmq http-client {hop-version} org.springframework spring-web {spring-version} com.fasterxml.jackson.core jackson-databind {jackson-version} ---- .pom.xml [source,xml,subs="attributes,specialcharacters"]
If you want to use the reactive, non-blocking IO client, add the following dependencies:
com.rabbitmq http-client {hop-version} io.projectreactor.netty reactor-netty {reactor-netty-version} com.fasterxml.jackson.core jackson-databind {jackson-version} ---- .pom.xml [source,xml,subs="attributes,specialcharacters"]
=== Gradle
If you want to use the blocking IO client, add the following dependencies:
.build.gradle [source,groovy,subs="attributes,specialcharacters"]
compile "com.rabbitmq:http-client:{hop-version}" compile "org.springframework:spring-web:{spring-version}" compile "com.fasterxml.jackson.core:jackson-databind:{jackson-version}"
If you want to use the reactive, non-blocking IO client, add the following dependencies:
.build.gradle [source,groovy,subs="attributes,specialcharacters"]
compile "com.rabbitmq:http-client:{hop-version}" compile "io.projectreactor.netty:reactor-netty:{reactor-netty-version}" compile "com.fasterxml.jackson.core:jackson-databind:{jackson-version}"
=== Milestones and Release Candidates
Milestones and release candidates are available on the RabbitMQ Milestone Repository:
Maven:
packagecloud-rabbitmq-maven-milestones https://packagecloud.io/rabbitmq/maven-milestones/maven2 true false ---- .pom.xml [source,xml,subs="attributes,specialcharacters"]
Gradle:
.build.gradle [source,groovy,subs="attributes,specialcharacters"]
https://packagecloud.io/rabbitmq/maven-milestones/maven2" } }
repositories { maven { url "== Usage Guide
=== Instantiating a Client
Hop faithfully follows RabbitMQ HTTP API conventions in its API. You interact with the server
using a single class, Client
, which needs an API endpoint and
a pair of credentials to be instantiated:
[source,java]
import com.rabbitmq.http.client.Client; import com.rabbitmq.http.client.ClientParameters;
http://127.0.0.1:15672/api/") .username("guest") .password("guest") );
Client c = new Client( new ClientParameters() .url("=== HTTP Layer
The HTTP layer used by the Client
is pluggable. The Client(ClientParameters)
constructor
uses standard JDK HTTP facilities by default, but
https://hc.apache.org/[Apache HTTP Components] and https://square.github.io/okhttp/[OkHttp]
are also supported.
==== Apache HTTP Components
To use Apache HTTP Components, use an HttpComponentsRestTemplateConfigurator
instance when creating the client:
[source,java]
http://localhost:15672/api").username("guest").password("guest") .restTemplateConfigurator(new HttpComponentsRestTemplateConfigurator()) );
Client client = new Client( new ClientParameters().url("This requires to add Apache HTTP Components on the classpath.
For Maven:
org.apache.httpcomponents httpclient {http-client-version} ---- .pom.xml [source,xml,subs="attributes,specialcharacters"]
For Gradle:
.build.gradle [source,groovy,subs="attributes,specialcharacters"]
compile "org.apache.httpcomponents:httpclient:{http-client-version}"
==== OkHttp
To use OkHttp, use an OkHttpRestTemplateConfigurator
instance when creating the client:
[source,java]
http://localhost:15672/api").username("guest").password("guest") .restTemplateConfigurator(new OkHttpRestTemplateConfigurator()) );
Client client = new Client( new ClientParameters().url("This requires to add OkHttp on the classpath.
For Maven:
com.squareup.okhttp3 okhttp {okhttp-version} ---- .pom.xml [source,xml,subs="attributes,specialcharacters"]
For Gradle:
.build.gradle [source,groovy,subs="attributes,specialcharacters"]
compile "com.squareup.okhttp3:okhttp:{okhttp-version}"
=== Getting Overview
[source,java]
c.getOverview();
=== Node and Cluster Status
[source,java]
// list cluster nodes c.getNodes();
[email protected]");
// get status and metrics of individual node c.getNode("=== Operations on Connections
[source,java]
// 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
[source,java]
// 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
[source,java]
// get status and metrics of individual vhost c.getVhost("/");
=== Managing Users
TBD
=== Managing Permissions
TBD
=== Operations on Exchanges
TBD
=== Operations on Queues
[source,java]
// 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
[source,java]
// 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");
== Running Tests (with Docker)
Start the broker:
docker run -it --rm --name rabbitmq -p 5672:5672 -p 15672:15672 rabbitmq:3.8-management
Configure the broker for the test suite:
export HOP_RABBITMQCTL="DOCKER:rabbitmq"
./bin/before_build.sh
Launch the test suite:
./mvnw test
== Running Tests
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:
./bin/before_build.sh
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:
./mvnw test
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:
./mvnw test -Drabbitmq.management.port=15673
== Versioning
This library uses https://semver.org/[semantic versioning].
== Support
See the https://www.rabbitmq.com/java-versions.html[RabbitMQ Java libraries support page] for the support timeline of this library.
== License
https://www.apache.org/licenses/LICENSE-2.0.html[Apache 2.0].
== Copyright
Michael Klishin, 2014-2016.
VMware, Inc. or its affiliates, 2014-2020.