li/cil/oc/api/INetworkNode.java

package li.cil.oc.api;

/**
 * A single node in a {@link Network}.
 * 
 * <p>
 * All nodes in a network <em>should</em> have a unique address; the network
 * will try to generate a unique address and assign it to new nodes. A node must
 * never ever change its address while in a network (because the lookup-table in
 * the network manager would not be notified of this change). If you must change
 * the address, remove the node first, change the address and then add it again.
 * </p>
 * 
 * <p>
 * Per default there are two kinds of nodes: tile entities and item components.
 * If a <tt>TileEntity</tt> implements this interface adding/removal from its
 * network on load/unload will automatically be handled and you will only have
 * to ensure it is added/removed to/from a network when the corresponding block
 * is added/removed. Item components in containers have to be handled manually.
 * All other kinds of nodes you may come up with will also have to be handled
 * manually.
 * </p>
 */
public interface INetworkNode {
  /**
   * The address of the node, so that it can be found in the network.
   * 
   * @return the id of this node.
   */
  int getAddress();

  /**
   * Set the address of the node.
   * 
   * <p>
   * This is used by the network manager when a node is added to a network to
   * assign it a unique address in that network. Nodes should avoid using custom
   * addresses since that could lead to multiple nodes with the same address in
   * a network. Note that that in and by itself is supported however, it is just
   * harder to work with.
   * </p>
   * 
   * <p>
   * Some nodes may however wish to simply ignore this and always provide the
   * same address (e.g. zero), when they are never expected to be used by other
   * nodes (cables, for example).
   * </p>
   * 
   * @param value
   *          the new address for the node.
   */
  void setAddress(int value);

  /**
   * The network this node is currently in.
   * 
   * <p>
   * Note that valid nodes should never return <tt>null</tt> here. When created
   * a node should immediately be added to a network, after being removed from
   * its network it should be considered invalid.
   * </p>
   * 
   * @return the network the node is in.
   */
  INetwork getNetwork();

  /**
   * Sets the network the node is currently in.
   * 
   * <p>
   * This is mainly used by the {@link NetworkAPI} and the network itself when
   * merging with another network. You should never have to call this yourself.
   * </p>
   * 
   * @param network
   *          the network the node now belongs to.
   */
  void setNetwork(INetwork network);

  /**
   * Makes the node handle a message.
   * 
   * @param message
   *          the message to handle.
   */
  void receive(INetworkMessage message);
}