001    /*
002     *   Licensed to the Apache Software Foundation (ASF) under one
003     *   or more contributor license agreements.  See the NOTICE file
004     *   distributed with this work for additional information
005     *   regarding copyright ownership.  The ASF licenses this file
006     *   to you under the Apache License, Version 2.0 (the
007     *   "License"); you may not use this file except in compliance
008     *   with the License.  You may obtain a copy of the License at
009     *
010     *     http://www.apache.org/licenses/LICENSE-2.0
011     *
012     *   Unless required by applicable law or agreed to in writing,
013     *   software distributed under the License is distributed on an
014     *   "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
015     *   KIND, either express or implied.  See the License for the
016     *   specific language governing permissions and limitations
017     *   under the License.
018     *
019     */
020    package org.apache.directory.shared.ldap.cursor;
021    
022    
023    /**
024     * A monitor used by Cursors to detect conditions when they should stop 
025     * performing some work during advance operations such as next(), previous(),
026     * first() etc, and release resources.
027     *
028     * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a>
029     * @version $Rev$, $Date$
030     */
031    public interface ClosureMonitor
032    {
033        /**
034         * Sets monitor state to closed, and sets the cause to a 
035         * CursorClosedException without an error message string.
036         */
037        void close();
038    
039        
040        /**
041         * Sets monitor state to closed, and sets the cause to a 
042         * CursorClosedException with a specific error message string.
043         * 
044         * @param cause error message string
045         */
046        void close( String cause );
047        
048        
049        /**
050         * Sets monitor state to closed, and sets the cause to a specific 
051         * Exception.
052         * 
053         * @param cause the exception to associate with the closure
054         */
055        void close( Exception cause );
056        
057        
058        /**
059         * Gets whether the state of this ClosureMonitor is set to closed.
060         *
061         * @return true if state is closed, false if open
062         */
063        boolean isClosed();
064        
065        
066        /**
067         * Checks if state of this ClosureMonitor is set to closed and if so, 
068         * throws the causing Exception.
069         *
070         * @throws Exception the cause of the closure
071         */
072        void checkNotClosed() throws Exception;
073        
074        
075        /**
076         * Gets the cause of the closure.
077         *
078         * @return the causing Exception
079         */
080        Exception getCause();
081    }