org.eclipse.scout.rt.mom/src/main/java/org/eclipse/scout/rt/mom/IMom.java

/*
 * Copyright (c) BSI Business Systems Integration AG. All rights reserved.
 * http://www.bsiag.com/
 */
package org.eclipse.scout.rt.mom;

import java.util.concurrent.TimeUnit;

import org.eclipse.scout.rt.mom.encryptor.DefaultAesEncryptor;
import org.eclipse.scout.rt.mom.encryptor.IEncryptor;
import org.eclipse.scout.rt.mom.marshaller.BytesMarshaller;
import org.eclipse.scout.rt.mom.marshaller.IMarshaller;
import org.eclipse.scout.rt.mom.marshaller.JsonMarshaller;
import org.eclipse.scout.rt.mom.marshaller.ObjectMarshaller;
import org.eclipse.scout.rt.mom.marshaller.StringMarshaller;
import org.eclipse.scout.rt.platform.config.AbstractClassConfigProperty;
import org.eclipse.scout.rt.platform.context.RunContext;
import org.eclipse.scout.rt.platform.util.IRegistrationHandle;
import org.eclipse.scout.rt.platform.util.concurrent.ThreadInterruptedException;
import org.eclipse.scout.rt.platform.util.concurrent.TimedOutException;

/**
 * Message oriented middleware (MOM) for sending and receiving messages between distributed systems.
 * <p>
 * This MOM provides publish/subscribe (topic-based) or point-to-point (queue-based) messaging. A topic allows to
 * publish a message to multiple subscribers, meaning that the message is transported to all consumers which currently
 * are subscribed. A queue differs from the topic distribution mechanism that the message is transported to exactly one
 * consumer. If there is no subscription the message will be kept until a consumer subscribes for the queue. However, if
 * there are multiple subscriptions for the queue, the message is load balanced to a single consumer.
 * <p>
 * Besides, this MOM provides 'request-reply' messaging, which is kind of synchronous communication between two parties.
 * The publisher of a message blocks until the reply is received. This mode is still based on P2P or pub/sub messaging,
 * meaning there is no open connection for the time of blocking.
 * <p>
 * Message addressing is based on destinations (queues or topics), which additionally allow to register for a
 * {@link IMarshaller}, and optionally for an {@link IEncryptor}. A marshaller is used to transform the transfer object
 * into its transport representation, like text in JSON format, or bytes for the object's serialization data. An
 * encryptor allows end-to-end message encryption, which may be required depending on the messaging topology you choose.
 * However, even if working with a secure transport layer, messages may temporarily be stored like when being delivered
 * to queues - end-to-end encryption ensures confidentiality, integrity, and authenticity of those messages.
 *
 * @since 6.1
 */
public interface IMom {

  int AUTO_ACKNOWLEDGE_MODE = 1;
  int TRANSACTED_ACKNOWLEDGE_MODE = 2;

  /**
   * Publishes the given message to the given destination.
   * <p>
   * The message is published with default messaging settings, meaning with normal priority, with persistent delivery
   * mode and without expiration.
   *
   * @param destination
   *          specifies the target of the message, and is either a queue (P2P) or topic (pub/sub). See {@link IMom}
   *          documentation for more information about the difference between topic and queue based messaging.
   * @param transferObject
   *          specifies the transfer object to be sent to the destination.<br>
   *          The object is marshalled into its transport representation using the {@link IMarshaller} registered for
   *          that destination. By default, {@link JsonMarshaller} is used.
   * @see #newQueue(String)
   * @see #newTopic(String)
   * @see #subscribe(IDestination, IMessageListener, RunContext)
   */
  void publish(IDestination destination, Object transferObject);

  /**
   * Publishes the given message to the given destination.
   *
   * @param destination
   *          specifies the target of the message, and is either a queue (P2P) or topic (pub/sub). See {@link IMom}
   *          documentation for more information about the difference between topic and queue based messaging.
   * @param transferObject
   *          specifies the transfer object to be sent to the destination.<br>
   *          The object is marshalled into its transport representation using the {@link IMarshaller} registered for
   *          that destination. By default, {@link JsonMarshaller} is used.
   * @param input
   *          specifies how to publish the message.
   * @see #newQueue(String)
   * @see #newTopic(String)
   * @see #subscribe(IDestination, IMessageListener, RunContext)
   */
  void publish(IDestination destination, Object transferObject, MessageInput input);

