Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/rabbitmq/hop
RabbitMQ HTTP API client for Java, Groovy, and other JVM languages
https://github.com/rabbitmq/hop
http java rabbitmq
Last synced: 6 days ago
JSON representation
RabbitMQ HTTP API client for Java, Groovy, and other JVM languages
- Host: GitHub
- URL: https://github.com/rabbitmq/hop
- Owner: rabbitmq
- Created: 2014-08-16T17:44:23.000Z (over 10 years ago)
- Default Branch: main
- Last Pushed: 2024-10-29T12:59:11.000Z (2 months ago)
- Last Synced: 2024-10-29T15:25:03.740Z (2 months ago)
- Topics: http, java, rabbitmq
- Language: Java
- Size: 2.67 MB
- Stars: 141
- Watchers: 22
- Forks: 56
- Open Issues: 16
-
Metadata Files:
- Readme: README.adoc
- License: LICENSE-2.0.txt
Awesome Lists containing this project
README
:rabbitmq-version: 4.0.0
:hop-version: 5.3.0
:jackson-version: 2.18.1
:reactor-netty-version: 1.2.0
:hop-snapshot: 5.4.0-SNAPSHOT
:jackson-for-snapshot: 2.18.1
= Hop, Java Client for the RabbitMQ HTTP API
image:https://github.com/rabbitmq/hop/actions/workflows/test.yml/badge.svg["Build Status", link="https://github.com/rabbitmq/hop/actions/workflows/test.yml"]
Hop is a Java client for the
https://raw.githack.com/rabbitmq/rabbitmq-server/v{rabbitmq-version}/deps/rabbitmq_management/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
Hop provides a reactive, non-blocking IO client based on https://projectreactor.io/[Reactor Netty].
A blocking client is available as well.
== 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.
== Pre-requisites
Hop requires Java 11 or later.
== 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.
For milestones and release candidates, declare the
<> in your dependency manager.
=== Dependency Manager Configuration
If you want to use the **blocking IO client**, add the following dependencies:
.pom.xml
[source,xml,subs="attributes,specialcharacters"]
----
com.rabbitmq
http-client
{hop-version}
com.fasterxml.jackson.core
jackson-databind
{jackson-version}
----
.build.gradle
[source,groovy,subs="attributes,specialcharacters"]
----
compile "com.rabbitmq:http-client:{hop-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:
.pom.xml
[source,xml,subs="attributes,specialcharacters"]
----
com.rabbitmq
http-client
{hop-version}
io.projectreactor.netty
reactor-netty
{reactor-netty-version}
com.fasterxml.jackson.core
jackson-databind
{jackson-version}
----
.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}"
----
[[milestone-rc-repository]]
=== Milestones and Release Candidates
Milestones and release candidates are available on the RabbitMQ Milestone Repository:
Maven:
.pom.xml
[source,xml,subs="attributes,specialcharacters"]
----
packagecloud-rabbitmq-maven-milestones
https://packagecloud.io/rabbitmq/maven-milestones/maven2
true
false
----
Gradle:
.build.gradle
[source,groovy,subs="attributes,specialcharacters"]
----
repositories {
maven {
url "https://packagecloud.io/rabbitmq/maven-milestones/maven2"
}
}
----
=== Snapshots
To use snapshots, add the following dependencies:
.pom.xml
[source,xml,subs="attributes,specialcharacters"]
----
com.rabbitmq
http-client
{hop-snapshot}
com.fasterxml.jackson.core
jackson-databind
{jackson-for-snapshot}
----
.build.gradle
[source,groovy,subs="attributes,specialcharacters"]
----
compile "com.rabbitmq:http-client:{hop-snapshot}"
compile "com.fasterxml.jackson.core:jackson-databind:{jackson-for-snapshot}"
----
Add the https://oss.sonatype.org/content/repositories/snapshots/com/rabbitmq/http-client/[Sonatype OSS snapshot repository] to your dependency manager:
Maven:
.pom.xml
[source,xml,subs="attributes,specialcharacters"]
----
ossrh
https://oss.sonatype.org/content/repositories/snapshots
true
false
----
Gradle:
.build.gradle
[source,groovy,subs="attributes,specialcharacters"]
----
repositories {
maven { url 'https://oss.sonatype.org/content/repositories/snapshots' }
mavenCentral()
}
----
== 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;
Client c = new Client(
new ClientParameters()
.url("http://127.0.0.1:15672/api/")
.username("guest")
.password("guest")
);
----
=== HTTP Layer (Synchronous Client)
The synchronous client uses https://docs.oracle.com/en/java/javase/11/docs/api/java.net.http/java/net/http/HttpClient.html[Java 11's `HttpClient`] internally.
==== Advanced Configuration
The client uses sensible defaults, but it is possible to customize the `HttpClient` instance and requests creation with `JdkHttpClientHttpLayer#configure()`:
[source,java]
----
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>
----
<1> Configure the HTTP layer factory
<2> Configure the creation of the `HttpClient` instance
<3> Configure the creation of each request
<4> Instantiate the HTTP layer factory
<5> Set the HTTP layer factory
==== TLS
Set the `SSLContext` on the `HttpClient` builder to configure TLS:
[source,java]
----
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();
----
<1> Create the SSL context
<2> Initialize the SSL context
<3> Set the SSL context on the client builder
Note the `HttpClient` enables https://tools.ietf.org/search/rfc2818#section-3.1[hostname verification] by default.
This is a good thing for security, but it can generate surprising failures.
Hostname verification can be disabled _globally_ with the https://bugs.openjdk.java.net/browse/JDK-8213309[`jdk.internal.httpclient.disableHostnameVerification` system property] for development or test purposes, but at no cost in a production environment.
=== Getting Overview
[source,java]
----
c.getOverview();
----
=== Node and Cluster Status
[source,java]
----
// list cluster nodes
c.getNodes();
// get status and metrics of individual node
c.getNode("[email protected]");
----
=== 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:
[source,sh]
----
docker run -it --rm --name rabbitmq -p 5672:5672 -p 15672:15672 rabbitmq:4.0-management
----
Configure the broker for the test suite:
[source,sh]
----
export HOP_RABBITMQCTL="DOCKER:rabbitmq"
./ci/before-build.sh
----
Launch the test suite:
[source,sh]
----
./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:
[source,sh]
----
./ci/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:
[source,sh]
----
./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:
[source,sh]
----
./mvnw test -Drabbitmq.management.port=15673
----
== Versioning
This library uses https://semver.org/[semantic versioning].
== Support
See the https://www.rabbitmq.com/client-libraries/java-versions[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
(c) Michael Klishin, 2014-2016.
(c) VMware, Inc. or its affiliates, 2014-2023.
(c) Broadcom, 2023. All Rights Reserved. The term "Broadcom" refers to Broadcom Inc. and/or its subsidiaries.