/*
 * Copyright (c) 2003,2009 Declarative Engineering LLC.
 * All rights reserved.  This program and the accompanying materials
 * are made available under the terms of the Declarative Engineering LLC
 * verson 1 which accompanies this distribution, and is available at
 * http://declarativeengineering.com/legal/DE_Developer_License_v1.txt
 */
package com.common.util;

/**
 * Defines a tree consisting of a set of nodes each referencing a value.  Values are placed into the tree and the tree manages the associations between the values.
 */
public interface ITree extends ICollection {
/**
 * Adds the given value to the tree under the parent value.
 * @param parent The value's parent value, or null if this is a root level tree value.
 * @param value A value to add to the tree.
 * @return Will be true if the operation was a success.
 */
public boolean add(Object parent, Object value);
/**
 * Adds the given value to the tree under the parent value.
 * @param parent The value's parent value, or null if this is a root level tree value.
 * @param value A value to add to the tree.
 * @param context The context under which the change is being made.
 * @return Will be true if the operation was a success.
 */
public boolean add(Object parent, Object value, byte context);
/**
 * Adds the given values to the tree under the parent value.
 * @param parent The parent for the new values.
 * @param values The values to add to the tree.
 * @return Will be true if the operation was a success.
 */
public boolean addAll(Object parent, Object[] values);
/**
 * Adds the given values to the tree under the parent value.
 * @param parent The parent for the new values.
 * @param values The values to add to the tree.
 * @param context The context under which the change is being made.
 * @return Will be true if the operation was a success.
 */
public boolean addAll(Object parent, Object[] values, byte context);
/**
 * Adds the given values to the tree under the parent value.
 * @param parent The parent for the new values.
 * @param values The values to add to the tree.
 * @return Will be true if the operation was a success.
 */
public boolean addAll(Object parent, ICollection values);
/**
 * Adds the given values to the tree under the parent value.
 * @param parent The parent for the new values.
 * @param values The values to add to the tree.
 * @param context The context under which the change is being made.
 * @return Will be true if the operation was a success.
 */
public boolean addAll(Object parent, ICollection values, byte context);
/**
 * Adds the given tree of values to the tree under the parent value.
 * @param parent The parent for the new values.
 * @param values The tree of values to add to the tree.
 * @return Will be true if the operation was a success.
 */
public boolean addAll(Object parent, ITree values);
/**
 * Adds the given tree of values to the tree under the parent value.
 * @param parent The parent for the new values.
 * @param values The tree of values to add to the tree.
 * @param context The context under which the change is being made.
 * @return Will be true if the operation was a success.
 */
public boolean addAll(Object parent, ITree values, byte context);
/**
 * Gets the value's child count.
 * @param value The value whose children are to be counted, or null for root level values.
 * @return The number of children under the given tree value.
 */
public int getChildCount(Object value);
/**
 * Gets the value's children.
 * @param value The value whose children are to be found, or null for root level values.
 * @return The tree of children for the given value.
 */
public ITree getChildren(Object value);
/**
 * Gets the value's children.
 * @param value The value whose children are to be found, or null for root level values.
 * @param children The collection that the children will be added to.
 * @return Whether the operation was successful.
 */
public boolean getChildren(Object value, IList children);
/**
 * Gets the value's parent value.
 * @param value The value whose parent value is to be found.
 * @return The parent value for the given value, or null if there isn't one (the value is a root level value).
 */
public Object getParent(Object value);
/**
 * Gets a depth first iterator over all of the tree values.
 * @param rootValue The root of the iterator.
 * @return An iterator that will iterate over all the tree values using a depth first algorithm.
 */
public IIterator iterator(Object rootValue);
/**
 * Gets a depth first iterator over all of the tree values.
 * @param depthFirst Whether the iterator should start at the bottom and traverse from left to right.  A standard iterator starts at the top and works from left to right (first to last).
 * @return An iterator that will iterate over all the tree values using a depth first algorithm.
 */
public IIterator iteratorDepthFirst();
/**
 * Gets a depth first iterator over all of the tree values.
 * @param rootValue The root of the iterator.
 * @param depthFirst Whether the iterator should start at the bottom and traverse from left to right.  A standard iterator starts at the top and works from left to right (first to last).
 * @return An iterator that will iterate over all the tree values using a depth first algorithm.
 */
public IIterator iteratorDepthFirst(Object rootValue);
}//ITree//