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 asynchronous connect requests.
026 *
027 * <h3>Example</h3>
028 * <pre>
029 * IoConnector connector = ...;
030 * ConnectFuture future = connector.connect(...);
031 * future.awaitUninterruptibly(); // Wait until the connection attempt is finished.
032 * IoSession session = future.getSession();
033 * session.write(...);
034 * </pre>
035 *
036 * @author <a href="http://mina.apache.org">Apache MINA Project</a>
037 */
038public interface ConnectFuture extends IoFuture {
039    /**
040     * Returns {@link IoSession} which is the result of connect operation.
041     *
042     * @return The {link IoSession} instance that has been associated with the connection,
043     * if the connection was successful, {@code null} otherwise
044     */
045    IoSession getSession();
046
047    /**
048     * Returns the cause of the connection failure.
049     *
050     * @return <tt>null</tt> if the connect operation is not finished yet,
051     *         or if the connection attempt is successful, otherwise returns
052     *         teh cause of the exception
053     */
054    Throwable getException();
055
056    /**
057     * @return {@code true} if the connect operation is finished successfully.
058     */
059    boolean isConnected();
060
061    /**
062     * @return {@code true} if the connect operation has been canceled by
063     * {@link #cancel()} method.
064     */
065    boolean isCanceled();
066
067    /**
068     * Sets the newly connected session and notifies all threads waiting for
069     * this future.  This method is invoked by MINA internally.  Please do not
070     * call this method directly.
071     * 
072     * @param session The created session to store in the ConnectFuture insteance
073     */
074    void setSession(IoSession session);
075
076    /**
077     * Sets the exception caught due to connection failure and notifies all
078     * threads waiting for this future.  This method is invoked by MINA
079     * internally.  Please do not call this method directly.
080     * 
081     * @param exception The exception to store in the ConnectFuture instance
082     */
083    void setException(Throwable exception);
084
085    /**
086     * Cancels the connection attempt and notifies all threads waiting for
087     * this future.
088     * 
089     * @return {@code true} if the future has been cancelled by this call, {@code false}
090     * if the future was already cancelled.
091     */
092    boolean cancel();
093
094    /**
095     * {@inheritDoc}
096     */
097    ConnectFuture await() throws InterruptedException;
098
099    /**
100     * {@inheritDoc}
101     */
102    ConnectFuture awaitUninterruptibly();
103
104    /**
105     * {@inheritDoc}
106     */
107    ConnectFuture addListener(IoFutureListener<?> listener);
108
109    /**
110     * {@inheritDoc}
111     */
112    ConnectFuture removeListener(IoFutureListener<?> listener);
113}