001/** 002 * Logback: the reliable, generic, fast and flexible logging framework. 003 * Copyright (C) 1999-2015, QOS.ch. All rights reserved. 004 * 005 * This program and the accompanying materials are dual-licensed under 006 * either the terms of the Eclipse Public License v1.0 as published by 007 * the Eclipse Foundation 008 * 009 * or (per the licensee's choosing) 010 * 011 * under the terms of the GNU Lesser General Public License version 2.1 012 * as published by the Free Software Foundation. 013 */ 014package ch.qos.logback.core.net.server; 015 016import java.io.Closeable; 017import java.io.IOException; 018 019/** 020 * A listener that accepts {@link Client} connections on behalf of a 021 * {@link ServerRunner}. 022 * <p> 023 * This interface exists primarily to abstract away the details of the 024 * listener's underlying {@code ServerSocket} and the concurrency associated 025 * with handling multiple clients. Such realities make it difficult to create 026 * effective unit tests for the {@link ServerRunner} that are easy to understand 027 * and maintain. 028 * <p> 029 * This interface captures the only those details about the listener that the 030 * {@code ServerRunner} cares about; namely, that it is something that has an 031 * underlying resource (or resources) that need to be closed before the listener 032 * is discarded. 033 * 034 */ 035public interface ServerListener<T extends Client> extends Closeable { 036 037 /** 038 * Accepts the next client that appears on this listener. 039 * <p> 040 * An implementation of this method is expected to block the calling thread and 041 * not return until either a client appears or an exception occurs. 042 * 043 * @return client object 044 * @throws IOException 045 * @throws InterruptedException 046 */ 047 T acceptClient() throws IOException, InterruptedException; 048 049 /** 050 * Closes any underlying {@link Closeable} resources associated with this 051 * listener. 052 * <p> 053 * Note that (as described in Doug Lea's discussion about interrupting I/O 054 * operations in "Concurrent Programming in Java" - Addison-Wesley Professional, 055 * 2nd edition, 1999) this method is used to interrupt any blocked I/O operation 056 * in the client when the server is shutting down. The client implementation 057 * must anticipate this potential, and gracefully exit when the blocked I/O 058 * operation throws the relevant {@link IOException} subclass. 059 * <p> 060 * Note also, that unlike {@link Closeable#close()} this method is not permitted 061 * to propagate any {@link IOException} that occurs when closing the underlying 062 * resource(s). 063 */ 064 void close(); 065 066}