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.service;
21
22 import java.io.IOException;
23 import java.net.SocketAddress;
24 import java.util.List;
25 import java.util.Set;
26
27 import org.apache.mina.core.session.IoSession;
28
29 /**
30 * Accepts incoming connection, communicates with clients, and fires events to
31 * {@link IoHandler}s.
32 * <p>
33 * Please refer to
34 * <a href="../../../../../xref-examples/org/apache/mina/examples/echoserver/Main.html">EchoServer</a>
35 * example.
36 * <p>
37 * You should bind to the desired socket address to accept incoming
38 * connections, and then events for incoming connections will be sent to
39 * the specified default {@link IoHandler}.
40 * <p>
41 * Threads accept incoming connections start automatically when
42 * {@link #bind()} is invoked, and stop when {@link #unbind()} is invoked.
43 *
44 * @author The Apache MINA Project (dev@mina.apache.org)
45 * @version $Rev: 671827 $, $Date: 2008-06-26 10:49:48 +0200 (jeu, 26 jun 2008) $
46 */
47 public interface IoAcceptor extends IoService {
48 /**
49 * Returns the local address which is bound currently. If more than one
50 * address are bound, only one of them will be returned, but it's not
51 * necessarily the firstly bound address.
52 */
53 SocketAddress getLocalAddress();
54
55 /**
56 * Returns a {@link Set} of the local addresses which are bound currently.
57 */
58 Set<SocketAddress> getLocalAddresses();
59
60 /**
61 * Returns the default local address to bind when no argument is specified
62 * in {@link #bind()} method. Please note that the default will not be
63 * used if any local address is specified. If more than one address are
64 * set, only one of them will be returned, but it's not necessarily the
65 * firstly specified address in {@link #setDefaultLocalAddresses(List)}.
66 *
67 */
68 SocketAddress getDefaultLocalAddress();
69
70 /**
71 * Returns a {@link List} of the default local addresses to bind when no
72 * argument is specified in {@link #bind()} method. Please note that the
73 * default will not be used if any local address is specified.
74 */
75 List<SocketAddress> getDefaultLocalAddresses();
76
77 /**
78 * Sets the default local address to bind when no argument is specified in
79 * {@link #bind()} method. Please note that the default will not be used
80 * if any local address is specified.
81 */
82 void setDefaultLocalAddress(SocketAddress localAddress);
83
84 /**
85 * Sets the default local addresses to bind when no argument is specified
86 * in {@link #bind()} method. Please note that the default will not be
87 * used if any local address is specified.
88 */
89 void setDefaultLocalAddresses(SocketAddress firstLocalAddress, SocketAddress... otherLocalAddresses);
90
91 /**
92 * Sets the default local addresses to bind when no argument is specified
93 * in {@link #bind()} method. Please note that the default will not be
94 * used if any local address is specified.
95 */
96 void setDefaultLocalAddresses(Iterable<? extends SocketAddress> localAddresses);
97
98 /**
99 * Sets the default local addresses to bind when no argument is specified
100 * in {@link #bind()} method. Please note that the default will not be
101 * used if any local address is specified.
102 */
103 void setDefaultLocalAddresses(List<? extends SocketAddress> localAddresses);
104
105 /**
106 * Returns <tt>true</tt> if and only if all clients are closed when this
107 * acceptor unbinds from all the related local address (i.e. when the
108 * service is deactivated).
109 */
110 boolean isCloseOnDeactivation();
111
112 /**
113 * Sets whether all client sessions are closed when this acceptor unbinds
114 * from all the related local addresses (i.e. when the service is
115 * deactivated). The default value is <tt>true</tt>.
116 */
117 void setCloseOnDeactivation(boolean closeOnDeactivation);
118
119 /**
120 * Binds to the default local address(es) and start to accept incoming
121 * connections.
122 *
123 * @throws IOException if failed to bind
124 */
125 void bind() throws IOException;
126
127 /**
128 * Binds to the specified local address and start to accept incoming
129 * connections.
130 *
131 * @throws IOException if failed to bind
132 */
133 void bind(SocketAddress localAddress) throws IOException;
134
135 /**
136 * Binds to the specified local addresses and start to accept incoming
137 * connections.
138 *
139 * @throws IOException if failed to bind
140 */
141 void bind(SocketAddress firstLocalAddress, SocketAddress... otherLocalAddresses) throws IOException;
142
143 /**
144 * Binds to the specified local addresses and start to accept incoming
145 * connections.
146 *
147 * @throws IOException if failed to bind
148 */
149 void bind(Iterable<? extends SocketAddress> localAddresses) throws IOException;
150
151 /**
152 * Unbinds from all local addresses that this service is bound to and stops
153 * to accept incoming connections. All managed connections will be closed
154 * if {@link #setCloseOnDeactivation(boolean) disconnectOnUnbind} property
155 * is <tt>true</tt>. This method returns silently if no local address is
156 * bound yet.
157 */
158 void unbind();
159
160 /**
161 * Unbinds from the specified local address and stop to accept incoming
162 * connections. All managed connections will be closed if
163 * {@link #setCloseOnDeactivation(boolean) disconnectOnUnbind} property is
164 * <tt>true</tt>. This method returns silently if the default local
165 * address is not bound yet.
166 */
167 void unbind(SocketAddress localAddress);
168
169 /**
170 * Unbinds from the specified local addresses and stop to accept incoming
171 * connections. All managed connections will be closed if
172 * {@link #setCloseOnDeactivation(boolean) disconnectOnUnbind} property is
173 * <tt>true</tt>. This method returns silently if the default local
174 * addresses are not bound yet.
175 */
176 void unbind(SocketAddress firstLocalAddress, SocketAddress... otherLocalAddresses);
177
178 /**
179 * Unbinds from the specified local addresses and stop to accept incoming
180 * connections. All managed connections will be closed if
181 * {@link #setCloseOnDeactivation(boolean) disconnectOnUnbind} property is
182 * <tt>true</tt>. This method returns silently if the default local
183 * addresses are not bound yet.
184 */
185 void unbind(Iterable<? extends SocketAddress> localAddresses);
186
187 /**
188 * (Optional) Returns an {@link IoSession} that is bound to the specified
189 * <tt>localAddress</tt> and the specified <tt>remoteAddress</tt> which
190 * reuses the local address that is already bound by this service.
191 * <p>
192 * This operation is optional. Please throw {@link UnsupportedOperationException}
193 * if the transport type doesn't support this operation. This operation is
194 * usually implemented for connectionless transport types.
195 *
196 * @throws UnsupportedOperationException if this operation is not supported
197 * @throws IllegalStateException if this service is not running.
198 * @throws IllegalArgumentException if this service is not bound to the
199 * specified <tt>localAddress</tt>.
200 */
201 IoSession newSession(SocketAddress remoteAddress, SocketAddress localAddress);
202 }