jarol.messages
Class Link

java.lang.Object
  jarol.messages.Link

Direct Known Subclasses:

TCPClientLink, TCPServerLink, UDPLink

public abstract class Link
extends java.lang.Object

Jarol-wise, non-blocking, lock-free bidirectional message link abstract class.

A link has the intent of providing calling tasks a Jarol-wise signal/port interface for operation, with deterministic operation and non-blocking behavior.

This base class is extended by classes that implement actual network links in the Jarol system or custom ones defined by the user. Derived classes need only to provide link access functions (start/stop/send/receive functions), the application interface logic is within the base link class.

The link can be used to send and receive message using two instances of base.Port and an instance of base.Signal:

1) A receive port which callers can poll for received messages. The receive port is updated asynchronously (as soon as messages arrive).

2) A send port in which callers can place messages to be sent

3) A send signal to actually send the messages in the send port over the link. To send messages, the link caller should place a number of messages in the send port then trigger the send signal.

Internally Link works as follows:

1) A "receiver thread" polls the communication link and when it gets a new message it places it on the receive port.

2) A "sender thread" that waits on the send signal, then sends data from the send port over the communication link.

Note that a link will self-disconnect if the physical connection has a fatal error.

Version:

0.1

Author:

Eduardo Marques

Field Summary

static int	DEFAULT_PORT_BUFSZ Default buffer capacity for the receive and send ports
static int	MAX_MESSAGE_PAYLOAD Maximum message payload

Constructor Summary

Link(MessageFactory factory)
Constructor specifying message factory.

Link(MessageFactory factory, int recvPortBufSz, int sendPortBufSz)
Constructor specifying message factory and receive/send port capacity.

Method Summary

void	connect() Connect the message link.
boolean	connected() Check if link is connected.
void	disconnect() Disconnect the message link.
Port	getRecvPort() Get receive port.
Port	getSendPort() Get send port.
Signal	getSendSignal() Get send signal.
protected abstract int	recv(byte[] buf, int off, int len, int timeout) Abstract method used to receive data.
protected abstract void	send(byte[] data, int off, int len) Abstract method used to send data.
protected abstract void	start() Abstract method for starting the link.
protected abstract void	stop() Abstract method for stopping the link.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

DEFAULT_PORT_BUFSZ

public static final int DEFAULT_PORT_BUFSZ

Default buffer capacity for the receive and send ports

See Also:

Constant Field Values

MAX_MESSAGE_PAYLOAD

public static final int MAX_MESSAGE_PAYLOAD

Maximum message payload

See Also:

Constant Field Values

Constructor Detail

Link

public Link(MessageFactory factory)

Constructor specifying message factory. Receive and send ports will be defined with buffer capacity equal to Port.DEFAULT_PORT_CAPACITY .

Parameters:

factory - the message factory

Link

public Link(MessageFactory factory,
            int recvPortBufSz,
            int sendPortBufSz)

Constructor specifying message factory and receive/send port capacity.

Parameters:

factory - the message factory

recvPortBufSz - the buffer size for the receive port

sendPortBufSz - the buffer size for the send port

Method Detail

connected

public final boolean connected()

Check if link is connected. This procedure should be called to ensure link is connected and no connection errors occurred in the meanwhile.

Returns:

true if the link is connected.

getSendPort

public final Port getSendPort()

Get send port. The send port will remain the same throughout the link's life (whenever it is connected or not).

Returns:

send port

getSendSignal

public final Signal getSendSignal()

Get send signal. The send signal will remain the same throughout the link's life (whenever it is connected or not).

Returns:

send signal

getRecvPort

public final Port getRecvPort()

Get receive port. The receive port will remain the same throughout the link's life (whenever it is connected or not).

Returns:

receive port

connect

public final void connect()
                   throws java.io.IOException

Connect the message link. The request is ignored if the link is already in a connected state. Otherwise this will (1) setup the connection and (2) spawn the receive and send threads

Throws:

java.io.IOException - if there a problem in connecting the link

disconnect

public final void disconnect()

Disconnect the message link. The request is ignored if the link is already in a disconnected state. Otherwise this will: 1) wait for any pending sending / receiving operations to complete 2) stop the receiver and sender threads, and 3) disconnect the physical connection. Note that the link may be reconnected and any references to the sender and receive ports will remain valid. Note also that it is possible to restart the link.

start

protected abstract void start()
                       throws java.io.IOException

Abstract method for starting the link. Implementations should define this method to allocate, setup and enable the actual communication link.

Throws:

java.io.IOException - if a port-specific error occurs (eg network related)

stop

protected abstract void stop()
                      throws java.io.IOException

Abstract method for stopping the link. Implementations should define this method to close and destroy the actual communication link.

Throws:

java.io.IOException - if a port-specific error occurs (eg network related)

send

protected abstract void send(byte[] data,
                             int off,
                             int len)
                      throws java.io.IOException

Abstract method used to send data.

Parameters:

data - the message payload

off - payload offset

len - payload length

Throws:

java.io.IOException - if a port-specific error occurs (eg network related)

recv

protected abstract int recv(byte[] buf,
                            int off,
                            int len,
                            int timeout)
                     throws java.io.IOException

Abstract method used to receive data.

Parameters:

buf - the receive buffer to use

off - the receive buffer offset

len - the receive buffer usable length

timeout - the time to wait for a message

Returns:

the length of the received message packet or 0 in case timeout has been reached

Throws:

java.io.IOException - if a port-specific error occurs (eg network related)