package propagation;

/**
 * The PropagationManager interface represents "propagation tree". This is the frontend and logical representation
 * of the whole network.
 *
 * @author y-komori
 * @@org.jboss.cache.aop.InstanceOfAopMarker
 */
public interface PropagationManager {
   /**
    * Creates and sets the root <code>Node</code> which has specified RDN to
    * this propagation tree.
    *
    * @param rdn the root <code>Node</code>'s RDN.
    */
   public void setRootNode(String rdn);

   /**
    * Creates a new <code>Node</code> object and register to the propagation
    * tree.
    *
    * @param fdn the new <code>Node</code>'s FDN
    * @param rdn the new <code>Node</code>'s RDN
    * @return created <code>Node</code> object
    */
   public Node createNode(String fdn, String rdn);

   /**
    * Creates and appends a new <code>Node</code> to this propagation tree as
    * the specified <code>Node</code>'s children.
    *
    * @param parentFdn the parent <code>Node</code>'s FDN
    * @param rdn       the new <code>Node</code>'s RDN
    */
   public void addNode(String parentFdn, String rdn);

   /**
    * Sets the <code>Node</code> object to the lower <code>Node</code>
    * object as a upper node.
    *
    * @param upperFdn the upper <code>Node</code>'s FDN
    * @param lowerFdn the lower <code>Node</code>'s FDN
    */
   public void setUpperNode(String upperFdn, String lowerFdn);

   /**
    * Creates and appends a new <code>StateItem</code> to the Node identified
    * by the specified parent FDN and item ID.
    *
    * @param parentFdn    the parent <code>Node</code>'s FDN
    * @param itemId       the new <code>StateItem</code>'s item ID
    * @param name         a logical name
    * @param defaultState the new <code>StateItem</code>'s default state.
    */
   public void addStateItem(String parentFdn, long itemId, String name, long defaultState);

   /**
    * Finds the <code>Node</code> identified by the specified FDN.
    * If it can't find the specified <code>Node</code>, returns
    * <code>null</code>.
    *
    * @param fdn the target <code>Node</code>'s FDN.
    * @return found <code>Node</code> object or <code>null</code>.
    */
   public Node findNode(String fdn);

   /**
    * Changes the <code>Node</code>'s state to the specified new state.
    * The target Node is identified by the specified FDN and item ID.<br />
    *
    * @param fdn      the target <code>Node</code>'s FDN.
    * @param itemId   the target item ID.
    * @param newState a new state to change.
    */
   public void stateChange(String fdn, long itemId, long newState);

   /**
    * Prints the propagation tree's all <code>Node</code>'s and state.
    */
   public void printNodes();

   /**
    * Prints the propagation tree from the <code>Node</code> identified by
    * the specified FDN.<br />
    *
    * @param fdn the top <code>Node</code>'s FDN
    */
   public void printNodes(String fdn);
}
