001    package org.apache.ojb.broker.accesslayer;
002    
003    /* Copyright 2002-2005 The Apache Software Foundation
004     *
005     * Licensed under the Apache License, Version 2.0 (the "License");
006     * you may not use this file except in compliance with the License.
007     * You may obtain a copy of the License at
008     *
009     *     http://www.apache.org/licenses/LICENSE-2.0
010     *
011     * Unless required by applicable law or agreed to in writing, software
012     * distributed under the License is distributed on an "AS IS" BASIS,
013     * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014     * See the License for the specific language governing permissions and
015     * limitations under the License.
016     */
017    
018    import java.util.Iterator;
019    
020    import org.apache.ojb.broker.PersistenceBrokerException;
021    
022    /**
023     * A {@link Iterator} extension internaly used by OJB to handle query results.
024     *
025     * <p>
026     * NOTE: OJB is very strict in handling <tt>OJBIterator</tt> instances. <tt>OJBIterator</tt> is
027     * bound very closely to the used {@link org.apache.ojb.broker.PersistenceBroker} instance.
028     * Thus if you do a
029     * <br/> - {@link org.apache.ojb.broker.PersistenceBroker#close}
030     * <br/> - {@link org.apache.ojb.broker.PersistenceBroker#commitTransaction}
031     * <br/> - {@link org.apache.ojb.broker.PersistenceBroker#abortTransaction}
032     * <br/>
033     * call, the current <tt>OJBIterator</tt> instance resources will be cleaned up automatic
034     * and invalidate current instance.
035     * </p>
036     *
037     * @version $Id: OJBIterator.java,v 1.1 2007-08-24 22:17:30 ewestfal Exp $
038     */
039    public interface OJBIterator extends Iterator
040    {
041        /**
042         * @return the size of the iterator, aka the number of rows in this iterator.
043         */
044        int size() throws PersistenceBrokerException;
045    
046        /**
047         * @return the unlimited size of the iterator,
048         * fullSize() may differ from size() for PagingIterator
049         */
050        int fullSize() throws PersistenceBrokerException;
051    
052        /**
053         * Moves the cursor to the given row number in the iterator.
054         * If the row number is positive, the cursor moves to the given row number with
055         * respect to the beginning of the iterator. The first row is row 1, the second is row 2, and so on.
056         * @param row the row to move to in this iterator, by absolute number
057         */
058        boolean absolute(int row) throws PersistenceBrokerException;
059    
060        /**
061         * Moves the cursor a relative number of rows, either positive or negative. Attempting to move beyond the first/last
062         * row in the iterator positions the cursor before/after the the first/last row. Calling relative(0) is valid,
063         * but does not change the cursor position.
064         * @param row the row to move to in this iterator, by relative number
065         */
066        boolean relative(int row) throws PersistenceBrokerException;
067    
068        /**
069         * Release all internally used Database resources of the iterator.
070         * Clients must call this methods explicitely if the iterator is not
071         * exhausted by the client application. If the Iterator is exhauseted
072         * this method will be called implicitely.
073         */
074        public void releaseDbResources();
075        
076        /**
077         * Do not fire any PBLifeCycleEvent when reading next item. 
078         */
079        public void disableLifeCycleEvents();
080    }