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}