package treecms.api;

import treecms.tree.util.PathNotFoundException;

/**
 * 木構造を非破壊的に更新する機能を提供します．TreeEditorはTreeを非破壊的に更新していき，commitすることでTreeに更新を適用します．
 * TreeEditor.getRootはcommitされていない状態のRootNodeを取得します．
 * この機能は分散リポジトリを参考に考案されました．
 * @author shoshi
 */
public interface MonotonicTree
{
	/**
	 * 非破壊的に更新した木構造を適用します．
	 * 更新する際に他の方法により木構造がすでに更新されていた場合，commitは失敗します。_forceがtrueの場合，強制的に置き換えます． 
	 * @param _force 強制コミットフラグ
	 * @return 成功した場合true，失敗した場合false
	 */
	public boolean commit(boolean _force);
	
	/**
	 * 監視している木構造をEditorにキャッシュします．
	 * @return キャッシュが成功した場合はtrue，失敗した場合はfalse
	 */
	public boolean pull();
	
	/**
	 * 監視されている木構造が更新されていないかチェックします．
	 * @return 更新されていた場合はture，されていない場合はfalse
	 */
	public boolean check();
	
	/**
	 * 監視している木構造をキャッシュにマージします．
	 */
	public void merge();
	
	/**
	 * この木構造のルートNodeを返します。
	 * @return この木構造のルートNode
	 */
	public Node getRoot();
	
	/**
	 * 木構造を非破壊的に更新します．変更の対象となるNodeが木構造内に見つからない場合，PathNotFoundExceptionがスローされます．
	 * @param _target 更新する対象のNode
	 * @param _newData 新しいNodeに割り当てられるNodeData
	 * @return 更新された新しいNode
	 * @throws PathNotFoundException パスが見つからない場合
	 */
	public Node updateTree(Node _target,NodeData _newData) throws PathNotFoundException;
	
	/**
	 * 木構造を非破壊的に更新します．Nodeへのパスが既知な場合このメソッドを使用できます。
	 * このメソッドは使用時にパスの正当性を検証します。見つからない場合PathNotFoundExceptionがスローされます
	 * @param _target
	 * @param _newData
	 * @param _path
	 * @return 更新された新しいNode
	 * @throws PathNotFoundException 
	 */
	public Node updateTree(Node _target,NodeData _newData,Node[] _path) throws PathNotFoundException;
}