001    /**
002     * Copyright 2007 Mike Kroutikov.
003     *
004     * This program is free software; you can redistribute it and/or modify
005     *   it under the terms of the Lesser GNU General Public License as 
006     *   published by the Free Software Foundation; either version 3 of
007     *   the License, or (at your option) any later version.
008     *
009     *   This program is distributed in the hope that it will be useful,
010     *   but WITHOUT ANY WARRANTY; without even the implied warranty of
011     *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
012     *   Lesser GNU General Public License for more details.
013     *
014     *   You should have received a copy of the Lesser GNU General Public License
015     *   along with this program.  If not, see <http://www.gnu.org/licenses/>.
016     */
017    
018    package org.otfeed;
019    
020    import org.otfeed.event.OTError;
021    
022    /**
023     * Defines contract for the Request handler.
024     *
025     * Instance of {@link IRequest} is returned by 
026     * {@link IConnection#prepareRequest(org.otfeed.protocol.ICommand)}
027     * metod.
028     * <p/>
029     * Use this handle to actually {@link #submit} the asynchronous request, 
030     * to {@link #cancel} it or to {@link #waitForCompletion() block} till request is complete.
031     * <p/>
032     * Implementations must be thread-safe. All implementation supplied by <code>org.otfeed</code>
033     * are thread-safe.
034     */
035    public interface IRequest {
036    
037            /**
038             * Submits the request.
039             * If request is already active, does nothing.
040             */
041            public void submit();
042    
043            /**
044             * Cancels the request.
045             * If request is not active, does nothing.
046             */
047            public void cancel();
048    
049            /**
050             * Returns request completion status.
051             * After request is completed, one may want to check 
052             * {@link #getError() error} property to see whether 
053             * completion was normal or an error has occured.
054             *
055             * @return true if request has completed, false otherwise.
056             */
057            public boolean isCompleted();
058            
059            /**
060             * Returns error. If request is still running, or has
061             * completed normally, returns null.
062             * 
063             * @return error.
064             */
065            public OTError getError();
066    
067            /**
068             * Waits for request to complete.
069             *
070             * @param  millis timeout value in millis.
071             * @return true if request completed or has been successfully
072             *         cancelled, false on timeout.
073             */
074            public boolean waitForCompletion(long millis);
075    
076            /**
077             * Waits for request to complete (indefinetely).
078             */
079            public void waitForCompletion();
080    }