/*
 *   @(#) $Id: ConnectFuture.java 331846 2005-11-08 17:12:06Z trustin $
 *
 *   Copyright 2004 The Apache Software Foundation
 *
 *   Licensed under the Apache License, Version 2.0 (the "License");
 *   you may not use this file except in compliance with the License.
 *   You may obtain a copy of the License at
 *
 *       http://www.apache.org/licenses/LICENSE-2.0
 *
 *   Unless required by applicable law or agreed to in writing, software
 *   distributed under the License is distributed on an "AS IS" BASIS,
 *   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 *   See the License for the specific language governing permissions and
 *   limitations under the License.
 *
 */
package org.apache.mina.common;

import java.io.IOException;

import org.apache.mina.util.ExceptionUtil;

/**
 * An {@link IoFuture} for asynchronous connect requests.
 *
 * <h3>Example</h3>
 * <pre>
 * IoConnector connector = ...;
 * ConnectFuture future = connector.connect(...);
 * future.join(); // Wait until the connection attempt is finished.
 * IoSession session = future.getSession();
 * session.write(...);
 * </pre>
 *
 * @author The Apache Directory Project
 * @version $Rev: 331846 $, $Date: 2005-11-08 17:12:06 +0000 (Tue, 08 Nov 2005) $
 */
public class ConnectFuture extends IoFuture
{
    /**
     * Returns {@link IoSession} which is the result of connect operation.
     * 
     * @return <tt>null</tt> if the connect operation is not finished yet
     * @throws IOException if connection attempt failed by an exception
     */
    public IoSession getSession() throws IOException
    {
        Object v = getValue();
        if( v instanceof Throwable )
        {
            ExceptionUtil.throwException( ( Throwable ) v );
            throw new InternalError(); // this cannot be executed
        }
        else
        {
            return ( IoSession ) v;
        }
    }

    /**
     * Returns <tt>true</tt> if the connect operation is finished successfully.
     */
    public boolean isConnected()
    {
        return getValue() instanceof IoSession;
    }
    
    /**
     * This method is invoked by MINA internally.  Please do not call this method
     * directly.
     */
    public void setSession( IoSession session )
    {
        setValue( session );
    }
    
    /**
     * This method is invoked by MINA internally.  Please do not call this method
     * directly.
     */
    public void setException( Throwable exception )
    {
        setValue( exception );
    }
    
    /**
     * Sets a listener to be notified when the connection is either
     * established, or fails.
     * If this futures result is already available, the listener is
     * notified immediately
     * 
     * @param listener  The listener
     */
    public void setConnectListener(ConnectListener listener) 
    {
      setCallback(new CallbackAdapter(listener));
    }
    
    /**
     * Something interested in being notified when the result of
     * a connection attempt becomes available
     */
    public interface ConnectListener 
    {
      
      /**
       * Invoked when a connection is successfully established
       * 
       * @param session  The new session associated with the connection
       */
      public void connectionEstablished(IoSession session);
    
      /**
       * Invoked when a connection attempt fails
       * 
       * @param cause  The cause of the failure
       */
      public void connectionFailed(Throwable cause);
      
    }
    
    /**
     * Adapts a <code>ConnectionListener</code> to a future
     * <code>Callback</code>
     */
    private static class CallbackAdapter implements IoFuture.Callback {

      private ConnectListener listener;
      
      CallbackAdapter(ConnectListener listener) 
      {
        this.listener = listener;  
      }
      
      /**
       * Invoked when our result becomes available.
       * The result is either an exception, or a newly created
       * <code>IoSession</code>. Our underlying 
       * <code>ConnectionListener</code> is notified accordingly
       * 
       * @param result  The result
       */
      public void resultReady(Object result) 
      {
        if (result instanceof Throwable) 
        {
          listener.connectionFailed((Throwable) result);
        } 
        else 
        {
          listener.connectionEstablished((IoSession) result);
        }
      }
      
    }
    
}