001/** 002 * 003 * Copyright (c) 2014, the Railo Company Ltd. All rights reserved. 004 * 005 * This library is free software; you can redistribute it and/or 006 * modify it under the terms of the GNU Lesser General Public 007 * License as published by the Free Software Foundation; either 008 * version 2.1 of the License, or (at your option) any later version. 009 * 010 * This library is distributed in the hope that it will be useful, 011 * but WITHOUT ANY WARRANTY; without even the implied warranty of 012 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 013 * Lesser General Public License for more details. 014 * 015 * You should have received a copy of the GNU Lesser General Public 016 * License along with this library. If not, see <http://www.gnu.org/licenses/>. 017 * 018 **/ 019package lucee.runtime.type; 020 021import java.io.Serializable; 022 023import lucee.runtime.dump.Dumpable; 024import lucee.runtime.exp.PageException; 025import lucee.runtime.op.Castable; 026 027 028/** 029 * interface collection, used for all collection types of lucee (array, struct, query) 030 */ 031public interface Collection extends Dumpable, Iteratorable, Cloneable, Serializable, Castable,ForEachIteratorable { 032 033 034 035 /** 036 * @return the size of the collection 037 */ 038 public int size(); 039 040 /** 041 * @return returns a string array of all keys in the collection 042 * @deprecated use instead <code>keyIterator()</code> 043 */ 044 public Collection.Key[] keys(); 045 046 /** 047 * removes value from collection and return it when it exists, otherwise throws a exception 048 * @param key key of the collection 049 * @return removed Object 050 * @throws PageException 051 */ 052 public Object remove(Collection.Key key) throws PageException; 053 054 /** 055 * removes value from collection and return it when it exists, otherwise returns null 056 * @param key key of the collection 057 * @return removed Object 058 */ 059 public Object removeEL(Collection.Key key); 060 061 /** 062 * clears the collection 063 */ 064 public void clear(); 065 066 /** 067 * return a value from the collection 068 * @param key key of the value to get 069 * @return value on key position 070 * @throws PageException 071 * @deprecated use instead <code>{@link #get(lucee.runtime.type.Collection.Key)}</code> 072 */ 073 public Object get(String key) throws PageException; 074 075 076 /** 077 * return a value from the collection 078 * @param key key of the value to get must be lower case 079 * @return value on key position 080 * @throws PageException 081 */ 082 public Object get(Collection.Key key) throws PageException; 083 084 /** 085 * return a value from the collection, if key doesn't exist, dont throw a exception, reeturns null 086 * @param key key of the value to get 087 * @return value on key position or null 088 * @deprecated use instead <code>{@link #get(lucee.runtime.type.Collection.Key, Object)}</code> 089 */ 090 public Object get(String key, Object defaultValue); 091 092 /** 093 * return a value from the collection, if key doesn't exist, dont throw a exception, reeturns null 094 * @param key key of the value to get 095 * @return value on key position or null 096 */ 097 public Object get(Collection.Key key, Object defaultValue); 098 099 /** 100 * sets a value to the collection 101 * @param key key of the new value 102 * @param value value to set 103 * @return value setted 104 * @throws PageException 105 * @deprecated use instead <code>{@link #set(lucee.runtime.type.Collection.Key, Object)}</code> 106 */ 107 public Object set(String key, Object value) throws PageException; 108 109 /** 110 * sets a value to the collection 111 * @param key key of the new value 112 * @param value value to set 113 * @return value setted 114 * @throws PageException 115 */ 116 public Object set(Collection.Key key, Object value) throws PageException; 117 118 /** 119 * sets a value to the collection, if key doesn't exist, dont throw a exception, returns null 120 * @param key key of the value to get 121 * @param value value to set 122 * @return value on key position or null 123 * @deprecated use instead <code>{@link #setEL(lucee.runtime.type.Collection.Key, Object)}</code> 124 */ 125 public Object setEL(String key, Object value); 126 127 /** 128 * sets a value to the collection, if key doesn't exist, dont throw a exception, returns null 129 * @param key key of the value to get 130 * @param value value to set 131 * @return value on key position or null 132 */ 133 public Object setEL(Collection.Key key, Object value); 134 135 136 137 /** 138 * @return this object cloned 139 */ 140 public Object clone(); 141 142 public Collection duplicate(boolean deepCopy); 143 144 /** 145 * contains this key 146 * @param key 147 * @return returns if collection has a key with given name 148 * @deprecated use instead <code>{@link #containsKey(lucee.runtime.type.Collection.Key)}</code> 149 */ 150 public boolean containsKey(String key); 151 152 /** 153 * contains this key 154 * @param key 155 * @return returns if collection has a key with given name 156 */ 157 public boolean containsKey(Collection.Key key); 158 159 160 161 interface Key extends Serializable { 162 163 /** 164 * return key as String 165 */ 166 public String getString(); 167 168 /** 169 * return key as lower case String 170 */ 171 public String getLowerString(); 172 173 /** 174 * return key as upper case String 175 */ 176 public String getUpperString(); 177 178 179 /** 180 * return char at given position 181 * @param index 182 * @return character at given position 183 */ 184 public char charAt(int index); 185 186 /** 187 * return lower case char a given position 188 * @param index 189 * @return lower case char from given position 190 */ 191 public char lowerCharAt(int index); 192 193 /** 194 * return upper case char a given position 195 * @param index 196 * @return upper case char from given position 197 */ 198 public char upperCharAt(int index); 199 200 /** 201 * compare to object, ignore case of input 202 * @param key 203 * @return is equal to given key? 204 */ 205 public boolean equalsIgnoreCase(Collection.Key key); 206 207 /** 208 * @return return id for this key, this key is unique for the system but ignore case of input 209 */ 210 public int getId(); 211 212 /** 213 * Returns the length of this string. 214 * @return length of the string 215 */ 216 public int length(); 217 218 // Future add; returns a 64 bit based hashcode for the Key 219 // public long hash(); 220 } 221}