source: references/src/main/java/geniusweb/connection/Connection.java@ 2

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();
}