/*
* 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 body
, which can be null, and also headers
, which can be empty.
If the message was sent specifying a reply handler, it can be replied to using reply
.
If you want to notify the sender that processing failed, then fail
can be called.
Author: Tim Fox
/**
* Represents a message that is received from the event bus in a handler.
* <p>
* Messages have a {@link #body}, which can be null, and also {@link #headers}, which can be empty.
* <p>
* If the message was sent specifying a reply handler, it can be replied to using {@link #reply}.
* <p>
* If you want to notify the sender that processing failed, then {@link #fail} can be called.
*
* @author <a href="http://tfox.org">Tim Fox</a>
*/
@VertxGen
public interface Message<T> {
The address the message was sent to
/**
* The address the message was sent to
*/
String address();
Multi-map of message headers. Can be empty
Returns: the headers
/**
* Multi-map of message headers. Can be empty
*
* @return the headers
*/
MultiMap headers();
The body of the message. Can be null.
Returns: the body, or null.
/**
* The body of the message. Can be null.
*
* @return the body, or null.
*/
@CacheReturn
T body();
The reply address. Can be null.
Returns: the reply address, or null, if message was sent without a reply handler.
/**
* 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.
Returns: true if this is a send.
/**
* 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.
Params: - message – the message to reply with.
/**
* Reply to this message.
* <p>
* 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 reply(Object)
but allows you to specify delivery options for the reply. Params: - message – the reply message
- options – the delivery options
/**
* 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 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.
Params: - message – the message to reply with.
- replyHandler – the reply handler for the reply.
/**
* Reply to this message, specifying a {@code replyHandler} for the reply - i.e.
* to receive the reply to the reply.
* <p>
* 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 <R> void replyAndRequest(@Nullable Object message, Handler<AsyncResult<Message<R>>> replyHandler) {
replyAndRequest(message, new DeliveryOptions(), replyHandler);
}
Like replyAndRequest(Object, Handler)
but returns a Future
of the asynchronous result /**
* Like {@link #replyAndRequest(Object, Handler)} but returns a {@code Future} of the asynchronous result
*/
default <R> Future<Message<R>> replyAndRequest(@Nullable Object message) {
return replyAndRequest(message, new DeliveryOptions());
}
Like replyAndRequest(Object, Handler)
but specifying options
that can be used to configure the delivery. Params: - message – the message body, may be
null
- options – delivery options
- replyHandler – reply handler will be called when any reply from the recipient is received
/**
* 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 <R> void replyAndRequest(@Nullable Object message, DeliveryOptions options, Handler<AsyncResult<Message<R>>> replyHandler) {
this.<R>replyAndRequest(message, options).onComplete(replyHandler);
}
Like replyAndRequest(Object, DeliveryOptions, Handler)
but returns a Future
of the asynchronous result /**
* Like {@link #replyAndRequest(Object, DeliveryOptions, Handler)} but returns a {@code Future} of the asynchronous result
*/
<R> Future<Message<R>> 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.
Params: - failureCode – A failure code to pass back to the sender
- message – A message to pass back to the sender
/**
* Signal to the sender that processing of this message failed.
* <p>
* 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));
}
}