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.util.Map;
022
023import lucee.runtime.db.SQL;
024import lucee.runtime.exp.PageException;
025
026/**
027 * inteface for resultset (query) object
028 */
029public interface Query extends Collection, Iterator,com.allaire.cfx.Query {
030
031        /**
032         * Constant <code>ORDER_ASC</code>, used for method sort
033         */
034        public static final int ORDER_ASC=1;
035        
036        /**
037         * Constant <code>ORDER_DESC</code>, used for method sort
038         */
039        public static final int ORDER_DESC=2;
040
041        
042        /**
043         * @return return how many lines are affected by a update/insert
044         */
045        public int getUpdateCount();
046        
047        /**
048         * return a value of the resultset by specified column and row
049         * @param key column to get 
050         * @param row row to get from (1-recordcount)
051         * @return value at the called poition
052         * @throws PageException if invalid position definition
053         * @deprecated use instead <code>{@link #getAt(lucee.runtime.type.Collection.Key, int)}</code>
054        */
055        public Object getAt(String key,int row) throws PageException;
056        
057        /**
058         * return a value of the resultset by specified column and row
059         * @param key column to get 
060         * @param row row to get from (1-recordcount)
061         * @return value at the called poition
062         * @throws PageException if invalid position definition
063         */
064        public Object getAt(Collection.Key key,int row) throws PageException;
065        
066        /**
067         * return a value of the resultset by specified column and row, otherwise to getAt this method throw no exception if value dont exist (return null)
068         * @param key column to get 
069         * @param row row to get from (1-recordcount)
070         * @return value at the called poition
071         * @deprecated use instead <code>{@link #getAt(lucee.runtime.type.Collection.Key, int, Object)}</code>
072        */
073        public Object getAt(String key,int row, Object defaultValue);
074        
075        /**
076         * return a value of the resultset by specified column and row, otherwise to getAt this method throw no exception if value dont exist (return null)
077         * @param key column to get 
078         * @param row row to get from (1-recordcount)
079         * @return value at the called poition
080         */
081        public Object getAt(Collection.Key key,int row, Object defaultValue);
082
083    /**
084     * set a value at the defined position
085     * @param key column to set
086     * @param row row to set
087     * @param value value to fill
088     * @return filled value
089     * @throws PageException 
090     * @deprecated use instead <code>{@link #setAtEL(lucee.runtime.type.Collection.Key, int, Object)}</code>
091        */
092    public Object setAt(String key,int row, Object value) throws PageException;
093
094    /**
095     * set a value at the defined position
096     * @param key column to set
097     * @param row row to set
098     * @param value value to fill
099     * @return filled value
100     * @throws PageException 
101     */
102    public Object setAt(Collection.Key key,int row, Object value) throws PageException;
103
104    /**
105     * set a value at the defined position
106     * @param key column to set
107     * @param row row to set
108     * @param value value to fill
109     * @return filled value
110     * @deprecated use instead <code>{@link #setAtEL(lucee.runtime.type.Collection.Key, int, Object)}</code>
111        */
112    public Object setAtEL(String key,int row, Object value);
113
114    /**
115     * set a value at the defined position
116     * @param key column to set
117     * @param row row to set
118     * @param value value to fill
119     * @return filled value
120     */
121    public Object setAtEL(Collection.Key key,int row, Object value);
122    
123        /**
124         * adds a new row to the resultset
125         * @param count count of rows to add
126         * @return return if row is addded or nod (always true)
127         */
128        public boolean addRow(int count);
129    
130    /**
131     * remove row from query
132     * @param row
133     * @return return new rowcount
134     * @throws PageException 
135     */
136    public int removeRow(int row) throws PageException;
137    
138    /**
139     * remove row from query
140     * @param row
141     * @return return new rowcount
142     */
143    public int removeRowEL(int row);
144    
145        /**
146         * adds a new column to the resultset
147         * @param columnName name of the new column
148         * @param content content of the new column inside a array (must have same size like query has records)
149         * @return if column is added return true otherwise false (always true, throw error when false)
150         * @throws PageException
151         * @deprecated use instead <code>{@link #addColumn(lucee.runtime.type.Collection.Key, Array)}</code>
152        */
153        public boolean addColumn(String columnName, Array content) throws PageException;
154    
155        /**
156         * adds a new column to the resultset
157         * @param columnName name of the new column
158         * @param content content of the new column inside a array (must have same size like query has records)
159         * @return if column is added return true otherwise false (always true, throw error when false)
160         * @throws PageException
161         */
162        public boolean addColumn(Collection.Key columnName, Array content) throws PageException;
163        
164    /**
165     * adds a new column to the resultset
166         * @param columnName name of the new column
167         * @param content content of the new column inside a array (must have same size like query has records)
168     * @param type data type from (java.sql.Types)
169         * @return if column is added return true otherwise false (always true, throw error when false)
170         * @throws PageException
171         * @deprecated use instead <code>{@link #addColumn(lucee.runtime.type.Collection.Key, Array, int)}</code>
172        */
173    public boolean addColumn(String columnName, Array content, int type) throws PageException;
174        
175    /**
176     * adds a new column to the resultset
177         * @param columnName name of the new column
178         * @param content content of the new column inside a array (must have same size like query has records)
179     * @param type data type from (java.sql.Types)
180         * @return if column is added return true otherwise false (always true, throw error when false)
181         * @throws PageException
182         */
183    public boolean addColumn(Collection.Key columnName, Array content, int type) throws PageException;
184        
185        /**
186         * @return Coloned Object
187         */
188        public Object clone();
189        
190
191        /**
192         * @return return all types 
193         */
194        public int[] getTypes();
195        
196        /**
197         * @return returns all types as Map (key==column)
198         */
199        public Map getTypesAsMap();
200
201    /**
202     * return the query column matching to key
203     * @param key key to get
204     * @return QieryColumn object
205     * @throws PageException
206     * @deprecated use instead <code>{@link #getColumn(lucee.runtime.type.Collection.Key)}</code>
207        */
208    public QueryColumn getColumn(String key) throws PageException;
209
210    /**
211     * return the query column matching to key
212     * @param key key to get
213     * @return QieryColumn object
214     * @throws PageException
215     */
216    public QueryColumn getColumn(Collection.Key key) throws PageException;
217
218        /**
219         * return the query column matching to key, if key not exist return null
220         * @param key key to get
221         * @return QieryColumn object
222         * @deprecated use instead <code>{@link #getColumn(lucee.runtime.type.Collection.Key, QueryColumn)}</code>
223        */
224        public QueryColumn getColumn(String key,QueryColumn column);
225
226        /**
227         * return the query column matching to key, if key not exist return null
228         * @param key key to get
229         * @return QieryColumn object
230         */
231        public QueryColumn getColumn(Collection.Key key,QueryColumn column);
232
233    /**
234     * remove column matching to key
235     * @param key key to remove
236     * @return QueryColumn object removed
237     * @throws PageException
238     * @deprecated use instead <code>{@link #removeColumn(lucee.runtime.type.Collection.Key)}</code>
239        */
240    public QueryColumn removeColumn(String key) throws PageException;
241
242    /**
243     * remove column matching to key
244     * @param key key to remove
245     * @return QueryColumn object removed
246     * @throws PageException
247     */
248    public QueryColumn removeColumn(Collection.Key key) throws PageException;
249
250
251    /**
252     * remove column matching to key
253     * @param key key to remove
254     * @return QueryColumn object removed or null if column not exist
255     * @deprecated use instead <code>{@link #removeColumnEL(lucee.runtime.type.Collection.Key)}</code>
256        */
257    public QueryColumn removeColumnEL(String key);
258
259
260    /**
261     * remove column matching to key
262     * @param key key to remove
263     * @return QueryColumn object removed or null if column not exist
264     */
265    public QueryColumn removeColumnEL(Collection.Key key);
266
267        /**
268         * sets the execution Time of the query
269         * @param l
270         */
271        public void setExecutionTime(long l);
272        
273        /**
274         * sorts a query by a column, direction is asc
275         * @param column colun to sort
276         * @throws PageException
277         * @deprecated use instead <code>{@link #sort(lucee.runtime.type.Collection.Key)}</code>
278        */
279        public void sort(String column) throws PageException;
280        
281        /**
282         * sorts a query by a column, direction is asc
283         * @param column colun to sort
284         * @throws PageException
285         */
286        public void sort(Collection.Key column) throws PageException;
287
288        /**
289         * sorts a query by a column 
290         * @param strColumn column to sort
291         * @param order sort type (Query.ORDER_ASC or Query.ORDER_DESC)
292         * @throws PageException
293         * @deprecated use instead <code>{@link #sort(lucee.runtime.type.Collection.Key, int)}</code>
294        */
295        public void sort(String strColumn, int order) throws PageException;
296
297        /**
298         * sorts a query by a column 
299         * @param strColumn column to sort
300         * @param order sort type (Query.ORDER_ASC or Query.ORDER_DESC)
301         * @throws PageException
302         */
303        public void sort(Collection.Key strColumn, int order) throws PageException;
304
305    /**
306     * sets if query is form cache or not
307     * @param isCached is cached or not
308     */
309    public void setCached(boolean isCached);
310    
311    /**
312     * is query from cache or not
313     * @return is cached or not
314     */
315    public boolean isCached();
316
317    /**
318     * @return returns struct with meta data to the query
319     */
320    //public Struct getMetaData();
321    
322    /**
323     * @return returns array with meta data to the query (only column names and type)
324     */
325    public Array getMetaDataSimple();
326    
327        
328        
329        public void rename(Collection.Key columnName,Collection.Key newColumnName) throws PageException;
330        
331        public Collection.Key[] getColumnNames();
332        
333        public String[] getColumnNamesAsString();
334        
335        public Query getGeneratedKeys();
336        
337        public SQL getSql();
338
339        public String getTemplate();
340
341        /**
342         * @return return the query execution time in nanoseconds
343         */
344        public long getExecutionTime();
345        
346        /**
347         * @return returns the execution time
348         * @deprecated use <code>getExecutionTime()</code> instead
349         */
350        public int executionTime();
351
352        
353}