001/*
002 * (C) Copyright 2006-2008 Nuxeo SAS (http://nuxeo.com/) and contributors.
003 *
004 * All rights reserved. This program and the accompanying materials
005 * are made available under the terms of the GNU Lesser General Public License
006 * (LGPL) version 2.1 which accompanies this distribution, and is available at
007 * http://www.gnu.org/licenses/lgpl.html
008 *
009 * This library is distributed in the hope that it will be useful,
010 * but WITHOUT ANY WARRANTY; without even the implied warranty of
011 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
012 * Lesser General Public License for more details.
013 *
014 * Contributors:
015 *     bstefanescu
016 *
017 * $Id$
018 */
019
020package org.nuxeo.ecm.webengine.ui.tree;
021
022import java.io.Serializable;
023
024import org.nuxeo.common.utils.Path;
025
026/**
027 * @author <a href="mailto:bs@nuxeo.com">Bogdan Stefanescu</a>
028 */
029public interface TreeItem extends Serializable {
030
031    int NONE = 0;
032
033    int DATA = 1;
034
035    int CHILDREN = 2;
036
037    int BOTH = 3;
038
039    /**
040     * Gets the item path.
041     * <p>
042     * The path is uniquely identifying the item in its tree and is consistent with the tree structure so the parent
043     * item will have the same path as the child minus the last segment. The root item path will always be "/". (The
044     * root item should not be displayed in the tree - it has no label or other properties.)
045     * <p>
046     * Paths are useful to locate items in the tree using <code>find</find> methods.
047     *
048     * @return the item path
049     * @see #find(Path)
050     * @see #findAndReveal(Path)
051     * @see TreeModel#find(Path)
052     * @see TreeModel#findAndReveal(Path)
053     */
054    Path getPath();
055
056    /**
057     * Gets the object attached to this item.
058     * <p>
059     * The nature of the object depends on the registered content provider which will populate the tree branches when
060     * {@link ContentProvider#getChildren(Object)} is called. The root item is specified by using
061     * {@link TreeModel#setInput(Object)}
062     *
063     * @return the attached object or null if none
064     */
065    Object getObject();
066
067    /**
068     * Gets the parent item or null if this is the root item.
069     *
070     * @return the parent item
071     */
072    TreeItem getParent();
073
074    /**
075     * Gets this node name.
076     * <p>
077     * This is the same as the last segment on the item path
078     */
079    String getName();
080
081    /**
082     * Gets the label to be displayed for this item.
083     */
084    String getLabel();
085
086    /**
087     * Tests whether or not the item is expanded.
088     *
089     * @return true of expanded, false otherwise
090     */
091    boolean isExpanded();
092
093    /**
094     * Tests whether or not the item may have children.
095     *
096     * @return true if a container, false otherwise
097     */
098    boolean isContainer();
099
100    /**
101     * Gets the cached children.
102     * <p>
103     * The children items are created using the content provider the first time you call {@link #expand()}
104     */
105    TreeItem[] getChildren();
106
107    /**
108     * Gets the child item given its name.
109     * <p>
110     * This method will force loading children using the provider if not already loaded or if invalidated.
111     *
112     * @param name the name of the child item
113     * @return the child item or null if none
114     */
115    TreeItem getChild(String name);
116
117    /**
118     * Tests whether this item has any children.
119     * <p>
120     * This method will not load children if not already loaded.
121     *
122     * @return true if the children item has children, false otherwise
123     */
124    boolean hasChildren();
125
126    /**
127     * Finds the item given its relative path to that item.
128     * <p>
129     * This method will search only the loaded items - it will not make additional calls to provider to get new items.
130     *
131     * @param path the item path to find
132     * @return the item or null if none.
133     */
134    TreeItem find(Path path);
135
136    /**
137     * Finds the item given its relative path to that item and expand all its parents so that the item will be visible
138     * in the tree.
139     * <p>
140     * The item itself will not be expanded. Use {@link #expand()} on the returned item if you want so.
141     * <p>
142     * This method is loading any parent if not already loaded by using the registered provider.
143     *
144     * @param path the item path to find
145     * @return the item or null if none
146     */
147    TreeItem findAndReveal(Path path);
148
149    /**
150     * Expands the item.
151     * <p>
152     * This will load children items from the provider if they are not already loaded or if invalidated.
153     */
154    TreeItem[] expand();
155
156    /**
157     * Collapses this item. This will hide any loaded children.
158     */
159    void collapse();
160
161    /**
162     * Reloads item information like label, properties and children depending on the specified refresh type.
163     * <p>
164     * The argument is used to specify the type of refresh and can have one of the following values:
165     * <ul>
166     * <li>{@link #DATA} - to refresh only item data like labels
167     * <li>{@link #CHILDREN} - to refresh only item children
168     * <li>{@link #BOTH} - to refresh both data and children
169     * </ul>
170     *
171     * @param type of refresh
172     */
173    void refresh(int type);
174
175    /**
176     * Invalidates the item.
177     * <p>
178     * This will force reloading item data and/or children next time item and/or children are accessed. The argument is
179     * used to specify the type of invalidation and can have one of the following values:
180     * <ul>
181     * <li>{@link #DATA} - to invalidate only item data like labels
182     * <li>{@link #CHILDREN} - to invalidate only item children
183     * <li>{@link #BOTH} - to invalidate both data and children
184     * </ul>
185     *
186     * @param type of invalidation
187     */
188    void invalidate(int type);
189
190    /**
191     * Validates the item.
192     * <p>
193     * If the item was not invalidated do nothing.
194     */
195    void validate();
196
197    /**
198     * Returns the validation state.
199     * <p>
200     * Can be one of:
201     * <ul>
202     * <li>{@link #DATA} - the item data is invalid (not loaded or invalidated)
203     * <li>{@link #CHILDREN} - the item children are invalid
204     * <li>{@link #BOTH} - both data and children are invalid
205     * </ul>
206     *
207     * @return the validation state.
208     */
209    int getValidationState();
210
211    /**
212     * Gets the current content provider.
213     *
214     * @return the content provider. never return null
215     */
216    ContentProvider getContentProvider();
217
218    /**
219     * Accepts a visitor. This is to support visitor pattern.
220     *
221     * @param visitor the visitor to accept
222     * @return the result of the visit
223     */
224    Object accept(TreeItemVisitor visitor);
225
226}