  /**
   * Subscribes the given listener to receive messages sent to the given destination.
   *
   * @param destination
   *          specifies the target to consume messages from, and is either a topic (pub/sub) or queue (P2P). See
   *          {@link IMom} documentation for more information about the difference between topic and queue based
   *          messaging.
   * @param listener
   *          specifies the listener to receive messages.
   * @param runContext
   *          specifies the context in which to receive and process the messages.
   * @return subscription handle to unsubscribe from the destination.
   * @see #publish(IDestination, Object)
   */
  <TRANSFER_OBJECT> ISubscription subscribe(IDestination destination, IMessageListener<TRANSFER_OBJECT> listener, RunContext runContext);

  /**
   * Subscribes the given listener to receive messages sent to the given destination.
   *
   * @param destination
   *          specifies the target to consume messages from, and is either a topic (pub/sub) or queue (P2P). See
   *          {@link IMom} documentation for more information about the difference between topic and queue based
   *          messaging.
   * @param listener
   *          specifies the listener to receive messages.
   * @param runContext
   *          specifies the context in which to receive and process the messages.
   * @param acknowledgementMode
   *          XXX dwi
   * @return subscription handle to unsubscribe from the destination.
   * @see #publish(IDestination, Object)
   */
  <TRANSFER_OBJECT> ISubscription subscribe(IDestination destination, IMessageListener<TRANSFER_OBJECT> listener, RunContext runContext, int acknowledgementMode);

  /**
   * Initiates a 'request-reply' communication with a consumer, and blocks until the reply is received.
   * <p>
   * This method is for convenience to facilitate synchronous communication between a publisher and a subscriber, and is
   * still based on P2P or pub/sub messaging, meaning that there is no open connection for the time of blocking.
   * <p>
   * Typically, request-reply is used with a queue destination. If using a topic, it is the first reply which is
   * returned.
   * <p>
   * If the current thread is interrupted while waiting for the reply to receive, this method returns with a
   * {@link ThreadInterruptedException} and the interruption is propagated to the consumer(s) as well.
   * <p>
   * The message is published with default messaging settings, meaning with normal priority, with persistent delivery
   * mode and without expiration.
   *
   * @param destination
   *          specifies the target of the message, and is either a queue (P2P) or topic (pub/sub). See {@link IMom}
   *          documentation for more information about the difference between topic and queue based messaging.
   * @param transferObject
   *          specifies the transfer object to be sent to the destination.<br>
   *          The object is marshalled into its transport representation using the {@link IMarshaller} registered for
   *          that destination. By default, {@link JsonMarshaller} is used.
   * @return the reply of the consumer.
   * @throws ThreadInterruptedException
   *           if interrupted while waiting for the reply to receive.
   * @see {@link #reply(IDestination, IRequestListener, RunContext)}
   */
  <REPLY_OBJECT, REQUEST_OBJECT> REPLY_OBJECT request(IDestination destination, REQUEST_OBJECT transferObject);

