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 <a href="http://mina.apache.org">Apache MINA Project</a> 45 */ 46 public interface IoAcceptor extends IoService { 47 /** 48 * Returns the local address which is bound currently. If more than one 49 * address are bound, only one of them will be returned, but it's not 50 * necessarily the firstly bound address. 51 * 52 * @return The bound LocalAddress 53 */ 54 SocketAddress getLocalAddress(); 55 56 /** 57 * Returns a {@link Set} of the local addresses which are bound currently. 58 * 59 * @return The Set of bound LocalAddresses 60 */ 61 Set<SocketAddress> getLocalAddresses(); 62 63 /** 64 * Returns the default local address to bind when no argument is specified 65 * in {@link #bind()} method. Please note that the default will not be 66 * used if any local address is specified. If more than one address are 67 * set, only one of them will be returned, but it's not necessarily the 68 * firstly specified address in {@link #setDefaultLocalAddresses(List)}. 69 * 70 * @return The default bound LocalAddress 71 */ 72 SocketAddress getDefaultLocalAddress(); 73 74 /** 75 * Returns a {@link List} of the default local addresses to bind when no 76 * argument is specified in {@link #bind()} method. Please note that the 77 * default will not be used if any local address is specified. 78 * 79 * @return The list of default bound LocalAddresses 80 */ 81 List<SocketAddress> getDefaultLocalAddresses(); 82 83 /** 84 * Sets the default local address to bind when no argument is specified in 85 * {@link #bind()} method. Please note that the default will not be used 86 * if any local address is specified. 87 * 88 * @param localAddress The local addresses to bind the acceptor on 89 */ 90 void setDefaultLocalAddress(SocketAddress localAddress); 91 92 /** 93 * Sets the default local addresses to bind when no argument is specified 94 * in {@link #bind()} method. Please note that the default will not be 95 * used if any local address is specified. 96 * @param firstLocalAddress The first local address to bind the acceptor on 97 * @param otherLocalAddresses The other local addresses to bind the acceptor on 98 */ 99 void setDefaultLocalAddresses(SocketAddress firstLocalAddress, SocketAddress... otherLocalAddresses); 100 101 /** 102 * Sets the default local addresses to bind when no argument is specified 103 * in {@link #bind()} method. Please note that the default will not be 104 * used if any local address is specified. 105 * 106 * @param localAddresses The local addresses to bind the acceptor on 107 */ 108 void setDefaultLocalAddresses(Iterable<? extends SocketAddress> localAddresses); 109 110 /** 111 * Sets the default local addresses to bind when no argument is specified 112 * in {@link #bind()} method. Please note that the default will not be 113 * used if any local address is specified. 114 * 115 * @param localAddresses The local addresses to bind the acceptor on 116 */ 117 void setDefaultLocalAddresses(List<? extends SocketAddress> localAddresses); 118 119 /** 120 * Returns <tt>true</tt> if and only if all clients are closed when this 121 * acceptor unbinds from all the related local address (i.e. when the 122 * service is deactivated). 123 * 124 * @return <tt>true</tt> if the service sets the closeOnDeactivation flag 125 */ 126 boolean isCloseOnDeactivation(); 127 128 /** 129 * Sets whether all client sessions are closed when this acceptor unbinds 130 * from all the related local addresses (i.e. when the service is 131 * deactivated). The default value is <tt>true</tt>. 132 * 133 * @param closeOnDeactivation <tt>true</tt> if we should close on deactivation 134 */ 135 void setCloseOnDeactivation(boolean closeOnDeactivation); 136 137 /** 138 * Binds to the default local address(es) and start to accept incoming 139 * connections. 140 * 141 * @throws IOException if failed to bind 142 */ 143 void bind() throws IOException; 144 145 /** 146 * Binds to the specified local address and start to accept incoming 147 * connections. 148 * 149 * @param localAddress The SocketAddress to bind to 150 * 151 * @throws IOException if failed to bind 152 */ 153 void bind(SocketAddress localAddress) throws IOException; 154 155 /** 156 * Binds to the specified local addresses and start to accept incoming 157 * connections. If no address is given, bind on the default local address. 158 * 159 * @param firstLocalAddress The first address to bind to 160 * @param addresses The SocketAddresses to bind to 161 * 162 * @throws IOException if failed to bind 163 */ 164 void bind(SocketAddress firstLocalAddress, SocketAddress... addresses) throws IOException; 165 166 /** 167 * Binds to the specified local addresses and start to accept incoming 168 * connections. If no address is given, bind on the default local address. 169 * 170 * @param addresses The SocketAddresses to bind to 171 * 172 * @throws IOException if failed to bind 173 */ 174 void bind(SocketAddress... addresses) throws IOException; 175 176 /** 177 * Binds to the specified local addresses and start to accept incoming 178 * connections. 179 * 180 * @param localAddresses The local address we will be bound to 181 * @throws IOException if failed to bind 182 */ 183 void bind(Iterable<? extends SocketAddress> localAddresses) throws IOException; 184 185 /** 186 * Unbinds from all local addresses that this service is bound to and stops 187 * to accept incoming connections. All managed connections will be closed 188 * if {@link #setCloseOnDeactivation(boolean) disconnectOnUnbind} property 189 * is <tt>true</tt>. This method returns silently if no local address is 190 * bound yet. 191 */ 192 void unbind(); 193 194 /** 195 * Unbinds from the specified local address and stop to accept incoming 196 * connections. All managed connections will be closed if 197 * {@link #setCloseOnDeactivation(boolean) disconnectOnUnbind} property is 198 * <tt>true</tt>. This method returns silently if the default local 199 * address is not bound yet. 200 * 201 * @param localAddress The local address we will be unbound from 202 */ 203 void unbind(SocketAddress localAddress); 204 205 /** 206 * Unbinds from the specified local addresses and stop to accept incoming 207 * connections. All managed connections will be closed if 208 * {@link #setCloseOnDeactivation(boolean) disconnectOnUnbind} property is 209 * <tt>true</tt>. This method returns silently if the default local 210 * addresses are not bound yet. 211 * 212 * @param firstLocalAddress The first local address to be unbound from 213 * @param otherLocalAddresses The other local address to be unbound from 214 */ 215 void unbind(SocketAddress firstLocalAddress, SocketAddress... otherLocalAddresses); 216 217 /** 218 * Unbinds from the specified local addresses and stop to accept incoming 219 * connections. All managed connections will be closed if 220 * {@link #setCloseOnDeactivation(boolean) disconnectOnUnbind} property is 221 * <tt>true</tt>. This method returns silently if the default local 222 * addresses are not bound yet. 223 * 224 * @param localAddresses The local address we will be unbound from 225 */ 226 void unbind(Iterable<? extends SocketAddress> localAddresses); 227 228 /** 229 * (Optional) Returns an {@link IoSession} that is bound to the specified 230 * <tt>localAddress</tt> and the specified <tt>remoteAddress</tt> which 231 * reuses the local address that is already bound by this service. 232 * <p> 233 * This operation is optional. Please throw {@link UnsupportedOperationException} 234 * if the transport type doesn't support this operation. This operation is 235 * usually implemented for connectionless transport types. 236 * 237 * @param remoteAddress The remote address bound to the service 238 * @param localAddress The local address the session will be bound to 239 * @throws UnsupportedOperationException if this operation is not supported 240 * @throws IllegalStateException if this service is not running. 241 * @throws IllegalArgumentException if this service is not bound to the 242 * specified <tt>localAddress</tt>. 243 * @return The session bound to the the given localAddress and remote address 244 */ 245 IoSession newSession(SocketAddress remoteAddress, SocketAddress localAddress); 246 }