001/* 002 * Copyright 2006 - 2013 003 * Stefan Balev <stefan.balev@graphstream-project.org> 004 * Julien Baudry <julien.baudry@graphstream-project.org> 005 * Antoine Dutot <antoine.dutot@graphstream-project.org> 006 * Yoann Pigné <yoann.pigne@graphstream-project.org> 007 * Guilhelm Savin <guilhelm.savin@graphstream-project.org> 008 * 009 * This file is part of GraphStream <http://graphstream-project.org>. 010 * 011 * GraphStream is a library whose purpose is to handle static or dynamic 012 * graph, create them from scratch, file or any source and display them. 013 * 014 * This program is free software distributed under the terms of two licenses, the 015 * CeCILL-C license that fits European law, and the GNU Lesser General Public 016 * License. You can use, modify and/ or redistribute the software under the terms 017 * of the CeCILL-C license as circulated by CEA, CNRS and INRIA at the following 018 * URL <http://www.cecill.info> or under the terms of the GNU LGPL as published by 019 * the Free Software Foundation, either version 3 of the License, or (at your 020 * option) any later version. 021 * 022 * This program is distributed in the hope that it will be useful, but WITHOUT ANY 023 * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A 024 * PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details. 025 * 026 * You should have received a copy of the GNU Lesser General Public License 027 * along with this program. If not, see <http://www.gnu.org/licenses/>. 028 * 029 * The fact that you are presently reading this means that you have had 030 * knowledge of the CeCILL-C and LGPL licenses and that you accept their terms. 031 */ 032package org.graphstream.graph; 033 034import java.util.ArrayList; 035import java.util.Collection; 036import java.util.HashMap; 037import java.util.Iterator; 038import java.util.Map; 039 040/** 041 * An element is a part of a graph (node, edge, the graph itself). 042 * 043 * <p> 044 * An interface that defines common method to manipulate identifiers, attributes 045 * and indices of the elements (graph, nodes and edges) of a graph. 046 * </p> 047 * * 048 * <p> 049 * Attributes can be any object and are identified by arbitrary strings. Some 050 * attributes are stored as numbers or strings and are in this case named 051 * number, label or vector. There are utility methods to handle these attributes 052 * ({@link #getNumber(String)}, {@link #getLabel(String)}) or 053 * {@link #getVector(String)}, however they are also accessible through the more 054 * general method {@link #getAttribute(String)}. 055 * </p> 056 * 057 * <h3>Important</h3> 058 * <p> 059 * Implementing classes should indicate the complexity of their implementation 060 * for each method. 061 * </p> 062 * 063 * @since July 12 2007 064 * 065 */ 066public interface Element { 067 /** 068 * Unique identifier of this element. 069 * 070 * @return The identifier value. 071 */ 072 String getId(); 073 074 /** 075 * The current index of this element 076 * 077 * @return The index value 078 */ 079 int getIndex(); 080 081 /** 082 * Get the attribute object bound to the given key. The returned value may 083 * be null to indicate the attribute does not exists or is not supported. 084 * 085 * @param key 086 * Name of the attribute to search. 087 * @return The object bound to the given key or null if no object match this 088 * attribute name. 089 */ 090 // Object getAttribute( String key ); 091 <T> T getAttribute(String key); 092 093 /** 094 * Like {@link #getAttribute(String)}, but returns the first existing 095 * attribute in a list of keys, instead of only one key. The key list order 096 * matters. 097 * 098 * @param keys 099 * Several strings naming attributes. 100 * @return The first attribute that exists. 101 */ 102 // Object getFirstAttributeOf( String... keys ); 103 <T> T getFirstAttributeOf(String... keys); 104 105 /** 106 * Get the attribute object bound to the given key if it is an instance of 107 * the given class. Some The returned value maybe null to indicate the 108 * attribute does not exists or is not an instance of the given class. 109 * 110 * @param key 111 * The attribute name to search. 112 * @param clazz 113 * The expected attribute class. 114 * @return The object bound to the given key or null if no object match this 115 * attribute. 116 */ 117 // Object getAttribute( String key, Class<?> clazz ); 118 <T> T getAttribute(String key, Class<T> clazz); 119 120 /** 121 * Like {@link #getAttribute(String, Class)}, but returns the first existing 122 * attribute in a list of keys, instead of only one key. The key list order 123 * matters. 124 * 125 * @param clazz 126 * The class the attribute must be instance of. 127 * @param keys 128 * Several string naming attributes. 129 * @return The first attribute that exists. 130 */ 131 // Object getFirstAttributeOf( Class<?> clazz, String... keys ); 132 <T> T getFirstAttributeOf(Class<T> clazz, String... keys); 133 134 /** 135 * Get the label string bound to the given key key. Labels are special 136 * attributes whose value is a character sequence. If an attribute with the 137 * same name exists but is not a character sequence, null is returned. 138 * 139 * @param key 140 * The label to search. 141 * @return The label string value or null if not found. 142 */ 143 CharSequence getLabel(String key); 144 145 /** 146 * Get the number bound to key. Numbers are special attributes whose value 147 * is an instance of Number. If an attribute with the same name exists but 148 * is not a Number, NaN is returned. 149 * 150 * @param key 151 * The name of the number to search. 152 * @return The number value or NaN if not found. 153 */ 154 double getNumber(String key); 155 156 /** 157 * Get the vector of number bound to key. Vectors of numbers are special 158 * attributes whose value is a sequence of numbers. If an attribute with the 159 * same name exists but is not a vector of number, null is returned. 160 * 161 * @param key 162 * The name of the number to search. 163 * @return The vector of numbers or null if not found. 164 */ 165 ArrayList<? extends Number> getVector(String key); 166 167 /** 168 * Get the array of objects bound to key. Arrays of objects are special 169 * attributes whose value is a sequence of objects. If an attribute with the 170 * same name exists but is not an array, null is returned. 171 * 172 * @param key 173 * The name of the array to search. 174 * @return The array of objects or null if not found. 175 */ 176 Object[] getArray(String key); 177 178 /** 179 * Get the hash bound to key. Hashes are special attributes whose value is a 180 * set of pairs (name,object). Instances of object implementing the 181 * {@link CompoundAttribute} interface are considered like hashes since they 182 * can be transformed to a hash. If an attribute with the same name exists 183 * but is not a hash, null is returned. We cannot enforce the type of the 184 * key. It is considered a string and you should use "Object.toString()" to 185 * get it. 186 * 187 * @param key 188 * The name of the hash to search. 189 * @return The hash or null if not found. 190 */ 191 HashMap<?, ?> getHash(String key); 192 193 /** 194 * Does this element store a value for the given attribute key? 195 * 196 * @param key 197 * The name of the attribute to search. 198 * @return True if a value is present for this attribute. 199 */ 200 boolean hasAttribute(String key); 201 202 /** 203 * Does this element store a value for the given attribute key and this 204 * value is an instance of the given class? 205 * 206 * @param key 207 * The name of the attribute to search. 208 * @param clazz 209 * The expected class of the attribute value. 210 * @return True if a value is present for this attribute. 211 */ 212 boolean hasAttribute(String key, Class<?> clazz); 213 214 /** 215 * Does this element store a label value for the given key? A label is an 216 * attribute whose value is a string. 217 * 218 * @param key 219 * The name of the label. 220 * @return True if a value is present for this attribute and implements 221 * CharSequence. 222 */ 223 boolean hasLabel(String key); 224 225 /** 226 * Does this element store a number for the given key? A number is an 227 * attribute whose value is an instance of Number. 228 * 229 * @param key 230 * The name of the number. 231 * @return True if a value is present for this attribute and can contain a 232 * double (inherits from Number). 233 */ 234 boolean hasNumber(String key); 235 236 /** 237 * Does this element store a vector value for the given key? A vector is an 238 * attribute whose value is a sequence of numbers. 239 * 240 * @param key 241 * The name of the vector. 242 * @return True if a value is present for this attribute and can contain a 243 * sequence of numbers. 244 */ 245 boolean hasVector(String key); 246 247 /** 248 * Does this element store an array value for the given key? A vector is an 249 * attribute whose value is an array of objects. 250 * 251 * @param key 252 * The name of the array. 253 * @return True if a value is present for this attribute and can contain an 254 * array object. 255 */ 256 boolean hasArray(String key); 257 258 /** 259 * Does this element store a hash value for the given key? A hash is a set 260 * of pairs (key,value) or objects that implement the 261 * {@link org.graphstream.graph.CompoundAttribute} class. 262 * 263 * @param key 264 * The name of the hash. 265 * @return True if a value is present for this attribute and can contain a 266 * hash. 267 */ 268 boolean hasHash(String key); 269 270 /** 271 * Iterator on all attributes keys. 272 * 273 * @return An iterator on the key set of attributes. 274 */ 275 Iterator<String> getAttributeKeyIterator(); 276 277 /** 278 * An iterable view on the set of attribute keys usable within a for-each 279 * loop. 280 * 281 * @return an iterable view on attribute keys. 282 */ 283 Iterable<String> getEachAttributeKey(); 284 285 /** 286 * An unmodifiable view on the set of attribute keys. 287 * 288 * @return an unmodifiable collection containing the attribute keys. 289 */ 290 Collection<String> getAttributeKeySet(); 291 292 /** 293 * Remove all registered attributes. This includes numbers, labels and 294 * vectors. 295 */ 296 void clearAttributes(); 297 298 /** 299 * Add or replace the value of an attribute. Existing attributes are 300 * overwritten silently. All classes inheriting from Number can be 301 * considered as numbers. All classes inheriting from CharSequence can be 302 * considered as labels. You can pass zero, one or more arguments for the 303 * attribute values. If no value is given, a boolean with value "true" is 304 * added. If there is more than one value, an array is stored. If there is 305 * only one value, the value is stored (but not in an array). 306 * 307 * @param attribute 308 * The attribute name. 309 * @param values 310 * The attribute value or set of values. 311 */ 312 void addAttribute(String attribute, Object... values); 313 314 /** 315 * Like {@link #addAttribute(String, Object...)} but for consistency. 316 * 317 * @param attribute 318 * The attribute name. 319 * @param values 320 * The attribute value or array of values. 321 * @see #addAttribute(String, Object...) 322 */ 323 void changeAttribute(String attribute, Object... values); 324 325 /** 326 * Like {@link #addAttribute(String, Object...)} but for consistency. 327 * 328 * @param attribute 329 * The attribute name. 330 * @param values 331 * The attribute value or array of values. 332 * @see #addAttribute(String, Object...) 333 */ 334 void setAttribute(String attribute, Object... values); 335 336 /** 337 * Add or replace each attribute found in attributes. Existing attributes 338 * are overwritten silently. All classes inheriting from Number can be 339 * considered as numbers. All classes inheriting from CharSequence can be 340 * considered as labels. 341 * 342 * @param attributes 343 * A set of (key,value) pairs. 344 */ 345 void addAttributes(Map<String, Object> attributes); 346 347 /** 348 * Remove an attribute. Non-existent attributes errors are ignored silently. 349 * 350 * @param attribute 351 * Name of the attribute to remove. 352 */ 353 void removeAttribute(String attribute); 354 355 /** 356 * Number of attributes stored in this element. 357 * 358 * @return the number of attributes. 359 */ 360 int getAttributeCount(); 361}