/*
 * Copyright (c) 2011-2017 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.Fluent;
import io.vertx.codegen.annotations.GenIgnore;
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.Promise;
import io.vertx.core.metrics.Measured;

A Vert.x event-bus is a light-weight distributed messaging system which allows different parts of your application,
or different applications and services to communicate with each in a loosely coupled way.

An event-bus supports publish-subscribe messaging, point-to-point messaging and request-response messaging.

Message delivery is best-effort and messages can be lost if failure of all or part of the event bus occurs.

Please refer to the documentation for more information on the event bus.
Author:
Tim Fox/**
 * A Vert.x event-bus is a light-weight distributed messaging system which allows different parts of your application,
 * or different applications and services to communicate with each in a loosely coupled way.
 * <p>
 * An event-bus supports publish-subscribe messaging, point-to-point messaging and request-response messaging.
 * <p>
 * Message delivery is best-effort and messages can be lost if failure of all or part of the event bus occurs.
 * <p>
 * Please refer to the documentation for more information on the event bus.
 *
 * @author <a href="http://tfox.org">Tim Fox</a>
 */
@VertxGen
public interface EventBus extends Measured {

  
Sends a message.

The message will be delivered to at most one of the handlers registered to the address.
Params:
address –  the address to send it to
message –  the message, may be null
Returns:
a reference to this, so the API can be used fluently/**
   * Sends a message.
   * <p>
   * The message will be delivered to at most one of the handlers registered to the address.
   *
   * @param address  the address to send it to
   * @param message  the message, may be {@code null}
   * @return a reference to this, so the API can be used fluently
   */
  @Fluent
  EventBus send(String address, Object message);

  
Like send(String, Object) but specifying a replyHandler that will be called if the recipient subsequently replies to the message. 
Params:
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
Returns:
a reference to this, so the API can be used fluently
Deprecated:
use request(String, Object, Handler<AsyncResult<Message<Object>>>) instead/**
   * Like {@link #send(String, Object)} but specifying a {@code replyHandler} that will be called if the recipient
   * subsequently replies to the message.
   *
   * @param address  the address to send it to
   * @param message  the message, may be {@code null}
   * @param replyHandler  reply handler will be called when any reply from the recipient is received, may be {@code null}
   * @return a reference to this, so the API can be used fluently
   * @deprecated use {@link #request(String, Object, Handler)} instead
   */
  @Fluent
  @Deprecated
  <T> EventBus send(String address, Object message, Handler<AsyncResult<Message<T>>> replyHandler);

  
Like send(String, Object) but specifying options that can be used to configure the delivery. 
Params:
address –  the address to send it to
message –  the message, may be null
options –  delivery options
Returns:
a reference to this, so the API can be used fluently/**
   * Like {@link #send(String, Object)} but specifying {@code options} that can be used to configure the delivery.
   *
   * @param address  the address to send it to
   * @param message  the message, may be {@code null}
   * @param options  delivery options
   * @return a reference to this, so the API can be used fluently
   */
  @Fluent
  EventBus send(String address, Object message, DeliveryOptions options);

  
Like send(String, Object, DeliveryOptions) but specifying a replyHandler that will be called if the recipient subsequently replies to the message. 
Params:
address –  the address to send it to
message –  the message, may be null
options –  delivery options
replyHandler –  reply handler will be called when any reply from the recipient is received, may be null
Returns:
a reference to this, so the API can be used fluently
Deprecated:
use request(String, Object, DeliveryOptions, Handler<AsyncResult<Message<Object>>>) instead/**
   * Like {@link #send(String, Object, DeliveryOptions)} but specifying a {@code replyHandler} that will be called if the recipient
   * subsequently replies to the message.
   *
   * @param address  the address to send it to
   * @param message  the message, may be {@code null}
   * @param options  delivery options
   * @param replyHandler  reply handler will be called when any reply from the recipient is received, may be {@code null}
   * @return a reference to this, so the API can be used fluently
   * @deprecated use {@link #request(String, Object, DeliveryOptions, Handler)} instead
   */
  @Fluent
  @Deprecated
  <T> EventBus send(String address, Object message, DeliveryOptions options, Handler<AsyncResult<Message<T>>> replyHandler);

  
Sends a message and and specify a replyHandler that will be called if the recipient subsequently replies to the message. 

The message will be delivered to at most one of the handlers registered to the address.
Params:
address –  the address to send it to
message –  the message body, may be null
replyHandler –  reply handler will be called when any reply from the recipient is received
Returns:
a reference to this, so the API can be used fluently/**
   * Sends a message and and specify a {@code replyHandler} that will be called if the recipient
   * subsequently replies to the message.
   * <p>
   * The message will be delivered to at most one of the handlers registered to the address.
   *
   * @param address  the address to send it to
   * @param message  the message body, may be {@code null}
   * @param replyHandler  reply handler will be called when any reply from the recipient is received
   * @return a reference to this, so the API can be used fluently
   */
  @Fluent
  @SuppressWarnings("deprecation")
  default <T> EventBus request(String address, Object message, Handler<AsyncResult<Message<T>>> replyHandler) {
    return send(address, message, replyHandler);
  }

  
Like request(String, Object, Handler<AsyncResult<Message<Object>>>) but specifying options that can be used to configure the delivery. 
Params:
address –  the address to send it to
message –  the message body, may be null
options –  delivery options
replyHandler –  reply handler will be called when any reply from the recipient is received
Returns:
a reference to this, so the API can be used fluently/**
   * Like {@link #request(String, Object, Handler)} but specifying {@code options} that can be used to configure the delivery.
   *
   * @param address  the address to send it to
   * @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
   * @return a reference to this, so the API can be used fluently
   */
  @Fluent
  @SuppressWarnings("deprecation")
  default <T> EventBus request(String address, Object message, DeliveryOptions options, Handler<AsyncResult<Message<T>>> replyHandler) {
    return send(address, message, options, replyHandler);
  }

  
Publish a message.

The message will be delivered to all handlers registered to the address.
Params:
address –  the address to publish it to
message –  the message, may be null
Returns:
a reference to this, so the API can be used fluently/**
   * Publish a message.<p>
   * The message will be delivered to all handlers registered to the address.
   *
   * @param address  the address to publish it to
   * @param message  the message, may be {@code null}
   * @return a reference to this, so the API can be used fluently
   *
   */
  @Fluent
  EventBus publish(String address, Object message);

  
Like publish(String, Object) but specifying options that can be used to configure the delivery. 
Params:
address –  the address to publish it to
message –  the message, may be null
options –  the delivery options
Returns:
a reference to this, so the API can be used fluently/**
   * Like {@link #publish(String, Object)} but specifying {@code options} that can be used to configure the delivery.
   *
   * @param address  the address to publish it to
   * @param message  the message, may be {@code null}
   * @param options  the delivery options
   * @return a reference to this, so the API can be used fluently
   */
  @Fluent
  EventBus publish(String address, Object message, DeliveryOptions options);

  
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(Handler) is called. 
Params:
address –  the address that it will register it at
Returns:
the event bus message consumer/**
   * Create a message consumer against the specified address.
   * <p>
   * The returned consumer is not yet registered
   * at the address, registration will be effective when {@link MessageConsumer#handler(io.vertx.core.Handler)}
   * is called.
   *
   * @param address  the address that it will register it at
   * @return the event bus message consumer
   */
  <T> MessageConsumer<T> consumer(String address);

  
Create a consumer and register it against the specified address.
Params:
address –  the address that will register it at
handler –  the handler that will process the received messages
Returns:
the event bus message consumer/**
   * Create a consumer and register it against the specified address.
   *
   * @param address  the address that will register it at
   * @param handler  the handler that will process the received messages
   *
   * @return the event bus message consumer
   */
  <T> MessageConsumer<T> consumer(String address, Handler<Message<T>> handler);

  
Like consumer(String) but the address won't be propagated across the cluster. 
Params:
address –  the address to register it at
Returns:
the event bus message consumer/**
   * Like {@link #consumer(String)} but the address won't be propagated across the cluster.
   *
   * @param address  the address to register it at
   * @return the event bus message consumer
   */
  <T> MessageConsumer<T> localConsumer(String address);

  
Like consumer(String, Handler<Message<Object>>) but the address won't be propagated across the cluster. 
Params:
address –  the address that will register it at
handler –  the handler that will process the received messages
Returns:
the event bus message consumer/**
   * Like {@link #consumer(String, Handler)} but the address won't be propagated across the cluster.
   *
   * @param address  the address that will register it at
   * @param handler  the handler that will process the received messages
   * @return the event bus message consumer
   */
  <T> MessageConsumer<T> localConsumer(String address, Handler<Message<T>> handler);

  
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. 
Params:
address –  the address to send it to
Returns:
The sender/**
   * Create a message sender against the specified address.
   * <p>
   * The returned sender will invoke the {@link #send(String, Object)}
   * method when the stream {@link io.vertx.core.streams.WriteStream#write(Object)} method is called with the sender
   * address and the provided data.
   *
   * @param address  the address to send it to
   * @return The sender
   */
  <T> MessageProducer<T> sender(String address);

  
Like sender(String) but specifying delivery options that will be used for configuring the delivery of the message. 
Params:
address –  the address to send it to
options –  the delivery options
Returns:
The sender/**
   * Like {@link #sender(String)} but specifying delivery options that will be used for configuring the delivery of
   * the message.
   *
   * @param address  the address to send it to
   * @param options  the delivery options
   * @return The sender
   */
  <T> MessageProducer<T> sender(String address, DeliveryOptions options);

  
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. 
Params:
address – The address to publish it to
Returns:
The publisher/**
   * Create a message publisher against the specified address.
   * <p>
   * The returned publisher will invoke the {@link #publish(String, Object)}
   * method when the stream {@link io.vertx.core.streams.WriteStream#write(Object)} method is called with the publisher
   * address and the provided data.
   *
   * @param address The address to publish it to
   * @return The publisher
   */
  <T> MessageProducer<T> publisher(String address);

  
Like publisher(String) but specifying delivery options that will be used for configuring the delivery of the message. 
Params:
address –  the address to publish it to
options –  the delivery options
Returns:
The publisher/**
   * Like {@link #publisher(String)} but specifying delivery options that will be used for configuring the delivery of
   * the message.
   *
   * @param address  the address to publish it to
   * @param options  the delivery options
   * @return The publisher
   */
  <T> MessageProducer<T> publisher(String address, DeliveryOptions options);

  
Register a message codec.

You can register a message codec if you want to send any non standard message across the event bus.
E.g. you might want to send POJOs directly across the event bus.

To use a message codec for a send, you should specify it in the delivery options.
Params:
codec –  the message codec to register
Returns:
a reference to this, so the API can be used fluently/**
   * Register a message codec.
   * <p>
   * You can register a message codec if you want to send any non standard message across the event bus.
   * E.g. you might want to send POJOs directly across the event bus.
   * <p>
   * To use a message codec for a send, you should specify it in the delivery options.
   *
   * @param codec  the message codec to register
   * @return a reference to this, so the API can be used fluently
   */
  @GenIgnore(GenIgnore.PERMITTED_TYPE)
  EventBus registerCodec(MessageCodec codec);

  
Unregister a message codec.

Params:
name –  the name of the codec
Returns:
a reference to this, so the API can be used fluently/**
   * Unregister a message codec.
   * <p>
   * @param name  the name of the codec
   * @return a reference to this, so the API can be used fluently
   */
  @GenIgnore(GenIgnore.PERMITTED_TYPE)
  EventBus unregisterCodec(String name);

  
Register a default message codec.

You can register a message codec if you want to send any non standard message across the event bus.
E.g. you might want to send POJOs directly across the event bus.

Default message codecs will be used to serialise any messages of the specified type on the event bus without
the codec having to be specified in the delivery options.
Params:
clazz –  the class for which to use this codec
codec –  the message codec to register
Returns:
a reference to this, so the API can be used fluently/**
   * Register a default message codec.
   * <p>
   * You can register a message codec if you want to send any non standard message across the event bus.
   * E.g. you might want to send POJOs directly across the event bus.
   * <p>
   * Default message codecs will be used to serialise any messages of the specified type on the event bus without
   * the codec having to be specified in the delivery options.
   *
   * @param clazz  the class for which to use this codec
   * @param codec  the message codec to register
   * @return a reference to this, so the API can be used fluently
   */
  @GenIgnore
  <T> EventBus registerDefaultCodec(Class<T> clazz, MessageCodec<T, ?> codec);

  
Unregister a default message codec.

Params:
clazz –  the class for which the codec was registered
Returns:
a reference to this, so the API can be used fluently/**
   * Unregister a default message codec.
   * <p>
   * @param clazz  the class for which the codec was registered
   * @return a reference to this, so the API can be used fluently
   */
  @GenIgnore
  EventBus unregisterDefaultCodec(Class clazz);

  
Start the event bus. This would not normally be called in user code
Params:
completionHandler –  handler will be called when event bus is started/**
   * Start the event bus. This would not normally be called in user code
   *
   * @param completionHandler  handler will be called when event bus is started
   */
  @GenIgnore
  void start(Handler<AsyncResult<Void>> completionHandler);

  
Close the event bus and release any resources held. This would not normally be called in user code
Params:
completionHandler – may be null/**
   * Close the event bus and release any resources held. This would not normally be called in user code
   *
   * @param completionHandler may be {@code null}
   */
  @GenIgnore
  void close(Handler<AsyncResult<Void>> completionHandler);

  
Add an interceptor that will be called whenever a message is sent from Vert.x
Params:
interceptor –  the interceptor
Returns:
a reference to this, so the API can be used fluently/**
   * Add an interceptor that will be called whenever a message is sent from Vert.x
   *
   * @param interceptor  the interceptor
   * @return a reference to this, so the API can be used fluently
   */
  @Fluent
  <T> EventBus addOutboundInterceptor(Handler<DeliveryContext<T>> interceptor);

  
Remove an interceptor that was added by addOutboundInterceptor(Handler<DeliveryContext<Object>>) 
Params:
interceptor –  the interceptor
Returns:
a reference to this, so the API can be used fluently/**
   * Remove an interceptor that was added by {@link #addOutboundInterceptor(Handler)}
   *
   * @param interceptor  the interceptor
   * @return a reference to this, so the API can be used fluently
   */
  @Fluent
  <T> EventBus removeOutboundInterceptor(Handler<DeliveryContext<T>> interceptor);

  
Add an interceptor that will be called whenever a message is received by Vert.x
Params:
interceptor –  the interceptor
Returns:
a reference to this, so the API can be used fluently/**
   * Add an interceptor that will be called whenever a message is received by Vert.x
   *
   * @param interceptor  the interceptor
   * @return a reference to this, so the API can be used fluently
   */
  @Fluent
  <T> EventBus addInboundInterceptor(Handler<DeliveryContext<T>> interceptor);

  
Remove an interceptor that was added by addInboundInterceptor(Handler<DeliveryContext<Object>>) 
Params:
interceptor –  the interceptor
Returns:
a reference to this, so the API can be used fluently/**
   * Remove an interceptor that was added by {@link #addInboundInterceptor(Handler)}
   *
   * @param interceptor  the interceptor
   * @return a reference to this, so the API can be used fluently
   */
  @Fluent
  <T> EventBus removeInboundInterceptor(Handler<DeliveryContext<T>> interceptor);
}