001    package railo.runtime.type;
002    
003    import java.io.Serializable;
004    
005    import railo.runtime.dump.Dumpable;
006    import railo.runtime.exp.PageException;
007    import railo.runtime.op.Castable;
008    
009    
010    /**
011     * interface collection, used for all collection types of railo (array, struct, query)
012     */
013    public interface Collection extends Dumpable, Iteratorable, Cloneable, Serializable, Castable,ForEachIteratorable  {
014        
015        
016        
017            /**
018             * @return the size of the collection
019             */
020            public int size();
021    
022            /**
023             * @return returns a string array of all keys in the collection
024             * @deprecated use instead <code>keyIterator()</code>
025             */
026            public Collection.Key[] keys();
027            
028            /**
029             * removes value from collection and return it when it exists, otherwise throws a exception
030             * @param key key of the collection
031             * @return removed Object
032             * @throws PageException
033         */
034        public Object remove(Collection.Key key) throws PageException;
035    
036            /**
037             * removes value from collection and return it when it exists, otherwise returns null
038             * @param key key of the collection 
039             * @return removed Object
040         */
041        public Object removeEL(Collection.Key key);
042    
043            /**
044             * clears the collection
045             */
046            public void clear();
047    
048            /**
049             * return a value from the collection
050             * @param key key of the value to get
051             * @return value on key position 
052             * @throws PageException
053             * @deprecated use instead <code>{@link #get(railo.runtime.type.Collection.Key)}</code>
054             */
055            public Object get(String key) throws PageException;
056            
057            
058            /**
059             * return a value from the collection
060             * @param key key of the value to get must be lower case
061             * @return value on key position 
062             * @throws PageException
063             */
064            public Object get(Collection.Key key) throws PageException;
065            
066            /**
067            * return a value from the collection, if key doesn't exist, dont throw a exception, reeturns null
068             * @param key key of the value to get
069             * @return value on key position or null
070             * @deprecated use instead <code>{@link #get(railo.runtime.type.Collection.Key, Object)}</code>
071             */
072            public Object get(String key, Object defaultValue);
073                    
074            /**
075             * return a value from the collection, if key doesn't exist, dont throw a exception, reeturns null
076             * @param key key of the value to get
077             * @return value on key position or null
078             */
079            public Object get(Collection.Key key, Object defaultValue);
080            
081            /**
082             * sets a value to the collection
083             * @param key key of the new value
084             * @param value value to set 
085             * @return value setted
086             * @throws PageException
087             * @deprecated use instead <code>{@link #set(railo.runtime.type.Collection.Key, Object)}</code>
088             */
089            public Object set(String key, Object value) throws PageException;
090            
091            /**
092             * sets a value to the collection
093             * @param key key of the new value 
094             * @param value value to set 
095             * @return value setted
096             * @throws PageException
097             */
098            public Object set(Collection.Key key, Object value) throws PageException;
099            
100            /**
101            * sets a value to the collection, if key doesn't exist, dont throw a exception, returns null
102             * @param key key of the value to get
103             * @param value value to set
104             * @return value on key position or null
105             * @deprecated use instead <code>{@link #setEL(railo.runtime.type.Collection.Key, Object)}</code>
106             */
107            public Object setEL(String key, Object value);
108            
109            /**
110            * sets a value to the collection, if key doesn't exist, dont throw a exception, returns null
111             * @param key key of the value to get
112             * @param value value to set
113             * @return value on key position or null
114             */
115            public Object setEL(Collection.Key key, Object value);
116            
117            
118            
119            /**
120             * @return this object cloned
121             */
122            public Object clone();
123            
124            public Collection duplicate(boolean deepCopy);
125            
126        /**
127         * contains this key
128         * @param key
129         * @return returns if collection has a key with given name
130         * @deprecated use instead <code>{@link #containsKey(railo.runtime.type.Collection.Key)}</code>
131             */
132        public boolean containsKey(String key);
133            
134        /**
135         * contains this key
136             * @param key
137         * @return returns if collection has a key with given name
138         */
139        public boolean containsKey(Collection.Key key);
140        
141    
142        
143        interface Key extends Serializable {
144    
145            /**
146             * return key as String
147             */
148            public String getString();
149    
150            /**
151             * return key as lower case String
152             */
153            public String getLowerString();
154            
155            /**
156             * return key as upper case String
157             */
158            public String getUpperString();
159            
160            
161            /**
162             * return char at given position
163             * @param index
164             * @return character at given position
165             */
166            public char charAt(int index);
167    
168            /**
169             * return lower case char a given position
170             * @param index
171             * @return lower case char from given position
172             */
173            public char lowerCharAt(int index);
174    
175            /**
176             * return upper case char a given position
177             * @param index
178             * @return upper case char from given position
179             */
180            public char upperCharAt(int index);
181            
182            /**
183             * compare to object, ignore case of input
184             * @param key
185             * @return is equal to given key?
186             */
187            public boolean equalsIgnoreCase(Collection.Key key);
188            
189            /**
190             * @return return id for this key, this key is unique for the system but ignore case of input
191             */
192            public int getId();
193            
194            /**
195             * Returns the length of this string.
196             * @return length of the string
197             */
198            public int length();
199    
200            
201        }
202    }