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 client of a {@link ServerRunner}.
021 * <p>
022 * This interface exists primarily to abstract away the details of the
023 * client's underlying {@code Socket} and the concurrency associated with
024 * handling multiple clients.  Such realities make it difficult to create 
025 * effective unit tests for the {@link ServerRunner} that are easy to 
026 * understand and maintain.
027 * <p>
028 * This interface captures the only those details about a client that
029 * the {@code ServerRunner} cares about; namely, that it is something that
030 * <ol>
031 *   <li>is Runnable &mdash; i.e. it can be executed concurrently</li>
032 *   <li>holds resources that need to be closed before the client is
033 *       discarded</li>
034 * </ol>
035 * 
036 * @author Carl Harris
037 */
038public interface Client extends Runnable, Closeable {
039
040    /**
041     * Closes any resources that are held by the client.
042     * <p>
043     * Note that (as described in Doug Lea's discussion about interrupting I/O
044     * operations in "Concurrent Programming in Java" (Addison-Wesley 
045     * Professional, 2nd edition, 1999) this method is used to interrupt
046     * any blocked I/O operation in the client when the server is shutting
047     * down.  The client implementation must anticipate this potential,
048     * and gracefully exit when the blocked I/O operation throws the
049     * relevant {@link IOException} subclass. 
050     * <p>
051     * Note also, that unlike {@link Closeable#close()} this method is not
052     * permitted to propagate any {@link IOException} that occurs when closing
053     * the underlying resource(s).
054     */
055    void close();
056
057}