li/cil/oc/api/network/Node.java

package li.cil.oc.api.network;

import li.cil.oc.api.Persistable;

/**
 * A single node in a {@link Network}.
 * <p/>
 * All nodes in a network have a unique address; the network will generate a
 * unique address and assign it to new nodes.
 * <p/>
 * Per default there are two kinds of nodes: tile entities and items.
 * <p/>
 * Items will usually only have nodes when in containers, such as a computer or
 * disk drive. Otherwise you'll have to connect/disconnect them manually as
 * desired.
 * <p/>
 * All other kinds of nodes you may come up with will also have to be
 * handled manually.
 * <p/>
 * Items have to be handled by a corresponding {@link li.cil.oc.api.driver.Item}.
 * Existing blocks may be interfaced with the adapter block if a
 * {@link li.cil.oc.api.driver.Block} exists that supports the block.
 * <p/>
 * <em>Important</em>: like the <tt>Network</tt> interface you must not create
 * your own implementations of this interface. Use the factory methods in the
 * network API to create new node instances and store them in your environment.
 *
 * @see Component
 */
public interface Node extends Persistable {
    /**
     * The environment hosting this node.
     * <p/>
     * For blocks whose tile entities implement {@link Environment} this will
     * be the tile entity. For all other implementations this will be a managed
     * environment.
     */
    Environment host();

    /**
     * The reachability of this node.
     * <p/>
     * This is used by the network to control which system messages to deliver
     * to which nodes. This value should not change over the lifetime of a node.
     * <p/>
     * It furthermore determines what is returned by the <tt>Network</tt>'s
     * <tt>neighbors</tt> and <tt>nodes</tt> functions.
     * <p/>
     * Note that this has no effect on the <em>real</em> reachability of a node;
     * it is only used to filter to which nodes to send connect, disconnect and
     * reconnect messages. If addressed directly, the node will still receive
     * that message even if it comes from a node that should not be able to see
     * it. Therefore nodes should still verify themselves that they want to
     * accept a message from the message's source.
     * <p/>
     * A different matter is a {@link Component}'s <tt>visibility</tt>, which is
     * checked before delivering messages a computer tries to send.
     */
    Visibility reachability();

    /**
     * The address of the node, so that it can be found in the network.
     * <p/>
     * This is used by the network manager when a node is added to a network to
     * assign it a unique address, if it doesn't already have one. Nodes must not
     * use custom addresses, only those assigned by the network. The only option
     * they have is to *not* have an address, which can be useful for "dummy"
     * nodes, such as cables. In that case they may ignore the address being set.
     */
    String address();

    /**
     * The network this node is currently in.
     * <p/>
     * Note that valid nodes should never return `None` here. When created a node
     * should immediately be added to a network, after being removed from its
     * network a node should be considered invalid.
     * <p/>
     * This will always be set automatically by the network manager. Do not
     * change this value and do not return anything that it wasn't set to.
     */
    Network network();

    // ----------------------------------------------------------------------- //

    /**
     * Checks whether this node is a neighbor of the specified node.
     *
     * @param other the node to check for.
     * @return whether this node is directly connected to the other node.
     */
    boolean isNeighborOf(Node other);

    /**
     * Checks whether this node can be reached from the specified node.
     *
     * @param other the node to check for.
     * @return whether this node can be reached from the specified node.
     */
    boolean canBeReachedFrom(Node other);

    /**
     * Get the list of neighbor nodes, i.e. nodes directly connected to this
     * node.
     * <p/>
     * This is a shortcut for <tt>node.network.neighbors(node)</tt>.
     * <p/>
     * If this node is not in a network, i.e. <tt>network</tt> is <tt>null</tt>,
     * this returns an empty list.
     *
     * @return the list of nodes directly connected to this node.
     */
    Iterable<Node> neighbors();

    /**
     * Get the list of nodes reachable from this node, based on their
     * {@link #reachability()}.
     * <p/>
     * This is a shortcut for <tt>node.network.nodes(node)</tt>.
     * <p/>
     * If this node is not in a network, i.e. <tt>network</tt> is <tt>null</tt>,
     * this returns an empty list.
     *
     * @return the list of nodes reachable from this node.
     */
    Iterable<Node> reachableNodes();

    // ----------------------------------------------------------------------- //

    /**
     * Connects the specified node to this node.
     * <p/>
     * This is a shortcut for <tt>node.network.connect(node, other)</tt>.
     * <p/>
     * If this node is not in a network, i.e. <tt>network</tt> is <tt>null</tt>,
     * this will throw an exception.
     *
     * @param node the node to connect to this node.
     * @throws NullPointerException if <tt>network</tt> is <tt>null</tt>.
     */
    void connect(Node node);

    /**
     * Disconnects the specified node from this node.
     * <p/>
     * This is a shortcut for <tt>node.network.disconnect(node, other)</tt>.
     * <p/>
     * If this node is not in a network, i.e. <tt>network</tt> is <tt>null</tt>,
     * this will do nothing.
     *
     * @param node the node to connect to this node.
     * @throws NullPointerException if <tt>network</tt> is <tt>null</tt>.
     */
    void disconnect(Node node);

    /**
     * Removes this node from its network.
     * <p/>
     * This is a shortcut for <tt>node.network.remove(node)</tt>.
     * <p/>
     * If this node is not in a network, i.e. <tt>network</tt> is <tt>null</tt>,
     * this will do nothing.
     */
    void remove();

    // ----------------------------------------------------------------------- //

    /**
     * Send a message to a node with the specified address.
     * <p/>
     * This is a shortcut for <tt>node.network.sendToAddress(node, ...)</tt>.
     * <p/>
     * If this node is not in a network, i.e. <tt>network</tt> is <tt>null</tt>,
     * this will do nothing.
     *
     * @param target the address of the node to send the message to.
     * @param name   the name of the message.
     * @param data   the data to pass along with the message.
     */
    void sendToAddress(String target, String name, Object... data);

    /**
     * Send a message to all neighbors of this node.
     * <p/>
     * This is a shortcut for <tt>node.network.sendToNeighbors(node, ...)</tt>.
     * <p/>
     * If this node is not in a network, i.e. <tt>network</tt> is <tt>null</tt>,
     * this will do nothing.
     *
     * @param name the name of the message.
     * @param data the data to pass along with the message.
     */
    void sendToNeighbors(String name, Object... data);

    /**
     * Send a message to all nodes reachable from this node.
     * <p/>
     * This is a shortcut for <tt>node.network.sendToReachable(node, ...)</tt>.
     * <p/>
     * If this node is not in a network, i.e. <tt>network</tt> is <tt>null</tt>,
     * this will do nothing.
     *
     * @param name the name of the message.
     * @param data the data to pass along with the message.
     */
    void sendToReachable(String name, Object... data);
}