/* $Id$ */
package ibis.ipl;
import java.io.IOException;
import java.util.Properties;
/**
* The starting point of all Ibis communication, created using the
* {@link ibis.ipl.IbisFactory}.
* <p>
* The following {@link Manageable} items are recognized:
* <TABLE border="2" frame="box" rules="groups" summary="manageable items">
* <CAPTION>Manageable items</CAPTION> <COLGROUP align="left"> <COLGROUP align="left">
* <TBODY>
* <TR>
* <TD> "outgoingMessageCount"
* <TD> the number of messages sent
* <TR>
* <TD> "bytesWritten"
* <TD> the number of bytes sent in messages (multicasts are counted once)
* <TR>
* <TD> "bytesSent"
* <TD> the total number of bytes sent
* <TR>
* <TD> "incomingMessageCount"
* <TD> the number of messages received
* <TR>
* <TD> "bytesReceived"
* <TD> the number of bytes received in messages
* <TR>
* <TD> "bytesRead"
* <TD> the total number of bytes received
* <TR></TBODY> </TABLE>
* <p>
* All these properties are long values, returned as a string.
*<p>
* Other items may be recognized, depending on the Ibis implementation.
*/
public interface Ibis extends Manageable {
/**
* Returns all Ibis recources to the system.
* The Ibis instance also deregisters itself from the registry. As a
* result, other Ibis instances may receive a
* {@link RegistryEventHandler#left(IbisIdentifier)} upcall.
* @exception IOException
* is thrown when an error occurs.
*/
public void end() throws IOException;
/**
* Returns the Ibis {@linkplain ibis.ipl.Registry Registry}.
* @return
* the Ibis registry.
*/
public Registry registry();
/**
* Polls the network for new messages.
* A message upcall may be generated by the poll.
* There is one poll for the entire Ibis, as this
* can sometimes be implemented more efficiently than polling per
* port. Polling per port is provided in the receiveport itself.
* @exception IOException
* is thrown when a communication error occurs.
*/
public void poll() throws IOException;
/**
* Returns an Ibis {@linkplain ibis.ipl.IbisIdentifier identifier} for
* this Ibis instance.
* An Ibis identifier identifies an Ibis instance in the network.
* @return
* the Ibis identifier of this Ibis instance.
*/
public IbisIdentifier identifier();
/**
* Returns the current Ibis version.
* @return
* the ibis version.
*/
public String getVersion();
/**
* Returns the properties as provided when instantiating Ibis.
* @return
* the properties.
*/
public Properties properties();
/**
* Creates an anonymous {@link SendPort} of the specified port type.
* @param portType
* the port type.
* @return
* the new sendport.
* @exception IOException
* is thrown when the port could not be created.
*/
public SendPort createSendPort(PortType portType) throws IOException;
/**
* Creates a named {@link SendPort} of the specified port type.
* The sendport name must be unique within this ibis instance.
*
* @param portType
* the port type.
* @param sendPortName
* the name of this sendport, or <code>null</code>, in which
* case the sendport is created anonymously.
* @return
* the new sendport.
* @exception IOException
* is thrown when the port could not be created.
* @exception IbisConfigurationException
* is thrown when the port type does not match the capabilities
* that are required to create this sendport.
*/
public SendPort createSendPort(PortType portType, String sendPortName)
throws IOException;
/**
* Creates a named {@link SendPort} of the specified port type.
* The sendport name must be unique within this ibis instance.
*
* @param portType
* the port type.
* @param sendPortName
* the name of this sendport, or <code>null</code>, in which
* case the sendport is created anonymously.
* @param sendPortDisconnectUpcall
* object implementing the {@link
* SendPortDisconnectUpcall#lostConnection(SendPort,
* ReceivePortIdentifier, Throwable)} method.
* @param properties
* the properties of the port.
* @return
* the new sendport.
* @exception IOException
* is thrown when the port could not be created.
* @exception IbisConfigurationException
* is thrown when the port type does not match the capabilities
* that are required to create this sendport.
*/
public SendPort createSendPort(PortType portType, String sendPortName,
SendPortDisconnectUpcall sendPortDisconnectUpcall,
Properties properties) throws IOException;
/**
* Creates a named {@link ReceivePort} of the specified port type.
* with explicit receipt communication.
* The receiveport name must be unique within this ibis instance.
* New connections will not be accepted until
* {@link ReceivePort#enableConnections()} is invoked on this port.
* This is done to avoid connection upcalls during initialization.
*
* @param portType
* the port type.
* @param receivePortName
* the unique name of this receiveport (or <code>null</code>,
* in which case the port is created anonymously).
* @return
* the new receiveport.
* @exception IOException
* is thrown when the port could not be created.
* @exception IbisConfigurationException
* is thrown when the port type does not match the capabilities
* that are required to create this receiveport.
*/
public ReceivePort createReceivePort(PortType portType,
String receivePortName) throws IOException;
/**
* Creates a named {@link ReceivePort} of the specified port type.
* with upcall-based communication.
* The receiveport name must be unique within this ibis instance.
* New connections will not be accepted until
* {@link ReceivePort#enableConnections()} is invoked.
* This is done to avoid connection upcalls during initialization.
* Upcalls will not be invoked until
* {@link ReceivePort#enableMessageUpcalls()} has been called.
* This is done to avoid message upcalls during initialization.
*
* @param portType
* the port type.
* @param receivePortName
* the unique name of this receiveport (or <code>null</code>,
* in which case the port is created anonymously).
* @param messageUpcall
* the upcall handler.
* @return
* the new receiveport.
* @exception IOException
* is thrown when the port could not be created.
* @exception IbisConfigurationException
* is thrown when the port type does not match the capabilities
* that are required to create this receiveport.
*/
public ReceivePort createReceivePort(PortType portType,
String receivePortName, MessageUpcall messageUpcall)
throws IOException;
/**
* Creates a named {@link ReceivePort} of the specified port type.
* with explicit receipt communication.
* The receiveport name must be unique within this ibis instance.
* New connections will not be accepted until
* {@link ReceivePort#enableConnections()} is invoked.
* This is done to avoid connection upcalls during initialization.
* When a new connection request arrives, or when a connection is lost,
* a ConnectUpcall is performed.
*
* @param portType
* the port type.
* @param receivePortName
* the unique name of this receiveport (or <code>null</code>,
* in which case the port is created anonymously).
* @param receivePortConnectUpcall
* object implementing <code>gotConnection</code>() and
* <code>lostConnection</code>() upcalls.
* @return
* the new receiveport.
* @exception IOException
* is thrown when the port could not be created.
* @exception IbisConfigurationException
* is thrown when the port type does not match the capabilities
* that are required to create this receiveport.
*/
public ReceivePort createReceivePort(PortType portType,
String receivePortName,
ReceivePortConnectUpcall receivePortConnectUpcall)
throws IOException;
/**
* Creates a named {@link ReceivePort} of the specified port type.
* with upcall-based communication.
* The receiveport name must be unique within this ibis instance.
* New connections will not be accepted until
* {@link ReceivePort#enableConnections()} is invoked.
* This is done to avoid connection upcalls during initialization.
* When a new connection request arrives, or when a connection is lost,
* a ConnectUpcall is performed.
* Upcalls will not be invoked until
* {@link ReceivePort#enableMessageUpcalls()} has been called.
* This is done to avoid message upcalls during initialization.
*
* @param portType
* the port type.
* @param receivePortName
* the unique name of this receiveport (or <code>null</code>,
* in which case the port is created anonymously).
* @param messageUpcall
* the upcall handler.
* @param receivePortConnectUpcall
* object implementing <code>gotConnection</code>() and
* <code>lostConnection</code>() upcalls.
* @param properties
* properties for the new receive port.
* @return
* the new receiveport.
* @exception IOException
* is thrown when the port could not be created.
* @exception IbisConfigurationException
* is thrown when the port type does not match the capabilities
* that are required to create this receiveport.
*/
public ReceivePort createReceivePort(PortType portType,
String receivePortName, MessageUpcall messageUpcall,
ReceivePortConnectUpcall receivePortConnectUpcall,
Properties properties) throws IOException;
}