View Javadoc
1   /**
2    * Logback: the reliable, generic, fast and flexible logging framework.
3    * Copyright (C) 1999-2015, QOS.ch. All rights reserved.
4    *
5    * This program and the accompanying materials are dual-licensed under
6    * either the terms of the Eclipse Public License v1.0 as published by
7    * the Eclipse Foundation
8    *
9    *   or (per the licensee's choosing)
10   *
11   * under the terms of the GNU Lesser General Public License version 2.1
12   * as published by the Free Software Foundation.
13   */
14  package ch.qos.logback.core.net.server;
15  
16  import java.io.Closeable;
17  import java.io.IOException;
18  
19  /**
20   * A listener that accepts {@link Client} connections on behalf of a
21   * {@link ServerRunner}.
22   * <p>
23   * This interface exists primarily to abstract away the details of the
24   * listener's underlying {@code ServerSocket} and the concurrency associated
25   * with handling multiple clients. Such realities make it difficult to create
26   * effective unit tests for the {@link ServerRunner} that are easy to 
27   * understand and maintain.
28   * <p>
29   * This interface captures the only those details about the listener that the
30   * {@code ServerRunner} cares about; namely, that it is something that has
31   * an underlying resource (or resources) that need to be closed before the
32   * listener is discarded.
33   * 
34   */
35  public interface ServerListener<T extends Client> extends Closeable {
36  
37      /**
38       * Accepts the next client that appears on this listener.
39       * <p>
40       * An implementation of this method is expected to block the calling thread
41       * and not return until either a client appears or an exception occurs.
42       * 
43       * @return client object
44       * @throws IOException
45       * @throws InterruptedException
46       */
47      T acceptClient() throws IOException, InterruptedException;
48  
49      /**
50       * Closes any underlying {@link Closeable} resources associated with this
51       * listener.
52       * <p>
53       * Note that (as described in Doug Lea's discussion about interrupting I/O
54       * operations in "Concurrent Programming in Java" (Addison-Wesley 
55       * Professional, 2nd edition, 1999) this method is used to interrupt
56       * any blocked I/O operation in the client when the server is shutting
57       * down.  The client implementation must anticipate this potential,
58       * and gracefully exit when the blocked I/O operation throws the 
59       * relevant {@link IOException} subclass. 
60       * <p>
61       * Note also, that unlike {@link Closeable#close()} this method is not
62       * permitted to propagate any {@link IOException} that occurs when closing
63       * the underlying resource(s).
64       */
65      void close();
66  
67  }