View Javadoc

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 }