source: references/src/main/java/geniusweb/connection/ConnectionEnd.java@ 22

package geniusweb.connection;

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

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

/**
 * One end of a general two-way connection. incoming data is reported through
 * the {@link Listenable} channel, sending events of the INTYPE.
 * <p>
 * 
 * The connection mechanism assumed here is fundamentally asymmetric. One side
 * is "Connectable", the other side is a ConnectionEnd created (usually from a
 * {@link Reference}. This matches the typical client-server system (web
 * architecture).
 * 
 * <p>
 * If an internal error occurs, eg a socket failure, timeout, or parser error, a
 * null event is sent into the Listenable. {@link #getError()} can be called to
 * find out about the error.
 *
 * @param <INTYPE>  the type of incoming messages (incoming for the user of this
 *                  connection end). Incoming messages are received through
 *                  Listener#not. Incoming messages are usually asynchronous.
 * @param <OUTTYPE> the type of outgoing messages (outgoing for the user of this
 *                  connection end). Outgoing messages can be sent directly with
 *                  #send.
 * 
 */
public interface ConnectionEnd<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();
}