org.eclipse.hono.client.device.amqp.EventSender Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of hono-client-device-amqp Show documentation
Clients used by devices exchanging messages with a Hono AMQP protocol adapter.
The newest version!
/*******************************************************************************
 * Copyright (c) 2020, 2022 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.client.device.amqp;

import io.opentracing.SpanContext;
import io.vertx.core.Future;
import io.vertx.core.buffer.Buffer;
import io.vertx.proton.ProtonDelivery;

/**
 * A client for sending event messages to Hono's AMQP adapter.
 *
 * @see AMQP Adapter User Guide
 */
public interface EventSender {

    /**
     * Sends an event message.
     *
     * @param payload The data to send.
     *            
     *            The payload, if not {@code null}, will be added to the message's body as an AMQP 1.0 Data section.
     * @param contentType The content type of the payload or {@code null} if unknown.
     *            

     *            This parameter will be used as the value for the message's content-type property.
     * @param tenantId The tenant that the device belongs to or {@code null} to determine the tenant from 
     *                 the device that has authenticated to the AMQP adapter.
     *                 Unauthenticated clients must provide a non-{@code null} value to indicate the tenant of the
     *                 device that the message originates from.
     * @param deviceId The identifier of the device that the message originates from or {@code null} if the
     *                 message originates from the device that has authenticated to the AMQP adapter.
     *                 Authenticated gateway devices can use this parameter to send a message on behalf of
     *                 another device.
     *                 Unauthenticated clients must provide a non-{@code null} value to indicate the device that
     *                 the message  originates from.
     * @param context The OpenTracing context to use for tracking the execution of the operation (may be {@code null}).
     * @return A future indicating the outcome of the operation.
     *         

     *         The future will succeed if the message has been accepted (and settled) by the peer.
     *         
     *         The future will be failed with a {@link org.eclipse.hono.client.ServerErrorException} if the message
     *         could not be sent due to a lack of credit. If an event is sent which cannot be processed by the peer
     *         the future will be failed with either a {@code org.eclipse.hono.client.ServerErrorException} or a
     *         {@link org.eclipse.hono.client.ClientErrorException} depending on the reason for the failure to
     *         process the message.
     * @throws IllegalArgumentException if tenant ID is not {@code null} but device ID is {@code null}.
     */
    Future sendEvent(
            Buffer payload,
            String contentType,
            String tenantId,
            String deviceId,
            SpanContext context);
}