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;
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.1 2007-08-24 22:17:30 ewestfal Exp $
38 */
39 public interface OJBIterator extends Iterator
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 }