package org.okip.util.hierarchy.api;

/*
   Copyright (c) 2002 Massachusetts Institute of Technology

   This work, including any software, documents, or other related items
   (the "Work"), is being provided by the copyright holder(s) subject to
   the terms of the MIT OKI(TM) API Definition License. By obtaining,
   using and/or copying this Work, you agree that you have read,
   understand, and will comply with the following terms and conditions of
   the MIT OKI(TM) API Definition License:

   You may use, copy, and distribute unmodified versions of this Work for
   any purpose, without fee or royalty, provided that you include the
   following on ALL copies of the Work that you make or distribute:

    *  The full text of the MIT OKI(TM) API Definition License in a
       location viewable to users of the redistributed Work.

    *  Any pre-existing intellectual property disclaimers, notices, or
       terms and conditions. If none exist, a short notice similar to the
       following should be used within the body of any redistributed
       Work: "Copyright (c) 2002 Massachusetts Institute of Technology. All
       Rights Reserved."

   You may modify or create Derivatives of this Work only for your
   internal purposes. You shall not distribute or transfer any such
   Derivative of this Work to any location or any other third party. For
   purposes of this license, "Derivative" shall mean any derivative of
   the Work as defined in the United States Copyright Act of 1976, such
   as a translation or modification.

   THIS WORK PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
   IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
   MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
   IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
   CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
   TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE WORK
   OR THE USE OR OTHER DEALINGS IN THE WORK.

   The name and trademarks of copyright holder(s) and/or MIT may NOT be
   used in advertising or publicity pertaining to the Work without
   specific, written prior permission. Title to copyright in the Work and
   any associated documentation will at all times remain with the
   copyright holders.
*/

/**
 * <p>Node objects are contained by Hierarchies.  They represent a link in 
 * those Hierarchies, but do not contain data.  They merely represent
 * relationships between objects.
 */

public interface Node
{
	/**
	 * <p>Constant indicating depth-first traversal.
	 */
	public static final int TRAVERSE_MODE_DEPTH_FIRST   = 0xdf;
	
	/**
	 * <p>Constant indicating breadth-first traversal.
	 */
	public static final int TRAVERSE_MODE_BREADTH_FIRST = 0xbf;
	
	/**
	 * <p>Constant indicating traversal up the hierarchy, or traversal of parents.
	 */
	public static final int TRAVERSE_DIRECTION_UP       = 0x01;
	
	/**
	 * <p>Constant indicating traversal down the hierarchy, or traversal of children.
	 */
	public static final int TRAVERSE_DIRECTION_DOWN     = 0x02;
	
	/**
	 * <p>Constant indicating no limit on the depth of traversal.
	 */
	public static final int TRAVERSE_LEVELS_INFINITE    = -1;

	/**
	 * <p>Get the key associated with this Node.
	 * @return The associated key object.
	 */
	public java.io.Serializable getKey();
	
	/**
	 * <p>Get the name associated with this Node.
	 * @return The associated name.
	 */
	public String getName() throws HierarchyException;

	/**
	 * <p>Get the parents of this Node, in no guaranteed order.
	 * @return An array of all Nodes that are parents of this Node.
	 */
	public Node[] getParents() throws HierarchyException;
	
	/**
	 * <p>Get the children of this Node, in no guaranteed order.
	 * @return An array of all Nodes that are children of this Node.
	 */
	public Node[] getChildren() throws HierarchyException;
	
	/**
	 * <p>Get the leaf status of this node.  A Node is a leaf if and only if
	 * it has no children.
	 * @return True if this Node has no children, otherwise false.
	 */
	public boolean isLeaf() throws HierarchyException;
	
	/**
	 * <p>Get the root status of this node.  A Node is a root if and only if
	 * it has no parents.
	 * @return True if this Node has no parents, otherwise false.
	 */
	public boolean isRoot() throws HierarchyException;
	
	/**
	 * <p>Delete this node from its Hierarchy.
	 * @throws HierarchyException If the deletion of this node causes a state
	 * inconsistency, depending on the implementation.
	 */
	public void delete() throws HierarchyException;
	
	/**
	 * <p>Add a parent to this Node.
	 * @param qKey The key to the Node in this Hierarchy that will be added.
	 * @throws HierarchyException If qKey.equals( this.getKey() ) or the
	 *         parent Node is not in the same Hierarchy.
	 */
	public void addParent( java.io.Serializable qKey ) throws HierarchyException;
	
	/**
	 * <p>Unlink a parent from this Node.
	 * @param qKey The key to the Node in this Hierarchy that will be unlinked.
	 * @throws HierarchyException If the disconnection causes a state
	 * inconsistency, depending on the implementation.
	 */
	public void removeParent( java.io.Serializable qKey ) throws HierarchyException;

	/**
	 * <p>Traverse the Hierarchy starting at this Node.
	 * @param qMode Must be either TRAVERSE_MODE_DEPTH_FIRST or 
	 *        TRAVERSE_MODE_BREADTH_FIRST, indicating either depth-first 
	 *        or breadth-first traversal.
	 * @param qDirection Must be either TRAVERSE_DIRECTION_UP or
	 *        TRAVERSE_DIRECTION_DOWN, indicating the whether the traversal
	 *        should proceed up the parents or down the children.
	 * @param qFilter Examines each node to filter the results.
	 * @param qLevels The number of levels to traverse.  If this value is
	 *        < 0 (or TRAVERSE_LEVELS_INFINITE, which equals -1), the traversal
	 *        will proceed all the way to the end of the Hierarchy or until a
	 *        circular reference returns to a Node already traversed.
	 * @return An array of NodeInfo, where each NodeInfo object contains
	 *         information on the Nodes traversed in the order they were hit.
	 */
	public NodeInfo[] traverse( int qMode, int qDirection, NodeFilter qFilter, int qLevels ) throws HierarchyException;
}