  /**
   * Initiates a 'request-reply' communication with a consumer, and blocks until the reply is received.
   * <p>
   * This method is for convenience to facilitate synchronous communication between a publisher and a subscriber, and is
   * still based on P2P or pub/sub messaging, meaning that there is no open connection for the time of blocking.
   * <p>
   * Typically, request-reply is used with a queue destination. If using a topic, it is the first reply which is
   * returned.
   * <p>
   * If the current thread is interrupted while waiting for the reply to receive, this method returns with a
   * {@link ThreadInterruptedException} and the interruption is propagated to the consumer(s) as well.
   *
   * @param destination
   *          specifies the target of the message, and is either a queue (P2P) or topic (pub/sub). See {@link IMom}
   *          documentation for more information about the difference between topic and queue based messaging.
   * @param transferObject
   *          specifies the transfer object to be sent to the destination.<br>
   *          The object is marshalled into its transport representation using the {@link IMarshaller} registered for
   *          that destination. By default, {@link JsonMarshaller} is used.
   * @param input
   *          specifies how to publish the message.
   * @return the reply of the consumer.
   * @throws ThreadInterruptedException
   *           if interrupted while waiting for the reply to receive. If interrupted, an interruption request is sent to
   *           the consumer(s).
   * @throws TimedOutException
   *           if the timeout specified via {@link MessageInput#withRequestReplyTimeout(long, TimeUnit)} elapsed. If
   *           elapsed, an interruption request is sent to the consumer(s).
   * @see #reply(IDestination, IRequestListener, RunContext)
   */

  <REPLY_OBJECT> REPLY_OBJECT request(IDestination destination, Object transferObject, MessageInput input);

  /**
   * Subscribes the given listener to receive messages from 'request-reply' communication sent to the given destination.
   *
   * @param destination
   *          specifies the target to consume messages from, and is either a topic (pub/sub) or queue (P2P). See
   *          {@link IMom} documentation for more information about the difference between topic and queue based
   *          messaging.
   * @param listener
   *          specifies the listener to receive messages.
   * @param runContext
   *          specifies the context in which to receive and process the messages.
   * @return subscription handle to unsubscribe from the destination.
   * @see #request(IDestination, Object)
   */
  <REQUEST_TRANSFER_OBJECT, REPLY_TRANSFER_OBJECT> ISubscription reply(IDestination destination, IRequestListener<REQUEST_TRANSFER_OBJECT, REPLY_TRANSFER_OBJECT> listener, RunContext runContext);

  /**
   * Creates a new topic for publish/subscribe messaging.
   */
  IDestination newTopic(String topic);

  /**
   * Creates a new queue for point-to-point messaging.
   */
  IDestination newQueue(String queue);

  /**
   * Looks up the given destination using JNDI.
   */
  IDestination lookupDestination(String destination);

  /**
   * Creates a message input to control how to publish a message. The {@link MessageInput} returned specifies normal
   * delivery priority, persistent delivery mode and without expiration.
   */
  MessageInput newMessageInput();

  /**
   * Registers a marshaller for transfer objects sent to the given destination, or which are received from the given
   * destination.
   * <p>
   * A marshaller transforms a transfer object into its transport representation to be sent across the network.
   * <p>
   * By default, if a destination does not specify a marshaller, {@link JsonMarshaller} is used.
   *
   * @return registration handle to unregister the marshaller from the destination.
   * @see StringMarshaller
   * @see BytesMarshaller
   * @see JsonMarshaller
   * @see ObjectMarshaller
   */
  IRegistrationHandle registerMarshaller(IDestination destination, IMarshaller<?> marshaller);

  /**
   * Allows end-to-end encryption for transfer objects sent to the given destination. By default, no encryption is used.
   *
   * @return registration handle to unregister the encryptor from the destination.
   * @see DefaultAesEncryptor
   */
  IRegistrationHandle registerEncryptor(IDestination destination, IEncryptor encryptor);

  /**
   * Destroys this MOM and releases all associated resources.
   */
  void destroy();

  /**
   * Specifies the default {@link IEncryptor} to use if no encryptor is specified for a destination.
   * <p>
   * By default, no encryptor is used.
   */
  class EncryptorProperty extends AbstractClassConfigProperty<IEncryptor> {

    @Override
    public String getKey() {
      return "scout.mom.encryptor";
    }
  }

  /**
   * Specifies the default {@link IMarshaller} to use if no marshaller is specified for a destination.
   * <p>
   * By default, {@link JsonMarshaller} is used.
   */
  class MarshallerProperty extends AbstractClassConfigProperty<IMarshaller<?>> {

    @Override
    public String getKey() {
      return "scout.mom.marshaller";
    }

    @Override
    protected Class<? extends IMarshaller<?>> getDefaultValue() {
      return JsonMarshaller.class;
    }
  }
}