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}