org.xlattice
Interface Connection

public interface Connection

A Connection is a relationship between two EndPoints. In XLattice, one EndPoint will have an Address on this Node. The other EndPoint will have an Address associated with a second Node. There is always a transport protocol associated with the connection; both EndPoints use this same protocol. Connections are established to allow one or more Messages to be passed between the Nodes at the two EndPoints. XXX Connections could be homogeneous or heterogeneous. In the first XXX case, each EndPoint would use the same transport. In the second case, XXX the heterogeneous Connection, the two EndPoints would use different XXX transports. A connection passes through a set of states. This progress is irreversible. Each state has an associated numeric value. The order of these values is guaranteed. That is, UNBOUND is less than BOUND, which is less than PENDING, and so forth. Therefore it is reasonable to test on the relative value of states. XXX If the Transport is Udp, then it is likely that we will want XXX to be able to bind and unbind the connection, allowing us to use XXX it with more than one remote EndPoint. In this case, the XXX progression through numbered states would not be irreversible. If new states are defined, they should adhere to this contract. That is, the passage of a connection through a sequence of states must be irreversible, and the numeric value of any later state must be greater than that associated with any earlier state. XXX Any application can encrypt data passing over a connection. XXX Is it reasonable to mandate what follows as part of the XXX interface? There may be a secret key associated with the Connection. This will be used with a symmetric cipher to encrypt and decrypt traffic over the Connection. Such secret keys are negotiated between the EndPoint Nodes and possibly periodically renegotiated. Connections exist at various levels of abstraction. TCP, for example, is layered on top of IP, and BGP4 on top of TCP. It is possible for a connection to be in clear, but used for carrying encrypted messages at a higher protocol level. It is equally possible that data passing over a connection will be encrypted at more than one level.

Author:

Jim Dixon

Field Summary

static int	BOUND near end point is set
static int	CONNECTED both end points have been set, connection is established
static int	DISCONNECTED connection has been closed
static int	PENDING connection to far end point has been requested
static int	UNBOUND neither end point is set

Method Summary

void	bindFarEnd(EndPoint p) Set the far end point of a connection.
void	bindNearEnd(EndPoint p) Set the near end point of a connection.
void	close() Bring the connection to the DISCONNECTED state.
boolean	equals(java.lang.Object o)
EndPoint	getFarEnd()
java.io.InputStream	getInputStream()
EndPoint	getNearEnd()
java.io.OutputStream	getOutputStream()
int	getState() Return the current state index.
int	hashCode()
boolean	isBlocking()
boolean	isClosed() This should be considered deprecated.

Field Detail

UNBOUND

static final int UNBOUND

neither end point is set

See Also:

Constant Field Values

BOUND

static final int BOUND

near end point is set

See Also:

Constant Field Values

PENDING

static final int PENDING

connection to far end point has been requested

See Also:

Constant Field Values

CONNECTED

static final int CONNECTED

both end points have been set, connection is established

See Also:

Constant Field Values

DISCONNECTED

static final int DISCONNECTED

connection has been closed

See Also:

Constant Field Values

Method Detail

getState

int getState()

Return the current state index. In the current implementation, this is not necessarily reliable, but the actual state index is guaranteed to be no less than the value reported.

Returns:

one of the values above

bindNearEnd

void bindNearEnd(EndPoint p)
                 throws java.io.IOException

Set the near end point of a connection. If either the near or far end point has already been set, this will cause an exception. If successful, the connection's state becomes BOUND.

Throws:

java.io.IOException

bindFarEnd

void bindFarEnd(EndPoint p)
                throws java.io.IOException

Set the far end point of a connection. If the near end point has NOT been set or if the far end point has already been set -- in other words, if the connection is already beyond state BOUND -- this will cause an exception. If the operation is successful, the connection's state becomes either PENDING or CONNECTED. XXX The state should become CONNECTED if the far end is on XXX the same host and PENDING if it is on a remoted host.

Throws:

java.io.IOException

close

void close()
           throws java.io.IOException

Bring the connection to the DISCONNECTED state.

Throws:

java.io.IOException

isClosed

boolean isClosed()

This should be considered deprecated. Test on whether the state is DISCONNECTED instead.

Returns:

whether the connection state is DISCONNECTED.

getNearEnd

EndPoint getNearEnd()

getFarEnd

EndPoint getFarEnd()

isBlocking

boolean isBlocking()

getInputStream

java.io.InputStream getInputStream()
                                   throws java.io.IOException

Throws:

java.io.IOException

getOutputStream

java.io.OutputStream getOutputStream()
                                     throws java.io.IOException

Throws:

java.io.IOException

equals

boolean equals(java.lang.Object o)

Overrides:

equals in class java.lang.Object

hashCode

int hashCode()

Overrides:

hashCode in class java.lang.Object