ibis.ipl
Interface SendPort

public interface SendPort

Maintains connections to one or more receive ports. When creating a sendport, it is possible to pass a SendPortConnectUpcall object. When a connection is lost for some reason (normal close or link error), the SendPortConnectUpcall.lostConnection(SendPort, ReceivePortIdentifier, Exception) upcall is invoked. This upcall is completely asynchronous, but Ibis ensures that at most one is alive at any given time. If no SendPortConnectUpcall is registered, the user is NOT informed of connections that are lost. No exceptions are thrown by the write message. It is then the user's own responisbility to use the lostConnections() method to poll for connections that are lost. Connections are unrelated to messages! If the sending of a message did not generate an exception, this does not mean that it actually arrived at the receive port. There may still be data in Ibis or operating system buffers, or in the network itself. For a given sendport, only one message is alive at any time. This is done to prevent flow control problems. When a message is alive, and a new message is requested, the request is blocked until the live message is finished.

Method Summary

void	close() Frees the resources held by the sendport.
void	connect(ReceivePortIdentifier receiver) Attempts to set up a connection with a receiver.
void	connect(ReceivePortIdentifier receiver, long timeoutMillis) Attempts to set up a connection with receiver.
ReceivePortIdentifier[]	connectedTo() Returns the set of receiveports this sendport is connected to.
void	disconnect(ReceivePortIdentifier receiver) Attempts to disconnect a connection with a receiver.
long	getCount() Returns the sum of the WriteMessage.finish() results for all write messages created with this port.
SendPortIdentifier	identifier() Obtains an identification for this sendport.
ReceivePortIdentifier[]	lostConnections() Polls to find out whether any connections are lost or closed.
java.lang.String	name() Returns the name of the sendport.
WriteMessage	newMessage() Requests a new message from this sendport.
DynamicProperties	properties() Returns the DynamicProperties of this port.
void	resetCount() Sets the counter for the number of bytes that have been written to this sendport to zero.
void	setReplacer(Replacer r) Installs an object replacer on the underlying object stream.

Method Detail

newMessage

public WriteMessage newMessage()
                        throws java.io.IOException

Requests a new message from this sendport. It is allowed to get a message for a sendport that is not connected. All data that is written into the message is then silently discarded.

Returns:

a WriteMessage.

Throws:

java.io.IOException - may be thrown when something goes wrong.

setReplacer

public void setReplacer(Replacer r)
                 throws java.io.IOException

Installs an object replacer on the underlying object stream. This can be used, for instance, by an RMI implementation to replace remote objects by stubs.

Parameters:

r - the object replacer.

Throws:

java.io.IOException - may be thrown when the underlying stream does not allow for replacers.

properties

public DynamicProperties properties()

Returns the DynamicProperties of this port. The user can set some implementation-specific dynamic properties of the port, by means of the DynamicProperties.set method.

identifier

public SendPortIdentifier identifier()

Obtains an identification for this sendport.

Returns:

the identification.

name

public java.lang.String name()

Returns the name of the sendport. When the sendport was created anonymously, a system-invented name will be returned.

Returns:

the name.

getCount

public long getCount()

Returns the sum of the WriteMessage.finish() results for all write messages created with this port.

Returns:

the number of bytes written.

resetCount

public void resetCount()

Sets the counter for the number of bytes that have been written to this sendport to zero.

connect

public void connect(ReceivePortIdentifier receiver)
             throws java.io.IOException

Attempts to set up a connection with a receiver. It is not allowed to set up a new connection while a message is alive.

Parameters:

receiver - identifies the ReceivePort to connect to

Throws:

ConnectionRefusedException - is thrown if the receiver denies the connection.

AlreadyConnectedException - is thrown if the port was already connected to the receiver. Multiple connections to the same receiver are NOT allowed.

PortMismatchException - is thrown if the receiveport port and the sendport are of different types.

java.io.IOException - is thrown if a message is alive.

disconnect

public void disconnect(ReceivePortIdentifier receiver)
                throws java.io.IOException

Attempts to disconnect a connection with a receiver.

Parameters:

receiver - identifies the ReceivePort to disconnect

Throws:

java.io.IOException - is thrown if there was no connection to the receiveport specified or in case of other trouble.

connect

public void connect(ReceivePortIdentifier receiver,
                    long timeoutMillis)
             throws java.io.IOException

Attempts to set up a connection with receiver.

Parameters:

receiver - identifies the ReceivePort to connect to

timeoutMillis - timeout in milliseconds

Throws:

ConnectionTimedOutException - is thrown if an accept/deny has not arrived within timeoutmillis. A value of 0 for timeoutmillis signifies no timeout on the connection attempt.

ConnectionRefusedException - is thrown if the receiver denies the connection.

AlreadyConnectedException - is thrown if the port was already connected to the receiver. Multiple connections to the same receiver are NOT allowed.

PortMismatchException - is thrown if the receiveport port and the sendport are of different types.

java.io.IOException

close

public void close()
           throws java.io.IOException

Frees the resources held by the sendport. If a close is attempted when a message is still alive, an exception will be thrown. Even if this call throws an exception, the connection cannot be used anymore.

Throws:

java.io.IOException - is thrown in case of trouble.

connectedTo

public ReceivePortIdentifier[] connectedTo()

Returns the set of receiveports this sendport is connected to.

Returns:

a set of receiveport identifiers.

lostConnections

public ReceivePortIdentifier[] lostConnections()

Polls to find out whether any connections are lost or closed. Returns the changes since the last lostConnections call, or, if this is the first call, all connections that were lost since the port was created. This call only works if the connectionAdministration parameter was true when this port was created. Otherwise, null is returned.

Returns:

A set of receiveport identifiers to which the connection is lost.