package org.wikiwebserver.core.interfaces;

import java.net.Socket;

/**
 * A ConnectionHandler reads requests from a socket, processes them, generates 
 * a response and writes the response to the socket.
 * 
 * This interface outlines functionality required when handling connections
 * on a socket.
 * 
 * @author Dr Michael Gardiner
 */
public interface ConnectionHandler {
    
    /**
     * Configures this connection handler to perform specific actions based on
     * the specified configuration.
     * 
     * @param config A configuration that determines the operation of the handler.
     */
    public void configure(HandlerConfiguration config);
    
    /**
     * Reads from the socket, processes requests and returns responses on the
     * specified socket.
     * 
     * @param sock The socket to read requests and write responses.
     */
    public void handle(Socket sock);
    
    /**
     * Returns the amount of time in milliseconds since request processing
     * started. For some protocols, such as HTTP 1.1, multiple requests
     * may be handled on a single connection. This is the request duration
     * not the connection duration.
     * 
     * @return The number of milliseconds since request processing started.
     */
    public long getExecutionTime();
    
    /**
     * Notifies this handler that no more requests should be handled on the
     * current connection and request processing should end gracefully as
     * soon as possible.
     */
    public void gracefulClose();
    
    /**
     * Forces this handler to stop handling requests and close the connection.
     * The handler thread will end when the connection is next read or
     * written to (this might not be immediately).
     */
    public void forceClose();
    
    /**
     * Attempts to interrupt the thread currently handling requests. If this
     * fails the thread will be forcefully stopped.  This method is a last
     * resort and should only be called on untrusted code.
     */
    public void forceStop();    
}