package propagation;

import java.util.List;

/**
 * The <code>Node</code> interface represents a physical or logical target to
 * supervise.<br />
 * <code>Node</code>s mean target sensor, area and so on. Each node has one
 * summary <code>StateItem</code> and several physical <code>StateItem</code>s.<br />
 * The summary <code>StateItem</code> represents the <code>Node</code>'s summary
 * state, e.g., overall status. Physical <code>StateItem</code>s represents the <code>Node</code>'s
 * individual states.
 *
 * @author y-komori
 * @@org.jboss.cache.aop.InstanceOfAopMarker
 */
public interface Node {

   /**
    * Sets the RDN (relative distinguished name) to this node.<br />
    *
    * @param rdn the RDN to set.
    */
   public void setNodeRDN(String rdn);

   /**
    * Returns this node's RDN.<br />
    *
    * @return this node's RDN.
    */
   public String getNodeRDN();

   /**
    * Sets the FDN to this node.<br />
    * The FDN is fully distinguished name of this node. FDN indicates where the
    * node is in the propagation tree. A node's FDN is made of the parent
    * node's FDN and it's own RDN.
    * <p/>
    * For example, if
    * a parent node's FDN is <code>root.foo</code>
    * , this node's RDN is <code>bar</code> then
    * this node's FDN is <ocde>root.foo.bar</code>
    *
    * @param fdn the FDN to set.
    */
   public void setNodeFDN(String fdn);

   /**
    * Returns this node's FDN.
    *
    * @return this node's FDN.
    */
   public String getNodeFDN();

   /**
    * Appends the specified child node to this node.
    * Note that each node can have multiple child nodes.
    *
    * @param child a child node to be appended to this node.
    */
   public void addChildNode(Node child);

   /**
    * Returns this node's child nodes List.
    *
    * @return this node's child nodes List.
    */
   public List getChildren();

   /**
    * Appends the specified <code>Node</code> as an upper node. An upper node is like a logical parent,
    * and it can have many upper nodes.
    *
    * @param upperNode a <code>Node</code> object to set as an upper node.
    */
   public void addUpperNode(Node upperNode);

   /**
    * Returns this node's upper nodes List.<br />
    *
    * @return this node's upper nodes List.
    */
   public List getUpperNodes();

   /**
    * Sets the specified node to this node as a parent node.
    * Each node can have only one node as a parent node. If any parent node
    * isn't be set, the node is treated as a root node.
    *
    * @param parent a node to be set as a parent node.
    */
   public void setParentNode(Node parent);

   /**
    * Returns this node's patent node.<br />
    * If this node hasn't any parent node, returns null.
    *
    * @return this node's parent node
    */
   public Node getParentNode();

   /**
    * Appends the specified <code>StateItem</code> object to this node.
    * Each node can have multiple <code>StateItem</code> objects.
    *
    * @param stateItem a <code>StateItem</code> object to be appended to this node.
    */
   public void addStateItem(StateItem stateItem);

   /**
    * Sets the specified <code>StateItem</code> object to this node as a
    * summary state.<br />
    * Summary <code>StateItem</code> object is a special
    * <code>StateItem</code> object which indicates this node's summary (e.g., overall status). Each
    * node can have only one <code>StateItem</code> object as a summary
    * state.
    *
    * @param stateItem a StateItem object to be set as a summary state.
    */
   public void setSummaryStateItem(StateItem stateItem);

   /**
    * Returns this node's summary <code>StateItem</code> object.
    * If this node hasn't any summary StateItem object which is set using
    * <code>setSummaryStateItem()</code>, returns null.
    *
    * @return a summary <code>StateItem</code> object.
    */
   public StateItem getSummaryStateItem();

   /**
    * Returns this node's <code>StateItem</code> object's list.
    * Notice that the summary <code>StateItem</code> isn't included in the
    * returned list.
    *
    * @return this node's <code>StateItem</code> object's list.
    */
   public List getStateItems();

   /**
    * Returns the <code>StateItem</code> object which has specified item ID.
    * Returns <code>null</code> if the <code>StateItem</code> is not found
    * there.
    *
    * @param itemId the StateItem's item ID to find.
    * @return the <code>StateItem</code> object, or <code>null</code> if
    *         none.
    */
   public StateItem findStateItem(long itemId);

   /**
    * Sets the specifies <code>PropagationRule</code> object to this node.
    *
    * @param rule a PropagationRule object to be set.
    */
   public void setPropagationRule(PropagationRule rule);

   /**
    * Returns this node's <code>PropagationRule</code> object. Returns
    * <code>null</code> if this node has no <code>PropagationRule</code>
    * object.
    *
    * @return this node's <code>PropagationRule</code> object, or
    *         <code>null</code> if none.
    */
   public PropagationRule getPropagationRule();
}
