View Javadoc

1   /*
2    * ====================================================================
3    * Licensed to the Apache Software Foundation (ASF) under one
4    * or more contributor license agreements.  See the NOTICE file
5    * distributed with this work for additional information
6    * regarding copyright ownership.  The ASF licenses this file
7    * to you under the Apache License, Version 2.0 (the
8    * "License"); you may not use this file except in compliance
9    * with the License.  You may obtain a copy of the License at
10   *
11   *   http://www.apache.org/licenses/LICENSE-2.0
12   *
13   * Unless required by applicable law or agreed to in writing,
14   * software distributed under the License is distributed on an
15   * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
16   * KIND, either express or implied.  See the License for the
17   * specific language governing permissions and limitations
18   * under the License.
19   * ====================================================================
20   *
21   * This software consists of voluntary contributions made by many
22   * individuals on behalf of the Apache Software Foundation.  For more
23   * information on the Apache Software Foundation, please see
24   * <http://www.apache.org/>.
25   *
26   */
27  
28  package org.apache.http.nio.reactor;
29  
30  import java.net.SocketAddress;
31  import java.util.Set;
32  import java.io.IOException;
33  
34  /**
35   * ListeningIOReactor represents an I/O reactor capable of listening for
36   * incoming connections on one or several ports.
37   *
38   * @since 4.0
39   */
40  public interface ListeningIOReactor extends IOReactor {
41  
42      /**
43       * Opens a new listener endpoint with the given socket address. Once
44       * the endpoint is fully initialized it starts accepting incoming
45       * connections and propagates I/O activity notifications to the I/O event
46       * dispatcher.
47       * <p>
48       * {@link ListenerEndpoint#waitFor()} can be used to wait for the
49       *  listener to be come ready to accept incoming connections.
50       * <p>
51       * {@link ListenerEndpoint#close()} can be used to shut down
52       * the listener even before it is fully initialized.
53       *
54       * @param address the socket address to listen on.
55       * @return listener endpoint.
56       */
57      ListenerEndpoint listen(SocketAddress address);
58  
59      /**
60       * Suspends the I/O reactor preventing it from accepting new connections on
61       * all active endpoints.
62       *
63       * @throws IOException in case of an I/O error.
64       */
65      void pause()
66          throws IOException;
67  
68      /**
69       * Resumes the I/O reactor restoring its ability to accept incoming
70       * connections on all active endpoints.
71       *
72       * @throws IOException in case of an I/O error.
73       */
74      void resume()
75          throws IOException;
76  
77      /**
78       * Returns a set of endpoints for this I/O reactor.
79       *
80       * @return set of endpoints.
81       */
82      Set<ListenerEndpoint> getEndpoints();
83  
84  }