001: /*
002: * Licensed to the Apache Software Foundation (ASF) under one
003: * or more contributor license agreements. See the NOTICE file
004: * distributed with this work for additional information
005: * regarding copyright ownership. The ASF licenses this file
006: * to you under the Apache License, Version 2.0 (the
007: * "License"); you may not use this file except in compliance
008: * with the License. You may obtain a copy of the License at
009: *
010: * http://www.apache.org/licenses/LICENSE-2.0
011: *
012: * Unless required by applicable law or agreed to in writing,
013: * software distributed under the License is distributed on an
014: * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
015: * KIND, either express or implied. See the License for the
016: * specific language governing permissions and limitations
017: * under the License.
018: *
019: */
020: package org.apache.mina.common;
021:
022: import java.io.IOException;
023: import java.net.SocketAddress;
024: import java.util.List;
025: import java.util.Set;
026:
027: /**
028: * Accepts incoming connection, communicates with clients, and fires events to
029: * {@link IoHandler}s.
030: * <p>
031: * Please refer to
032: * <a href="../../../../../xref-examples/org/apache/mina/examples/echoserver/Main.html">EchoServer</a>
033: * example.
034: * <p>
035: * You should bind to the desired socket address to accept incoming
036: * connections, and then events for incoming connections will be sent to
037: * the specified default {@link IoHandler}.
038: * <p>
039: * Threads accept incoming connections start automatically when
040: * {@link #bind()} is invoked, and stop when {@link #unbind()} is invoked.
041: *
042: * @author The Apache MINA Project (dev@mina.apache.org)
043: * @version $Rev: 601229 $, $Date: 2007-12-05 00:13:18 -0700 (Wed, 05 Dec 2007) $
044: */
045: public interface IoAcceptor extends IoService {
046: /**
047: * Returns the local address which is bound currently. If more than one
048: * address are bound, only one of them will be returned, but it's not
049: * necessarily the firstly bound address.
050: */
051: SocketAddress getLocalAddress();
052:
053: /**
054: * Returns a {@link Set} of the local addresses which are bound currently.
055: */
056: Set<SocketAddress> getLocalAddresses();
057:
058: /**
059: * Returns the default local address to bind when no argument is specified
060: * in {@link #bind()} method. Please note that the default will not be
061: * used if any local address is specified. If more than one address are
062: * set, only one of them will be returned, but it's not necessarily the
063: * firstly specified address in {@link #setDefaultLocalAddresses(List)}.
064: *
065: */
066: SocketAddress getDefaultLocalAddress();
067:
068: /**
069: * Returns a {@link List} of the default local addresses to bind when no
070: * argument is specified in {@link #bind()} method. Please note that the
071: * default will not be used if any local address is specified.
072: */
073: List<SocketAddress> getDefaultLocalAddresses();
074:
075: /**
076: * Sets the default local address to bind when no argument is specified in
077: * {@link #bind()} method. Please note that the default will not be used
078: * if any local address is specified.
079: */
080: void setDefaultLocalAddress(SocketAddress localAddress);
081:
082: /**
083: * Sets the default local addresses to bind when no argument is specified
084: * in {@link #bind()} method. Please note that the default will not be
085: * used if any local address is specified.
086: */
087: void setDefaultLocalAddresses(SocketAddress firstLocalAddress,
088: SocketAddress... otherLocalAddresses);
089:
090: /**
091: * Sets the default local addresses to bind when no argument is specified
092: * in {@link #bind()} method. Please note that the default will not be
093: * used if any local address is specified.
094: */
095: void setDefaultLocalAddresses(
096: Iterable<? extends SocketAddress> localAddresses);
097:
098: /**
099: * 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(
104: List<? extends SocketAddress> localAddresses);
105:
106: /**
107: * Returns <tt>true</tt> if and only if all clients are closed when this
108: * acceptor unbinds from all the related local address (i.e. when the
109: * service is deactivated).
110: */
111: boolean isCloseOnDeactivation();
112:
113: /**
114: * Sets whether all client sessions are closed when this acceptor unbinds
115: * from all the related local addresses (i.e. when the service is
116: * deactivated). The default value is <tt>true</tt>.
117: */
118: void setCloseOnDeactivation(boolean closeOnDeactivation);
119:
120: /**
121: * Binds to the default local address(es) and start to accept incoming
122: * connections.
123: *
124: * @throws IOException if failed to bind
125: */
126: void bind() throws IOException;
127:
128: /**
129: * Binds to the specified local address and start to accept incoming
130: * connections.
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.
139: *
140: * @throws IOException if failed to bind
141: */
142: void bind(SocketAddress firstLocalAddress,
143: SocketAddress... otherLocalAddresses) throws IOException;
144:
145: /**
146: * Binds to the specified local addresses and start to accept incoming
147: * connections.
148: *
149: * @throws IOException if failed to bind
150: */
151: void bind(Iterable<? extends SocketAddress> localAddresses)
152: throws IOException;
153:
154: /**
155: * Unbinds from all local addresses that this service is bound to and stops
156: * to accept incoming connections. All managed connections will be closed
157: * if {@link #setCloseOnDeactivation(boolean) disconnectOnUnbind} property
158: * is <tt>true</tt>. This method returns silently if no local address is
159: * bound yet.
160: */
161: void unbind();
162:
163: /**
164: * Unbinds from the specified local address and stop to accept incoming
165: * connections. All managed connections will be closed if
166: * {@link #setCloseOnDeactivation(boolean) disconnectOnUnbind} property is
167: * <tt>true</tt>. This method returns silently if the default local
168: * address is not bound yet.
169: */
170: void unbind(SocketAddress localAddress);
171:
172: /**
173: * Unbinds from the specified local addresses and stop to accept incoming
174: * connections. All managed connections will be closed if
175: * {@link #setCloseOnDeactivation(boolean) disconnectOnUnbind} property is
176: * <tt>true</tt>. This method returns silently if the default local
177: * addresses are not bound yet.
178: */
179: void unbind(SocketAddress firstLocalAddress,
180: SocketAddress... otherLocalAddresses);
181:
182: /**
183: * Unbinds from the specified local addresses and stop to accept incoming
184: * connections. All managed connections will be closed if
185: * {@link #setCloseOnDeactivation(boolean) disconnectOnUnbind} property is
186: * <tt>true</tt>. This method returns silently if the default local
187: * addresses are not bound yet.
188: */
189: void unbind(Iterable<? extends SocketAddress> localAddresses);
190:
191: /**
192: * (Optional) Returns an {@link IoSession} that is bound to the specified
193: * <tt>localAddress</tt> and the specified <tt>remoteAddress</tt> which
194: * reuses the local address that is already bound by this service.
195: * <p>
196: * This operation is optional. Please throw {@link UnsupportedOperationException}
197: * if the transport type doesn't support this operation. This operation is
198: * usually implemented for connectionless transport types.
199: *
200: * @throws UnsupportedOperationException if this operation is not supported
201: * @throws IllegalStateException if this service is not running.
202: * @throws IllegalArgumentException if this service is not bound to the
203: * specified <tt>localAddress</tt>.
204: */
205: IoSession newSession(SocketAddress remoteAddress,
206: SocketAddress localAddress);
207: }
|