KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > apache > ojb > broker > accesslayer > OJBIterator


1 package org.apache.ojb.broker.accesslayer;
2
3 /* Copyright 2002-2005 The Apache Software Foundation
4  *
5  * Licensed under the Apache License, Version 2.0 (the "License");
6  * you may not use this file except in compliance with the License.
7  * You may obtain a copy of the License at
8  *
9  * http://www.apache.org/licenses/LICENSE-2.0
10  *
11  * Unless required by applicable law or agreed to in writing, software
12  * distributed under the License is distributed on an "AS IS" BASIS,
13  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14  * See the License for the specific language governing permissions and
15  * limitations under the License.
16  */
17
18 import java.util.Iterator JavaDoc;
19
20 import org.apache.ojb.broker.PersistenceBrokerException;
21
22 /**
23  * A {@link Iterator} extension internaly used by OJB to handle query results.
24  *
25  * <p>
26  * NOTE: OJB is very strict in handling <tt>OJBIterator</tt> instances. <tt>OJBIterator</tt> is
27  * bound very closely to the used {@link org.apache.ojb.broker.PersistenceBroker} instance.
28  * Thus if you do a
29  * <br/> - {@link org.apache.ojb.broker.PersistenceBroker#close}
30  * <br/> - {@link org.apache.ojb.broker.PersistenceBroker#commitTransaction}
31  * <br/> - {@link org.apache.ojb.broker.PersistenceBroker#abortTransaction}
32  * <br/>
33  * call, the current <tt>OJBIterator</tt> instance resources will be cleaned up automatic
34  * and invalidate current instance.
35  * </p>
36  *
37  * @version $Id: OJBIterator.java,v 1.9.2.2 2005/12/21 22:22:58 tomdz Exp $
38  */
39 public interface OJBIterator extends Iterator JavaDoc
40 {
41     /**
42      * @return the size of the iterator, aka the number of rows in this iterator.
43      */
44     int size() throws PersistenceBrokerException;
45
46     /**
47      * @return the unlimited size of the iterator,
48      * fullSize() may differ from size() for PagingIterator
49      */
50     int fullSize() throws PersistenceBrokerException;
51
52     /**
53      * Moves the cursor to the given row number in the iterator.
54      * If the row number is positive, the cursor moves to the given row number with
55      * respect to the beginning of the iterator. The first row is row 1, the second is row 2, and so on.
56      * @param row the row to move to in this iterator, by absolute number
57      */
58     boolean absolute(int row) throws PersistenceBrokerException;
59
60     /**
61      * Moves the cursor a relative number of rows, either positive or negative. Attempting to move beyond the first/last
62      * row in the iterator positions the cursor before/after the the first/last row. Calling relative(0) is valid,
63      * but does not change the cursor position.
64      * @param row the row to move to in this iterator, by relative number
65      */
66     boolean relative(int row) throws PersistenceBrokerException;
67
68     /**
69      * Release all internally used Database resources of the iterator.
70      * Clients must call this methods explicitely if the iterator is not
71      * exhausted by the client application. If the Iterator is exhauseted
72      * this method will be called implicitely.
73      */
74     public void releaseDbResources();
75     
76     /**
77      * Do not fire any PBLifeCycleEvent when reading next item.
78      */
79     public void disableLifeCycleEvents();
80 }
81
Popular Tags