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