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.core.future;
21
22 import java.util.concurrent.TimeUnit;
23
24 import org.apache.mina.core.session.IoSession;
25
26 /**
27 * Represents the completion of an asynchronous I/O operation on an
28 * {@link IoSession}.
29 * Can be listened for completion using a {@link IoFutureListener}.
30 *
31 * @author <a href="http://mina.apache.org">Apache MINA Project</a>
32 */
33 public interface IoFuture {
34 /**
35 * @return the {@link IoSession} which is associated with this future.
36 */
37 IoSession getSession();
38
39 /**
40 * Wait for the asynchronous operation to complete.
41 * The attached listeners will be notified when the operation is
42 * completed.
43 *
44 * @return The instance of IoFuture that we are waiting for
45 * @exception InterruptedException If the thread is interrupted while waiting
46 */
47 IoFuture await() throws InterruptedException;
48
49 /**
50 * Wait for the asynchronous operation to complete with the specified timeout.
51 *
52 * @param timeout The maximum delay to wait before getting out
53 * @param unit the type of unit for the delay (seconds, minutes...)
54 * @return <tt>true</tt> if the operation is completed.
55 * @exception InterruptedException If the thread is interrupted while waiting
56 */
57 boolean await(long timeout, TimeUnit unit) throws InterruptedException;
58
59 /**
60 * Wait for the asynchronous operation to complete with the specified timeout.
61 *
62 * @param timeoutMillis The maximum milliseconds to wait before getting out
63 * @return <tt>true</tt> if the operation is completed.
64 * @exception InterruptedException If the thread is interrupted while waiting
65 */
66 boolean await(long timeoutMillis) throws InterruptedException;
67
68 /**
69 * Wait for the asynchronous operation to complete uninterruptibly.
70 * The attached listeners will be notified when the operation is
71 * completed.
72 *
73 * @return the current IoFuture
74 */
75 IoFuture awaitUninterruptibly();
76
77 /**
78 * Wait for the asynchronous operation to complete with the specified timeout
79 * uninterruptibly.
80 *
81 * @param timeout The maximum delay to wait before getting out
82 * @param unit the type of unit for the delay (seconds, minutes...)
83 * @return <tt>true</tt> if the operation is completed.
84 */
85 boolean awaitUninterruptibly(long timeout, TimeUnit unit);
86
87 /**
88 * Wait for the asynchronous operation to complete with the specified timeout
89 * uninterruptibly.
90 *
91 * @param timeoutMillis The maximum milliseconds to wait before getting out
92 * @return <tt>true</tt> if the operation is finished.
93 */
94 boolean awaitUninterruptibly(long timeoutMillis);
95
96 /**
97 * @deprecated Replaced with {@link #awaitUninterruptibly()}.
98 */
99 @Deprecated
100 void join();
101
102 /**
103 * @deprecated Replaced with {@link #awaitUninterruptibly(long)}.
104 *
105 * @param timeoutMillis The time to wait for the join before bailing out
106 * @return <tt>true</tt> if the join was successful
107 */
108 @Deprecated
109 boolean join(long timeoutMillis);
110
111 /**
112 * @return <tt>true</tt> if the operation is completed.
113 */
114 boolean isDone();
115
116 /**
117 * Adds an event <tt>listener</tt> which is notified when
118 * this future is completed. If the listener is added
119 * after the completion, the listener is directly notified.
120 *
121 * @param listener The listener to add
122 * @return the current IoFuture
123 */
124 IoFuture addListener(IoFutureListener<?> listener);
125
126 /**
127 * Removes an existing event <tt>listener</tt> so it won't be notified when
128 * the future is completed.
129 *
130 * @param listener The listener to remove
131 * @return the current IoFuture
132 */
133 IoFuture removeListener(IoFutureListener<?> listener);
134 }