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 understand 27 * 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 an 31 * underlying resource (or resources) that need to be closed before the listener 32 * 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 and 41 * 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 Professional, 55 * 2nd edition, 1999) this method is used to interrupt any blocked I/O operation 56 * in the client when the server is shutting down. The client implementation 57 * must anticipate this potential, and gracefully exit when the blocked I/O 58 * operation throws the relevant {@link IOException} subclass. 59 * <p> 60 * Note also, that unlike {@link Closeable#close()} this method is not permitted 61 * to propagate any {@link IOException} that occurs when closing the underlying 62 * resource(s). 63 */ 64 void close(); 65 66 }