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}