/*
 * Copyright 2000-2009 JetBrains s.r.o.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

/*
 * @author max
 */
package com.intellij.util.messages;

import com.intellij.openapi.Disposable;
import org.jetbrains.annotations.NotNull;
import org.jetbrains.annotations.Nullable;

/**
 * Aggregates multiple topic subscriptions for particular {@link MessageBus message bus}. I.e. every time a client wants to
 * listen for messages it should grab appropriate connection (or create a new one) and {@link #subscribe(Topic, Object) subscribe}
 * to particular endpoint.
 */
public interface MessageBusConnection extends Disposable {

  /**
   * Subscribes given handler to the target endpoint within the current connection.
   *
   * @param topic    target endpoint
   * @param handler  target handler to use for incoming messages
   * @param <L>      interface for working with the target topic
   * @throws IllegalStateException    if there is already registered handler for the target endpoint within the current connection.
   *                                  Note that that previously registered handler is not replaced by the given one then
   * @see MessageBus#syncPublisher(Topic)
   */
  <L> void subscribe(@NotNull Topic<L> topic, @NotNull L handler) throws IllegalStateException;

  /**
   * Subscribes to the target topic within the current connection using {@link #setDefaultHandler(MessageHandler) default handler}.
   *
   * @param topic  target endpoint
   * @param <L>    interface for working with the target topic
   * @throws IllegalStateException    if {@link #setDefaultHandler(MessageHandler) default handler} hasn't been defined or
   *                                  has incompatible type with the {@link Topic#getListenerClass() topic's business interface}
   *                                  or if target topic is already subscribed within the current connection
   */
  <L> void subscribe(@NotNull Topic<L> topic) throws IllegalStateException;

  /**
   * Allows to specify default handler to use during {@link #subscribe(Topic) anonymous subscriptions}.
   *
   * @param handler  handler to use
   */
  void setDefaultHandler(@Nullable MessageHandler handler);

  /**
   * Forces to process any queued but not delivered events.
   *
   * @see MessageBus#syncPublisher(Topic)
   */
  void deliverImmediately();

  /**
   * Disconnects current connections from the {@link MessageBus message bus} and drops all queued but not dispatched messages (if any)
   */
  void disconnect();
}