io.vertx.core.eventbus.Message Maven / Gradle / Ivy
/*
* Copyright (c) 2011-2019 Contributors to the Eclipse Foundation
*
* 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, or the Apache License, Version 2.0
* which is available at https://www.apache.org/licenses/LICENSE-2.0.
*
* SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
*/
package io.vertx.core.eventbus;
import io.vertx.codegen.annotations.CacheReturn;
import io.vertx.codegen.annotations.Nullable;
import io.vertx.codegen.annotations.VertxGen;
import io.vertx.core.AsyncResult;
import io.vertx.core.Future;
import io.vertx.core.Handler;
import io.vertx.core.MultiMap;
/**
* Represents a message that is received from the event bus in a handler.
*
* Messages have a {@link #body}, which can be null, and also {@link #headers}, which can be empty.
*
* If the message was sent specifying a reply handler, it can be replied to using {@link #reply}.
*
* If you want to notify the sender that processing failed, then {@link #fail} can be called.
*
* @author Tim Fox
*/
@VertxGen
public interface Message {
/**
* The address the message was sent to
*/
String address();
/**
* Multi-map of message headers. Can be empty
*
* @return the headers
*/
MultiMap headers();
/**
* The body of the message. Can be null.
*
* @return the body, or null.
*/
@CacheReturn
T body();
/**
* The reply address. Can be null.
*
* @return the reply address, or null, if message was sent without a reply handler.
*/
@Nullable
String replyAddress();
/**
* Signals if this message represents a send or publish event.
*
* @return true if this is a send.
*/
boolean isSend();
/**
* Reply to this message.
*
* If the message was sent specifying a reply handler, that handler will be
* called when it has received a reply. If the message wasn't sent specifying a receipt handler
* this method does nothing.
*
* @param message the message to reply with.
*/
default void reply(@Nullable Object message) {
reply(message, new DeliveryOptions());
}
/**
* Link {@link #reply(Object)} but allows you to specify delivery options for the reply.
*
* @param message the reply message
* @param options the delivery options
*/
void reply(@Nullable Object message, DeliveryOptions options);
/**
* Reply to this message, specifying a {@code replyHandler} for the reply - i.e.
* to receive the reply to the reply.
*
* If the message was sent specifying a reply handler, that handler will be
* called when it has received a reply. If the message wasn't sent specifying a receipt handler
* this method does nothing.
*
* @param message the message to reply with.
* @param replyHandler the reply handler for the reply.
*/
default void replyAndRequest(@Nullable Object message, Handler>> replyHandler) {
replyAndRequest(message, new DeliveryOptions(), replyHandler);
}
/**
* Like {@link #replyAndRequest(Object, Handler)} but returns a {@code Future} of the asynchronous result
*/
default Future> replyAndRequest(@Nullable Object message) {
return replyAndRequest(message, new DeliveryOptions());
}
/**
* Like {@link #replyAndRequest(Object, Handler)} but specifying {@code options} that can be used
* to configure the delivery.
*
* @param message the message body, may be {@code null}
* @param options delivery options
* @param replyHandler reply handler will be called when any reply from the recipient is received
*/
default void replyAndRequest(@Nullable Object message, DeliveryOptions options, Handler>> replyHandler) {
this.replyAndRequest(message, options).onComplete(replyHandler);
}
/**
* Like {@link #replyAndRequest(Object, DeliveryOptions, Handler)} but returns a {@code Future} of the asynchronous result
*/
Future> replyAndRequest(@Nullable Object message, DeliveryOptions options);
/**
* Signal to the sender that processing of this message failed.
*
* If the message was sent specifying a result handler
* the handler will be called with a failure corresponding to the failure code and message specified here.
*
* @param failureCode A failure code to pass back to the sender
* @param message A message to pass back to the sender
*/
default void fail(int failureCode, String message) {
reply(new ReplyException(ReplyFailure.RECIPIENT_FAILURE, failureCode, message));
}
}