001// Copyright 2011 The Apache Software Foundation
002//
003// Licensed under the Apache License, Version 2.0 (the "License");
004// you may not use this file except in compliance with the License.
005// You may obtain a copy of the License at
006//
007// http://www.apache.org/licenses/LICENSE-2.0
008//
009// Unless required by applicable law or agreed to in writing, software
010// distributed under the License is distributed on an "AS IS" BASIS,
011// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
012// See the License for the specific language governing permissions and
013// limitations under the License.
014
015package org.apache.tapestry5.tree;
016
017import java.util.List;
018
019import javax.swing.tree.TreeSelectionModel;
020
021import org.apache.tapestry5.ValueEncoder;
022import org.apache.tapestry5.corelib.components.Tree;
023
024/**
025 * A model for tree-oriented data used by the {@link Tree} component. The default implemention, {@link DefaultTreeModel}
026 * uses a {@link ValueEncoder} and a {@link TreeModelAdapter} to supply the
027 * underlying information.
028 * 
029 * @param <T>
030 *            type of data in the tree
031 * @since 5.3
032 * @see TreeSelectionModel
033 */
034public interface TreeModel<T>
035{
036    /**
037     * Returns the node or nodes that are the top level of the tree.
038     */
039    List<TreeNode<T>> getRootNodes();
040
041    /**
042     * Locates a node in the tree by its unique id.
043     * 
044     * @throws IllegalArgumentException
045     *             if no such node exists
046     * @see TreeNode#getId()
047     */
048    TreeNode<T> getById(String id);
049
050    /**
051     * Recursively searches from the root nodes to find the tree node that matches
052     * the provided element.
053     * 
054     * @param element
055     *            to search for
056     * @return matching node, or null if not found
057     */
058    TreeNode<T> find(T element);
059}