/interpreter/branches/net_refactor+bt/src/edu/vub/at/actors/net/comm/CommunicationBus.java

package edu.vub.at.actors.net.comm;

import java.io.IOException;

import edu.vub.at.actors.id.VirtualMachineID;
import edu.vub.at.actors.net.cmd.VMCommand;

public interface CommunicationBus {
	
	/**
	 * @return the group name assigned to this communication bus.
	 */
	public String getGroupName();

	/**
	 * called by the handshake cmd to register mapping between address and vmId in the commbus
	 * @param senderVMId_ the id of the vm sending the handshake
	 * @param senderVmAddress the address on which the handshake was received
	 */
	public void updateAddressForVm(VirtualMachineID senderVmId, Address senderVmAddress);

	/**
	 * called by the vm cmds to retrieve the vmId for a given address
	 * @param senderVmAddress
	 * @return the VmId corresponding to this address
	 */
	public VirtualMachineID getVmForAddress(Address senderVmAddress);

	/**
	 * Tries to connect the communication bus to the underlying network.
	 * @throws IOException if no server socket could be created to listen
	 * for incoming connections. If this exception is raised, it is
	 * guaranteed that the communication bus is left disconnected (i.e.
	 * it is not partially connected)
	 */
	public Address connect() throws NetworkException;

	/**
	 * Called by the VM when it has disconnected from the underlying channel.
	 * It gracefully shuts down all network threads, sets the network address
	 * to null and removes all current connections from the connection table.
	 */
	public void disconnect();

	/**
	 * Sends a VM Command object asynchronously to the recipient VM.
	 * There are no delivery guarantees for this message.
	 * If the recipient is offline, or the message times out, it is simply discarded
	 */
	public void sendAsyncUnicast(VMCommand msg, VirtualMachineID recipientVM);
	
	public void sendAsyncUnicast(VMCommand msg, Address recipientVM);

	/**
	 * Sends a VM Command object asynchronously to all connected VMs.
	 * There are no delivery guarantees for this message, nor is it guaranteed
	 * that all currently connected VMs will receive the message
	 */
	public void sendAsyncMulticast(VMCommand msg);

	/**
	 * Sends the given {@link VMCommand} to the given member. With 'synchronous' transmission,
	 * it is meant that if this method returns gracefully, the caller can rest assured that
	 * the remote VM has correctly received the command object. It does not given any guarantees
	 * that the command object will have been executed remotely.
	 * 
	 * @throws NetworkException if either the given address is no longer connected, or
	 * an I/O error occurs during the transmission of the command object. If this exception is
	 * raised, the caller does not know whether the message was correctly received or not.
	 */
	public void sendSynchronousUnicast(VMCommand msg, VirtualMachineID recipientVM) throws NetworkException;

	public NetworkPort getNetworkPort();
	
}