KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > apache > cayenne > QueryResponse


1 /*****************************************************************
2  * Licensed to the Apache Software Foundation (ASF) under one
3  * or more contributor license agreements. See the NOTICE file
4  * distributed with this work for additional information
5  * regarding copyright ownership. The ASF licenses this file
6  * to you under the Apache License, Version 2.0 (the
7  * "License"); you may not use this file except in compliance
8  * with the License. You may obtain a copy of the License at
9  *
10  * http://www.apache.org/licenses/LICENSE-2.0
11  *
12  * Unless required by applicable law or agreed to in writing,
13  * software distributed under the License is distributed on an
14  * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15  * KIND, either express or implied. See the License for the
16  * specific language governing permissions and limitations
17  * under the License.
18  ****************************************************************/
19
20 package org.apache.cayenne;
21
22 import java.util.List JavaDoc;
23
24 /**
25  * Represents a result of query execution. It potentially contain a mix of update counts
26  * and lists of selected values. Provides API somewhat similar to java.util.Iterator or
27  * java.sql.ResultSet for scanning through the individual results.
28  * <p>
29  * An example of iterating through a response:
30  * </p>
31  *
32  * <pre>
33  * QueryResponse response = context.performGenericQuery(query);
34  * for (response.reset(); response.next();) {
35  * if (response.isList()) {
36  * List list = response.currentList();
37  * // ...
38  * }
39  * else {
40  * int[] updateCounts = reponse.currentUpdateCount();
41  * // ...
42  * }
43  * }
44  * </pre>
45  *
46  * <p>
47  * In case the structure of the result is known, and only a single list or an update count
48  * is expected, there is a simpler API to access them:
49  * </p>
50  *
51  * <pre>
52  * QueryResponse response = context.performGenericQuery(query);
53  * List list = response.firstList();
54  * int[] count = response.firstUpdateCount();
55  * </pre>
56  *
57  * @since 1.2
58  * @author Andrus Adamchik
59  */
60 public interface QueryResponse {
61
62     /**
63      * Returns a number of results in the response.
64      */
65     int size();
66
67     /**
68      * Returns whether current iteration result is a list or an update count.
69      */
70     boolean isList();
71
72     /**
73      * Returns a List under the current iterator position. Use {@link #isList()} to check
74      * the result type before calling this method.
75      */
76     List JavaDoc currentList();
77
78     /**
79      * Returns an update count under the current iterator position. Returned value is an
80      * int[] to accomodate batch queries. For a regular update result, the value will be
81      * an int[1]. Use {@link #isList()} to check the result type before calling this
82      * method.
83      */
84     int[] currentUpdateCount();
85
86     /**
87      * Rewinds response iterator to the next result, returning true if it is available.
88      */
89     boolean next();
90
91     /**
92      * Restarts response iterator.
93      */
94     void reset();
95
96     /**
97      * A utility method for quickly retrieving the first list in the response. Returns
98      * null if the query has no lists. Note that this method resets current iterator to an
99      * undefined state.
100      */
101     List JavaDoc firstList();
102
103     /**
104      * A utility method for quickly retrieving the first update count from the response.
105      * Note that this method resets current iterator to an undefined state.
106      */
107     int[] firstUpdateCount();
108 }
109
Popular Tags