io.vertx.core.eventbus

Interface EventBus

All Superinterfaces:

Measured

All Known Implementing Classes:

EventBusImpl

public interface EventBus
extends Measured

A distributed lightweight event bus which can encompass multiple vert.x instances. The event bus implements publish / subscribe, point to point messaging and request-response messaging.<p> Messages sent over the event bus are represented by instances of the Message class.<p> For publish / subscribe, messages can be published to an address using one of the publish(java.lang.String, java.lang.Object) methods. An address is a simple String instance.<p> Handlers are registered against an address. There can be multiple handlers registered against each address, and a particular handler can be registered against multiple addresses. The event bus will route a sent message to all handlers which are registered against that address.<p> For point to point messaging, messages can be sent to an address using one of the send(java.lang.String, java.lang.Object) methods. The messages will be delivered to a single handler, if one is registered on that address. If more than one handler is registered on the same address, Vert.x will choose one and deliver the message to that. Vert.x will aim to fairly distribute messages in a round-robin way, but does not guarantee strict round-robin under all circumstances.<p> All messages sent over the bus are transient. On event of failure of all or part of the event bus messages may be lost. Applications should be coded to cope with lost messages, e.g. by resending them, and making application services idempotent.<p> The order of messages received by any specific handler from a specific sender should match the order of messages sent from that sender.<p> When sending a message, a reply handler can be provided. If so, it will be called when the reply from the receiver has been received. Reply messages can also be replied to, etc, ad infinitum<p> Different event bus instances can be clustered together over a network, to give a single logical event bus.<p> Instances of EventBus are thread-safe.<p> If handlers are registered from an event loop, they will be executed using that same event loop. If they are registered from outside an event loop (i.e. when using Vert.x embedded) then Vert.x will assign an event loop to the handler and use it to deliver messages to that handler.

Author:

<a href="http://tfox.org">Tim Fox</a>

Method Summary

Modifier and Type	Method and Description
void	close(Handler<AsyncResult<Void>> completionHandler) Close the EventBus and release all resources.
<T> MessageConsumer<T>	consumer(String address) Create a message consumer against the specified address.
<T> MessageConsumer<T>	consumer(String address, Handler<Message<T>> handler) Register a message consumer against the specified address.
<T> MessageConsumer<T>	localConsumer(String address) Create a local message consumer against the specified address.
<T> MessageConsumer<T>	localConsumer(String address, Handler<Message<T>> handler) Register a local message consumer against the specified address.
EventBus	publish(String address, Object message) Publish a message
EventBus	publish(String address, Object message, DeliveryOptions options)
<T> MessageProducer<T>	publisher(String address) Create a message publisher against the specified address.
<T> MessageProducer<T>	publisher(String address, DeliveryOptions options) Create a message publisher against the specified address.
EventBus	registerCodec(MessageCodec codec)
<T> EventBus	registerDefaultCodec(Class<T> clazz, MessageCodec<T,?> codec)
EventBus	send(String address, Object message) Send a message
<T> EventBus	send(String address, Object message, DeliveryOptions options)
<T> EventBus	send(String address, Object message, DeliveryOptions options, Handler<AsyncResult<Message<T>>> replyHandler)
<T> EventBus	send(String address, Object message, Handler<AsyncResult<Message<T>>> replyHandler) Send a message
<T> MessageProducer<T>	sender(String address) Create a message sender against the specified address.
<T> MessageProducer<T>	sender(String address, DeliveryOptions options) Create a message sender against the specified address.
EventBus	unregisterCodec(String name)
EventBus	unregisterDefaultCodec(Class clazz)

Methods inherited from interface io.vertx.core.metrics.Measured

metricBaseName, metrics

Method Detail

close

void close(Handler<AsyncResult<Void>> completionHandler)

Close the EventBus and release all resources.

Parameters:

completionHandler - may be null

send

EventBus send(String address,
              Object message)

Send a message

Parameters:

address - The address to send it to

message - The message, may be null

send

<T> EventBus send(String address,
                  Object message,
                  Handler<AsyncResult<Message<T>>> replyHandler)

Send a message

Parameters:

address - The address to send it to

message - The message, may be null

replyHandler - Reply handler will be called when any reply from the recipient is received, may be null

send

<T> EventBus send(String address,
                  Object message,
                  DeliveryOptions options)

send

<T> EventBus send(String address,
                  Object message,
                  DeliveryOptions options,
                  Handler<AsyncResult<Message<T>>> replyHandler)

publish

EventBus publish(String address,
                 Object message)

Publish a message

Parameters:

address - The address to publish it to

message - The message, may be null

publish

EventBus publish(String address,
                 Object message,
                 DeliveryOptions options)

consumer

<T> MessageConsumer<T> consumer(String address)

Create a message consumer against the specified address. The returned consumer is not yet registered at the address, registration will be effective when MessageConsumer.handler(io.vertx.core.Handler) is called.

Parameters:

address - The address that will register it at

Returns:

the event bus message consumer

consumer

<T> MessageConsumer<T> consumer(String address,
                                Handler<Message<T>> handler)

Register a message consumer against the specified address.

Parameters:

address - The address that will register it at

handler - The handler that will process the received messages

Returns:

the event bus message consumer

localConsumer

<T> MessageConsumer<T> localConsumer(String address)

Create a local message consumer against the specified address. The handler info won’t be propagated across the cluster. The returned consumer is not yet registered at the address, registration will be effective when MessageConsumer.handler(io.vertx.core.Handler) is called.

Parameters:

address - The address to register it at

Returns:

the event bus message consumer

localConsumer

<T> MessageConsumer<T> localConsumer(String address,
                                     Handler<Message<T>> handler)

Register a local message consumer against the specified address. The handler info won’t be propagated across the cluster.

Parameters:

address - The address that will register it at

handler - The handler that will process the received messages

Returns:

the event bus message consumer

sender

<T> MessageProducer<T> sender(String address)

Create a message sender against the specified address. The returned sender will invoke the send(String, Object) method when the stream WriteStream.write(Object) method is called with the sender address and the provided data.

Parameters:

address - The address to send it to

Returns:

The sender

sender

<T> MessageProducer<T> sender(String address,
                              DeliveryOptions options)

Create a message sender against the specified address. The returned sender will invoke the send(String, Object, DeliveryOptions) method when the stream WriteStream.write(Object) method is called with the sender address, the provided data and the sender delivery options.

Parameters:

address - The address to send it to

Returns:

The sender

publisher

<T> MessageProducer<T> publisher(String address)

Create a message publisher against the specified address. The returned publisher will invoke the publish(String, Object) method when the stream WriteStream.write(Object) method is called with the publisher address and the provided data.

Parameters:

address - The address to publish it to

Returns:

The publisher

publisher

<T> MessageProducer<T> publisher(String address,
                                 DeliveryOptions options)

Create a message publisher against the specified address. The returned publisher will invoke the publish(String, Object, DeliveryOptions) method when the stream WriteStream.write(Object) method is called with the publisher address, the provided data and the publisher delivery options.

Parameters:

address - The address to publish it to

Returns:

The publisher

registerCodec

EventBus registerCodec(MessageCodec codec)

unregisterCodec

EventBus unregisterCodec(String name)

registerDefaultCodec

<T> EventBus registerDefaultCodec(Class<T> clazz,
                                  MessageCodec<T,?> codec)

unregisterDefaultCodec

EventBus unregisterDefaultCodec(Class clazz)