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 */
020package org.apache.mina.core.future;
021
022import org.apache.mina.core.session.IoSession;
023
024/**
025 * An {@link IoFuture} for {@link IoSession#read() asynchronous read requests}. 
026 *
027 * <h3>Example</h3>
028 * <pre>
029 * IoSession session = ...;
030 * 
031 * // useReadOperation must be enabled to use read operation.
032 * session.getConfig().setUseReadOperation(true);
033 * 
034 * ReadFuture future = session.read();
035 * 
036 * // Wait until a message is received.
037 * future.awaitUninterruptibly();
038 * 
039 * try {
040 *     Object message = future.getMessage();
041 * } catch (Exception e) {
042 *     ...
043 * }
044 * </pre>
045 *
046 * @author <a href="http://mina.apache.org">Apache MINA Project</a>
047 */
048public interface ReadFuture extends IoFuture {
049
050    /**
051     * Get the read message.
052     * 
053     * @return the received message.  It returns <tt>null</tt> if this
054     * future is not ready or the associated {@link IoSession} has been closed. 
055     */
056    Object getMessage();
057
058    /**
059     * @return <tt>true</tt> if a message was received successfully.
060     */
061    boolean isRead();
062
063    /**
064     * @return <tt>true</tt> if the {@link IoSession} associated with this
065     * future has been closed.
066     */
067    boolean isClosed();
068
069    /**
070     * @return the cause of the read failure if and only if the read
071     * operation has failed due to an {@link Exception}.  Otherwise,
072     * <tt>null</tt> is returned.
073     */
074    Throwable getException();
075
076    /**
077     * Sets the message is written, and notifies all threads waiting for
078     * this future.  This method is invoked by MINA internally.  Please do
079     * not call this method directly.
080     * 
081     * @param message The received message to store in this future
082     */
083    void setRead(Object message);
084
085    /**
086     * Sets the associated {@link IoSession} is closed.  This method is invoked
087     * by MINA internally.  Please do not call this method directly.
088     */
089    void setClosed();
090
091    /**
092     * Sets the cause of the read failure, and notifies all threads waiting
093     * for this future.  This method is invoked by MINA internally.  Please
094     * do not call this method directly.
095     * 
096     * @param cause The exception to store in the Future instance
097     */
098    void setException(Throwable cause);
099
100    /**
101     * {@inheritDoc}
102     */
103    ReadFuture await() throws InterruptedException;
104
105    /**
106     * {@inheritDoc}
107     */
108    ReadFuture awaitUninterruptibly();
109
110    /**
111     * {@inheritDoc}
112     */
113    ReadFuture addListener(IoFutureListener<?> listener);
114
115    /**
116     * {@inheritDoc}
117     */
118    ReadFuture removeListener(IoFutureListener<?> listener);
119}