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}