View Javadoc

1   /*
2    *   @(#) $Id: ProtocolAcceptor.java 332218 2005-11-10 03:52:42Z trustin $
3    *
4    *   Copyright 2004 The Apache Software Foundation
5    *
6    *   Licensed under the Apache License, Version 2.0 (the "License");
7    *   you may not use this file except in compliance with the License.
8    *   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, software
13   *   distributed under the License is distributed on an "AS IS" BASIS,
14   *   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15   *   See the License for the specific language governing permissions and
16   *   limitations under the License.
17   *
18   */
19  package org.apache.mina.protocol;
20  
21  import java.io.IOException;
22  import java.net.SocketAddress;
23  
24  /***
25   * Accepts incoming connection, communicates with clients, and fires events to
26   * {@link ProtocolHandler}s.
27   * <p>
28   * Please refer to
29   * <a href="../../../../../xref-examples/org/apache/mina/examples/reverser/Main.html">Reverser</a>
30   * example. 
31   * <p>
32   * You should bind to the desired socket address to accept incoming
33   * connections, and then events for incoming connections will be sent to
34   * the specified default {@link ProtocolHandler}.
35   * <p>
36   * Threads accept incoming connections start automatically when
37   * {@link #bind(SocketAddress, ProtocolProvider)} is invoked, and stop when all
38   * addresses are unbound.
39   * 
40   * @author The Apache Directory Project (dev@directory.apache.org)
41   * @version $Rev: 332218 $, $Date: 2005-11-10 12:52:42 +0900 $
42   */
43  public interface ProtocolAcceptor extends ProtocolSessionManager
44  {
45      /***
46       * Binds to the specified <code>address</code> and handles incoming
47       * connections with the specified <code>protocolProvider</code>.
48       * 
49       * @throws IOException if failed to bind
50       */
51      void bind( SocketAddress address, ProtocolProvider protocolProvider )
52              throws IOException;
53  
54      /***
55       * Unbinds from the specified <code>address</code>.
56       */
57      void unbind( SocketAddress address );
58      
59      /***
60       * (Optional) Returns a {@link ProtocolSession} that is bound to the specified
61       * <tt>localAddress</tt> and <tt>remoteAddress</tt> which reuses
62       * the <tt>localAddress</tt> that is already bound by {@link ProtocolAcceptor}
63       * via {@link #bind(SocketAddress, ProtocolProvider)}.
64       * <p>
65       * This operation is optional.  Please throw {@link UnsupportedOperationException}
66       * if the transport type doesn't support this operation.  This operation is
67       * usually implemented for connectionless transport types.
68       * 
69       * @throws UnsupportedOperationException if this operation is not supported
70       * @throws IllegalArgumentException if the specified <tt>localAddress</tt> is
71       *                                  not bound yet. (see {@link #bind(SocketAddress, ProtocolProvider)})
72       */
73      ProtocolSession newSession( SocketAddress remoteAddress, SocketAddress localAddress );
74  }