KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > objectstyle > cayenne > access > ResultIterator


1 /* ====================================================================
2  *
3  * The ObjectStyle Group Software License, version 1.1
4  * ObjectStyle Group - http://objectstyle.org/
5  *
6  * Copyright (c) 2002-2005, Andrei (Andrus) Adamchik and individual authors
7  * of the software. All rights reserved.
8  *
9  * Redistribution and use in source and binary forms, with or without
10  * modification, are permitted provided that the following conditions
11  * are met:
12  *
13  * 1. Redistributions of source code must retain the above copyright
14  * notice, this list of conditions and the following disclaimer.
15  *
16  * 2. Redistributions in binary form must reproduce the above copyright
17  * notice, this list of conditions and the following disclaimer in
18  * the documentation and/or other materials provided with the
19  * distribution.
20  *
21  * 3. The end-user documentation included with the redistribution, if any,
22  * must include the following acknowlegement:
23  * "This product includes software developed by independent contributors
24  * and hosted on ObjectStyle Group web site (http://objectstyle.org/)."
25  * Alternately, this acknowlegement may appear in the software itself,
26  * if and wherever such third-party acknowlegements normally appear.
27  *
28  * 4. The names "ObjectStyle Group" and "Cayenne" must not be used to endorse
29  * or promote products derived from this software without prior written
30  * permission. For written permission, email
31  * "andrus at objectstyle dot org".
32  *
33  * 5. Products derived from this software may not be called "ObjectStyle"
34  * or "Cayenne", nor may "ObjectStyle" or "Cayenne" appear in their
35  * names without prior written permission.
36  *
37  * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
38  * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
39  * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
40  * DISCLAIMED. IN NO EVENT SHALL THE OBJECTSTYLE GROUP OR
41  * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
42  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
43  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
44  * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
45  * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
46  * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
47  * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
48  * SUCH DAMAGE.
49  * ====================================================================
50  *
51  * This software consists of voluntary contributions made by many
52  * individuals and hosted on ObjectStyle Group web site. For more
53  * information on the ObjectStyle Group, please see
54  * <http://objectstyle.org/>.
55  */
56 package org.objectstyle.cayenne.access;
57
58 import java.util.List JavaDoc;
59 import java.util.Map JavaDoc;
60
61 import org.objectstyle.cayenne.CayenneException;
62 import org.objectstyle.cayenne.map.DbEntity;
63
64 /**
65  * Defines API of an iterator over the records returned as a result
66  * of SelectQuery execution. Usually a ResultIterator is supported by
67  * an open java.sql.ResultSet, therefore most of the methods would throw
68  * checked exceptions. ResultIterators must be explicitly closed when the
69  * user is done working with them.
70  *
71  * <p><i>For more information see <a HREF="../../../../../../userguide/index.html"
72  * target="_top">Cayenne User Guide.</a></i></p>
73  *
74  * @author Andrei Adamchik
75  */
76 public interface ResultIterator {
77     
78     /**
79      * Returns all unread data rows from ResultSet and closes this iterator
80      * if asked to do so.
81      */
82     public List JavaDoc dataRows(boolean close) throws CayenneException;
83            
84     /**
85      * Returns true if there is at least one more record
86      * that can be read from the iterator.
87      */
88     public boolean hasNextRow() throws CayenneException;
89     
90     /**
91      * Returns the next result row as a Map.
92      */
93     public Map JavaDoc nextDataRow() throws CayenneException;
94     
95     /**
96      * Returns a map of ObjectId values from the next result row.
97      * Primary key columns are determined from the provided DbEntity.
98      *
99      * @since 1.1
100      */
101     public Map JavaDoc nextObjectId(DbEntity entity) throws CayenneException;
102     
103     /**
104      * Skips current data row instead of reading it.
105      */
106     public void skipDataRow() throws CayenneException;
107     
108     /**
109      * Closes ResultIterator and associated ResultSet. This method must be
110      * called explicitly when the user is finished processing the records.
111      * Otherwise unused database resources will not be released properly.
112      */
113     public void close() throws CayenneException;
114     
115     /**
116      * Returns the number of columns in the result row.
117      *
118      * @since 1.0.6
119      */
120     public int getDataRowWidth();
121 }
122
123
Popular Tags