// Copyright (c) 2009 The Chromium Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

package org.chromium.sdk.internal.transport;

import java.io.IOException;

/**
 * An interface to be implemented by an agent performing the communications with
 * the debugged browser instance.
 */
public interface Connection {

  /**
   * An interface to be used for notification of messages coming in from the
   * browser.
   */
  public interface NetListener {

    /**
     * Gets invoked whenever a message from the browser arrives.
     * Invoked from DispatchThread.
     * @param message from the browser instance the connection is associated
     *        with
     */
    void messageReceived(Message message);

    /**
     * Gets invoked from DispatchThread whenever EOS message arrives. This method
     * must not be called more than once. Method {@link #messageReceived} must
     * not be called after it.
     */
    void eosReceived();

    /**
     * Gets invoked when the physical connection has been terminated.
     * Called from whatever thread that connection is terminated from.
     */
    void connectionClosed();
  }

  /**
   * Sets a listener that will be notified of network events. The listener must
   * be set before calling {@link #start()} and cannot be changed over the
   * connection lifetime.
   *
   * @param netListener to set
   */
  void setNetListener(NetListener netListener);

  /**
   * Sends the specified message to the associated browser instance.
   *
   * @param message to send
   */
  void send(Message message);

  /**
   * Starts up the transport and acquire all needed resources. Does nothing if
   * the connection has already been started.
   *
   * @throws IOException
   */
  void start() throws IOException;

  /**
   * Shuts down the transport freeing all acquired resources. Does nothing if
   * the connection has already been shut down.
   */
  void close();

  /**
   * Determines the connection state.
   *
   * @return whether start() has been successfully invoked and close() has not
   *         been invoked yet
   */
  boolean isConnected();
}