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