package geniusweb.connection;

import java.io.IOException;
import java.net.SocketException;
import java.net.URI;

import geniusweb.references.Reference;
import tudelft.utilities.listener.Listenable;

/**
 * A general two-way connection. incoming data is reported through the
 * {@link Listenable} channel, sending events of the INTYPE.
 * <p>
 * If an internal error occurs, eg a socket failure, timeout, or parser error, a
 * null event is sent into the Listenable and {@link #getError()} can be called
 * to find out about the error.
 *
 * @param <INTYPE>  the type of incoming messages. Incoming messages are
 *                  received through Listener#not. Incoming messages are usually
 *                  asynchronous.
 * @param <OUTTYPE> the type of outgoing messages. Outgoing messages can be sent
 *                  directly with #send.
 * 
 */
public interface Connection<INTYPE, OUTTYPE> extends Listenable<INTYPE> {

	/**
	 * Send data out (and flush the output so that there are no excessive delays
	 * in sending the data). This call is assumed to return immediately (never
	 * block, eg on synchronized, Thread.sleep, IO, etc). When this is called
	 * multiple times in sequence, the data should arrive at the receiver end in
	 * the same order.
	 * 
	 * @param data the data to be sent.
	 * @throws IOException if the data failed to be sent.
	 */
	void send(OUTTYPE data) throws IOException;

	/**
	 * @return Reference that was used to create this connection
	 */
	Reference getReference();

	/**
	 * @return the URI of the remote endpoint that makes up the connection. This
	 *         is a URI that uniquely identifies the remote object
	 */
	URI getRemoteURI();

	/**
	 * Close the connection. Should return immediately (not block). Before
	 * really closing, this should attempt to send out possibly cached messages
	 * before closing the connection.
	 * 
	 */
	void close();

	/**
	 * @return the latest internal error, or null if no error occured. If the
	 *         channel is closed, this is set to {@link SocketException} "Socket
	 *         closed", even if the close was a "normal" termination eg when
	 *         {@link #close()} was called.
	 */
	Throwable getError();
}