View Javadoc

1   /*
2    *  Licensed to the Apache Software Foundation (ASF) under one
3    *  or more contributor license agreements.  See the NOTICE file
4    *  distributed with this work for additional information
5    *  regarding copyright ownership.  The ASF licenses this file
6    *  to you under the Apache License, Version 2.0 (the
7    *  "License"); you may not use this file except in compliance
8    *  with the License.  You may obtain a copy of the License at
9    *
10   *    http://www.apache.org/licenses/LICENSE-2.0
11   *
12   *  Unless required by applicable law or agreed to in writing,
13   *  software distributed under the License is distributed on an
14   *  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15   *  KIND, either express or implied.  See the License for the
16   *  specific language governing permissions and limitations
17   *  under the License.
18   *
19   */
20  package org.apache.mina.common;
21  
22  /**
23   * An {@link IoFuture} for asynchronous connect requests.
24   *
25   * <h3>Example</h3>
26   * <pre>
27   * IoConnector connector = ...;
28   * ConnectFuture future = connector.connect(...);
29   * future.join(); // Wait until the connection attempt is finished.
30   * IoSession session = future.getSession();
31   * session.write(...);
32   * </pre>
33   *
34   * @author The Apache MINA Project (dev@mina.apache.org)
35   * @version $Rev: 596168 $, $Date: 2007-11-18 17:20:24 -0700 (Sun, 18 Nov 2007) $
36   */
37  public interface ConnectFuture extends IoFuture {
38      /**
39       * Returns {@link IoSession} which is the result of connect operation.
40       *
41       * @return <tt>null</tt> if the connect operation is not finished yet
42       * @throws RuntimeException if connection attempt failed by an exception
43       */
44      IoSession getSession();
45  
46      /**
47       * Returns the cause of the connection failure.
48       *
49       * @return <tt>null</tt> if the connect operation is not finished yet,
50       *         or if the connection attempt is successful.
51       */
52      Throwable getException();
53  
54      /**
55       * Returns <tt>true</tt> if the connect operation is finished successfully.
56       */
57      boolean isConnected();
58  
59      /**
60       * Returns {@code true} if the connect operation has been canceled by
61       * {@link #cancel()} method.
62       */
63      boolean isCanceled();
64  
65      /**
66       * Sets the newly connected session and notifies all threads waiting for
67       * this future.  This method is invoked by MINA internally.  Please do not
68       * call this method directly.
69       */
70      void setSession(IoSession session);
71  
72      /**
73       * Sets the exception caught due to connection failure and notifies all
74       * threads waiting for this future.  This method is invoked by MINA
75       * internally.  Please do not call this method directly.
76       */
77      void setException(Throwable exception);
78  
79      /**
80       * Cancels the connection attempt and notifies all threads waiting for
81       * this future.
82       */
83      void cancel();
84  
85      ConnectFuture await() throws InterruptedException;
86  
87      ConnectFuture awaitUninterruptibly();
88  
89      ConnectFuture addListener(IoFutureListener<?> listener);
90  
91      ConnectFuture removeListener(IoFutureListener<?> listener);
92  }