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