01: package org.apache.ojb.broker.accesslayer;
02:
03: /* Copyright 2002-2005 The Apache Software Foundation
04: *
05: * Licensed under the Apache License, Version 2.0 (the "License");
06: * you may not use this file except in compliance with the License.
07: * You may obtain a copy of the License at
08: *
09: * 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.9.2.2 2005/12/21 22:22:58 tomdz Exp $
38: */
39: public interface OJBIterator extends Iterator {
40: /**
41: * @return the size of the iterator, aka the number of rows in this iterator.
42: */
43: int size() throws PersistenceBrokerException;
44:
45: /**
46: * @return the unlimited size of the iterator,
47: * fullSize() may differ from size() for PagingIterator
48: */
49: int fullSize() throws PersistenceBrokerException;
50:
51: /**
52: * Moves the cursor to the given row number in the iterator.
53: * If the row number is positive, the cursor moves to the given row number with
54: * respect to the beginning of the iterator. The first row is row 1, the second is row 2, and so on.
55: * @param row the row to move to in this iterator, by absolute number
56: */
57: boolean absolute(int row) throws PersistenceBrokerException;
58:
59: /**
60: * Moves the cursor a relative number of rows, either positive or negative. Attempting to move beyond the first/last
61: * row in the iterator positions the cursor before/after the the first/last row. Calling relative(0) is valid,
62: * but does not change the cursor position.
63: * @param row the row to move to in this iterator, by relative number
64: */
65: boolean relative(int row) throws PersistenceBrokerException;
66:
67: /**
68: * Release all internally used Database resources of the iterator.
69: * Clients must call this methods explicitely if the iterator is not
70: * exhausted by the client application. If the Iterator is exhauseted
71: * this method will be called implicitely.
72: */
73: public void releaseDbResources();
74:
75: /**
76: * Do not fire any PBLifeCycleEvent when reading next item.
77: */
78: public void disableLifeCycleEvents();
79: }
|