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 client of a {@link ServerRunner}.
21   * <p>
22   * This interface exists primarily to abstract away the details of the
23   * client's underlying {@code Socket} and the concurrency associated with
24   * handling multiple clients.  Such realities make it difficult to create 
25   * effective unit tests for the {@link ServerRunner} that are easy to 
26   * understand and maintain.
27   * <p>
28   * This interface captures the only those details about a client that
29   * the {@code ServerRunner} cares about; namely, that it is something that
30   * <ol>
31   *   <li>is Runnable &mdash; i.e. it can be executed concurrently</li>
32   *   <li>holds resources that need to be closed before the client is
33   *       discarded</li>
34   * </ol>
35   * 
36   * @author Carl Harris
37   */
38  public interface Client extends Runnable, Closeable {
39  
40      /**
41       * Closes any resources that are held by the client.
42       * <p>
43       * Note that (as described in Doug Lea's discussion about interrupting I/O
44       * operations in "Concurrent Programming in Java" (Addison-Wesley 
45       * Professional, 2nd edition, 1999) this method is used to interrupt
46       * any blocked I/O operation in the client when the server is shutting
47       * down.  The client implementation must anticipate this potential,
48       * and gracefully exit when the blocked I/O operation throws the
49       * relevant {@link IOException} subclass. 
50       * <p>
51       * Note also, that unlike {@link Closeable#close()} this method is not
52       * permitted to propagate any {@link IOException} that occurs when closing
53       * the underlying resource(s).
54       */
55      void close();
56  
57  }