org.eclipse.hono.application.client.ApplicationClient Maven / Gradle / Ivy
Show all versions of hono-client-application Show documentation
/*
* Copyright (c) 2021 Contributors to the Eclipse Foundation
*
* See the NOTICE file(s) distributed with this work for additional
* information regarding copyright ownership.
*
* This program and the accompanying materials are made available under the
* terms of the Eclipse Public License 2.0 which is available at
* http://www.eclipse.org/legal/epl-2.0
*
* SPDX-License-Identifier: EPL-2.0
*/
package org.eclipse.hono.application.client;
import io.vertx.core.Future;
import io.vertx.core.Handler;
/**
* A client that supports Hono's north bound operations to send commands and receive telemetry,
* event and command response messages.
*
* @param The type of context that messages are being received in.
*/
public interface ApplicationClient extends CommandSender {
/**
* Creates a client for consuming data from Hono's north bound Telemetry API.
*
* @param tenantId The tenant to consume data for.
* @param messageHandler The handler to invoke with every message received.
* The message passed in will be acknowledged automatically if the handler does not
* throw an exception.
*
* Implementors are encouraged to specify in detail the types of exceptions that handler
* might throw, what kind of problem they indicate and what the consequences regarding
* the underlying messaging infrastructure will be.
* @param closeHandler An (optional) handler to be invoked when the consumer is being closed by the peer.
* The handler will be invoked with an exception indicating the cause of the consumer
* being closed or {@code null} if unknown.
*
* Implementors are encouraged to specify in detail the types of exceptions that might
* be passed in, what kind of problem they indicate and what the consequences regarding the
* underlying messaging infrastructure will be.
* @return A future that will complete with the consumer once it is ready. The future will fail if the consumer
* cannot be started.
* @throws NullPointerException if any of tenant ID or message handler are {@code null}.
*/
Future createTelemetryConsumer(
String tenantId,
Handler> messageHandler,
Handler closeHandler);
/**
* Creates a client for consuming events from Hono's north bound Event API.
*
* @param tenantId The tenant to consume data for.
* @param messageHandler The handler to invoke with every message received.
* The message passed in will be acknowledged automatically if the handler does not
* throw an exception.
*
* Implementors are encouraged to specify in detail the types of exceptions that handler
* might throw, what kind of problem they indicate and what the consequences regarding
* the underlying messaging infrastructure will be.
* @param closeHandler An (optional) handler to be invoked when the consumer is being closed by the peer.
* The handler will be invoked with an exception indicating the cause of the consumer
* being closed or {@code null} if unknown.
*
* Implementors are encouraged to specify in detail the types of exceptions that might
* be passed in, what kind of problem they indicate and what the consequences regarding the
* underlying messaging infrastructure will be.
* @return A future that will complete with the consumer once it is ready. The future will fail if the consumer
* cannot be started.
* @throws NullPointerException if any of tenant ID or message handler are {@code null}.
*/
Future createEventConsumer(
String tenantId,
Handler> messageHandler,
Handler closeHandler);
/**
* Creates a client for consuming command responses from Hono's north bound Command and Control API.
*
* @param tenantId The tenant to consume data for.
* @param replyId An arbitrary string which will be used to create the reply-to address and included in commands
* sent to devices of the tenant. If the messaging network specific Command & Control
* implementation does not require a replyId, the specified value will be ignored.
* @param messageHandler The handler to invoke with every message received.
* The message passed in will be acknowledged automatically if the handler does not
* throw an exception.
*
* Implementors are encouraged to specify in detail the types of exceptions that handler
* might throw, what kind of problem they indicate and what the consequences regarding
* the underlying messaging infrastructure will be.
* @param closeHandler An (optional) handler to be invoked when the consumer is being closed by the peer.
* The handler will be invoked with an exception indicating the cause of the consumer
* being closed or {@code null} if unknown.
*
* Implementors are encouraged to specify in detail the types of exceptions that might
* be passed in, what kind of problem they indicate and what the consequences regarding the
* underlying messaging infrastructure will be.
* @return A future that will complete with the consumer once it is ready. The future will fail if the consumer
* cannot be started.
* @throws NullPointerException if any of tenantId or message handler are {@code null}.
* Also if the replyId is {@code null} provided that the messaging
* network specific Command & Control implementation requires it.
*/
Future createCommandResponseConsumer(
String tenantId,
String replyId,
Handler> messageHandler,
Handler closeHandler);
}