package treecms.api;

import java.util.Iterator;
import java.util.List;
import java.util.Map;
import java.util.Set;
import java.nio.ByteBuffer;

/**
 * 木構造の基本のデータ単位であるNodeを示します．Nodeは子供のリストとデータのマップを保持します．また，クライアントはノードが保持しているデータをNodeDataとして
 * 取得することが出来ます．
 * 
 * NodeはSingleLinkで子供Nodeへのパスしか保持していません、どのNodeが親かどうか判断するのは不可能です．
 * このようにしたのは，非破壊的木構造を実装するに当たり，編集対象のNodeの親を検索するのが困難であるからです．
 * DoubleLinkな実装はTree/MonotonicTreeで行います．
 * 
 * また，重複した子供を追加することは出来ません，このインターフェイスを実装するクラスはそのように実装します．
 * @author shoshi
 */
public interface Node
{
	/**
	 * Nodeに対応するNodeIDを取得します．
	 * @return Nodeに対応するNodeID
	 */
	public NodeID getID();
	
	/**
	 * Nodeが保持するデータを取得します．クライアントはこのメソッドを用いて取得されるNodeDataを用いてNodeの内容を<b>変更できません</b>。
	 * 変更を加えた場合は無視されるか、例外が発生します．
	 * @return Nodeが保持するNodeData
	 */
	public NodeData getData();
	
	/**
	 * Nodeが属するForestを取得します．
	 * @return Nodeが属するForest
	 */
	public Forest getForest();
	
	/*
	 * 属性関連のメソッド
	 * get,getAll,put,putAll,remove,removeAll,clear
	 */
	
	/**
	 * このNodeが保持する値の中で指定されたキーと対応する値を取得します．
	 * @param _key データに対応するキー
	 * @return キーと対応する値，見つからない場合はnull
	 */
	public ByteBuffer get(ByteBuffer _key);
	
	/**
	 * このNodeが保持するデータをマップとしてすべて取得します．
	 * @return Nodeが保持するすべてのデータのマップ
	 */
	public Map<ByteBuffer,ByteBuffer> getAll();
	
	/**
	 * キーとそれに対応する値を保存します．キーが重複した場合は上書きされます．
	 * @param _key キー
	 * @param _value 値
	 */
	public void put(ByteBuffer _key,ByteBuffer _value);
	
	/**
	 * キーとそれに対応する値を複数保持するマップを引数としてとり，マップが保持する値をすべて追加します．
	 * @param _map 追加される値のマップ
	 */
	public void putAll(Map<ByteBuffer,ByteBuffer> _map);
	
	/**
	 * キーとそれに対応する値を削除します。
	 * @param _key キー
	 */
	public void remove(ByteBuffer _key);
	
	/**
	 * Keyの集合すべてを削除します．
	 * @param _key
	 */
	public void removeAll(Set<ByteBuffer> _key);
	
	/**
	 * Keyの集合全てを削除します．
	 */
	public void clear();
	
	/*
	 * 子供関連
	 * getChildren,addChild,addChildren,removeChild,removeChildren,clearChildren
	 */
	
	/**
	 * 子供のIteratorを取得します．このIteratorは編集するためのメソッドは実装しません．
	 * 呼び出した場合は例外は発生します．
	 * @return 子供NodeのIterator
	 */
	public Iterator<Node> getChildren();
	
	/**
	 * 指定されたNodeを子供Nodeとして追加します．
	 * @param _child
	 */
	public void addChild(Node _child);
	
	/**
	 * 指定されたリストに含まれるNodeを，すべて子供Nodeとして追加します．
	 * @param _children 追加される子供Nodeを保持するリスト
	 */
	public void addChildren(List<Node> _children);
	
	/**
	 * 指定されたNodeを削除します。
	 * @param _child
	 */
	public void removeChild(Node _child);
	
	/**
	 * 指定した子供を全て削除します．
	 * @param _children 削除される子供
	 */
	public void removeChildren(List<Node> _children);
	
	/**
	 * 全ての子供を削除します． 
	 */
	public void clearChildren();
	
	/**
	 * このNodeのクローンを作成します．
	 * 
	 * クローンされたNodeはNodeIDとデータを受け継ぎます．クローンする際にデータに変更を加えることが出来ます．
	 * 変更を加える必要がない場合はnullを_dataに引数として渡します．
	 * 
	 * @param _data クローンされるNodeに適用されるNodeData
	 */
	public Node cloneNode(NodeData _data);
}