org.mpisws.p2p.transport
Interface TransportLayer<Identifier,MessageType>

Type Parameters:

Identifier - The type of node this layer operates on.

MessageType - The type of message this layer sends.

All Superinterfaces:

Destructable

All Known Subinterfaces:

CommonAPITransportLayer<Identifier>, IdentityTransport<Handle,Identifier>, LimitBandwidthTransportLayer<Identifier>, LivenessTransportLayer<Identifier,MsgType>, LowerIdentity<Identifier,MessageType>, MultiInetAddressTransportLayer, PeerReview<Handle,Identifier>, PriorityTransportLayer<Identifier>, SourceRouteManager<Identifier>, SourceRouteTransportLayer<Identifier>, SSLTransportLayer<Identifier,MessageType>, TableTransportLayer<Identifier,Key,Value>, UpperIdentity<Identifier,MessageType>, Verifier<Handle>, WireTransportLayer

All Known Implementing Classes:

AggressiveLivenessTransportLayerImpl, BandwidthLimitingTransportLayer, BandwidthMeasuringTransportLayer, CommonAPITransportLayerImpl, DirectTransportLayer, FirewallTLImpl, IdentityTransportLayerImpl, LimitSocketsTransportLayer, LivenessTransportLayerImpl, MagicNumberTransportLayer, MultiInetAddressTransportLayerImpl, NetworkInfoTransportLayer, NodeHandleAdapter, PeerReviewCallbackImpl, PeerReviewImpl, PriorityTransportLayerImpl, RC4TransportLayer, RecordLayer, RendezvousTransportLayerImpl, ReplayLayer, ReplayVerifier, SimpleIdentityTransportLayer, SourceRouteManagerImpl, SourceRouteTransportLayerImpl, SSLTransportLayerImpl, TableTransprotLayerImpl, VerifierImpl, WireTransportLayerImpl

public interface TransportLayer<Identifier,MessageType>
extends Destructable

The transport layer does provides the minimum functionality to provide communication with flow control.

The Identifier is the type of identifier this transport layer exports. At the lowest level, this is usually an InetSocketAddress, at the highest level, this is usually a NodeHandle.

MessageType is the type of object this transport layer operates on. At the lowest level, this is usually a ByteBuffer, and at the highest level, a RawMessage.

options are transport layer specific options that are passed through the transport layers. If a layer finds an option in the map that it understands, it applies the option. For example, whether to send the message as UDP/TCP or encrypted or not. Thus, if you specify an option, but do not use a transport layer that handles the option, it will be ignored.

When a message is sent, or a socket is opened, each layer in the transport stack may add a header. For example, the magic number layer adds a special byte sequence to each outgoing socket and message.

When a message is read, or a socket is received, each layer will read only the header that it added. For example, the magic number layer reads the bytes, to make sure that they match the expected byte sequence. If they don't match, or a timeout occurs before sufficient bytes are read, the socket is closed, or the message is discarded.

Once the header has been read, the transport layer calls callback.incomingSocket() or callback.messageReceived().

Sending a message and opening a socket may not be instant. Since the message may be queued, you can include a continuation (deliverAckToMe/deliverSocketToMe) to be called back when the operation succeeds or fails. It will be called back with the same RequestHandle that was returned when the call was made. Note that if the request fails immediately, the callback may be called before the method returns, thus you may not already have a record of the RequestHandle.

Author:

Jeff Hoye

Method Summary

void	acceptMessages(boolean b) Toggle accepting incoming messages.
void	acceptSockets(boolean b) Toggle accepting new sockets.
Identifier	getLocalIdentifier() The local node.
SocketRequestHandle<Identifier>	openSocket(Identifier i, SocketCallback<Identifier> deliverSocketToMe, java.util.Map<java.lang.String,java.lang.Object> options) Open a socket to the Identifier
MessageRequestHandle<Identifier,MessageType>	sendMessage(Identifier i, MessageType m, MessageCallback<Identifier,MessageType> deliverAckToMe, java.util.Map<java.lang.String,java.lang.Object> options) Send the message to the identifier
void	setCallback(TransportLayerCallback<Identifier,MessageType> callback) Set the callback for incoming sockets/messages
void	setErrorHandler(ErrorHandler<Identifier> handler) To be notified of problems not related to an outgoing messaage/socket.

Methods inherited from interface rice.Destructable

destroy

Method Detail

openSocket

SocketRequestHandle<Identifier> openSocket(Identifier i,
                                           SocketCallback<Identifier> deliverSocketToMe,
                                           java.util.Map<java.lang.String,java.lang.Object> options)

Open a socket to the Identifier

Parameters:

i - who to open the socket to

deliverSocketToMe - the callback when the socket is opened

options - options on how to open the socket (don't source route, encrypt etc) (may not be respected if layer cannot provide service)

Returns:

an object to cancel opening the socket if it takes to long, or is no longer relevant

sendMessage

MessageRequestHandle<Identifier,MessageType> sendMessage(Identifier i,
                                                         MessageType m,
                                                         MessageCallback<Identifier,MessageType> deliverAckToMe,
                                                         java.util.Map<java.lang.String,java.lang.Object> options)

Send the message to the identifier

Parameters:

i - the destination

m - the message

options - delivery options (don't source route, encrypt etc) (may not be respected if layer cannot provide service)

deliverAckToMe - layer dependent notification when the message is sent (can indicate placed on the wire, point-to-point acknowledgment, or end-to-end acknowledgement)

Returns:

ability to cancel the message if no longer relevant

getLocalIdentifier

Identifier getLocalIdentifier()

The local node.

Returns:

The local node.

acceptSockets

void acceptSockets(boolean b)

Toggle accepting new sockets. Useful in flow control if overwhelmed by incoming sockets. Default: true

Parameters:

b -

acceptMessages

void acceptMessages(boolean b)

Toggle accepting incoming messages. Useful in flow control if overwhelmed by incoming sockets. Default: true

Parameters:

b -

setCallback

void setCallback(TransportLayerCallback<Identifier,MessageType> callback)

Set the callback for incoming sockets/messages

Parameters:

callback - the callback for incoming sockets/messages

setErrorHandler

void setErrorHandler(ErrorHandler<Identifier> handler)

To be notified of problems not related to an outgoing messaage/socket. Or to be notified if a callback isn't provided.

Parameters:

handler - to be notified of problems not related to a specific messaage/socket.