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
022/**
023 * An {@link IoFuture} for asynchronous write requests.
024 *
025 * <h3>Example</h3>
026 * <pre>
027 * IoSession session = ...;
028 * WriteFuture future = session.write(...);
029 * 
030 * // Wait until the message is completely written out to the O/S buffer.
031 * future.awaitUninterruptibly();
032 * 
033 * if( future.isWritten() )
034 * {
035 *     // The message has been written successfully.
036 * }
037 * else
038 * {
039 *     // The message couldn't be written out completely for some reason.
040 *     // (e.g. Connection is closed)
041 * }
042 * </pre>
043 *
044 * @author <a href="http://mina.apache.org">Apache MINA Project</a>
045 */
046public interface WriteFuture extends IoFuture {
047    /**
048     * @return <tt>true</tt> if the write operation is finished successfully.
049     */
050    boolean isWritten();
051
052    /**
053     * @return the cause of the write failure if and only if the write
054     * operation has failed due to an {@link Exception}.  Otherwise,
055     * <tt>null</tt> is returned.
056     */
057    Throwable getException();
058
059    /**
060     * Sets the message is written, and notifies all threads waiting for
061     * this future.  This method is invoked by MINA internally.  Please do
062     * not call this method directly.
063     */
064    void setWritten();
065
066    /**
067     * Sets the cause of the write failure, and notifies all threads waiting
068     * for this future.  This method is invoked by MINA internally.  Please
069     * do not call this method directly.
070     * 
071     * @param cause The exception to store in the Future instance
072     */
073    void setException(Throwable cause);
074
075    /**
076     * Wait for the asynchronous operation to complete.
077     * The attached listeners will be notified when the operation is 
078     * completed.
079     * 
080     * @return the created {@link WriteFuture}
081     * @throws InterruptedException If the wait is interrupted
082     */
083    WriteFuture await() throws InterruptedException;
084
085    /**
086     * {@inheritDoc}
087     */
088    WriteFuture awaitUninterruptibly();
089
090    /**
091     * {@inheritDoc}
092     */
093    WriteFuture addListener(IoFutureListener<?> listener);
094
095    /**
096     * {@inheritDoc}
097     */
098    WriteFuture removeListener(IoFutureListener<?> listener);
099}