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