/*
 * JBoss, Home of Professional Open Source
 * Copyright 2008, JBoss Inc., and individual contributors as indicated
 * by the @authors tag. See the copyright.txt in the distribution for a
 * full listing of individual contributors.
 *
 * This is free software; you can redistribute it and/or modify it
 * under the terms of the GNU Lesser General Public License as
 * published by the Free Software Foundation; either version 2.1 of
 * the License, or (at your option) any later version.
 *
 * This software is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
 * License along with this software; if not, write to the Free
 * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
 * 02110-1301 USA, or see the FSF site: http://www.fsf.org.
 */

package org.jboss.servlet.http;

import java.io.IOException;

import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;

/**
 * The HttpEvent interface, which indicates the type of the event that is
 * being processed, as well as provides useful callbacks and utility objects.
 */
public interface HttpEvent {

    /**
     * Enumeration describing the major events that the container can invoke 
     * the EventHttpServlet event() method with:
     * <ul>
     * <li>BEGIN - will be called at the beginning 
     *  of the processing of the connection. It can be used to initialize any relevant 
     *  fields using the request and response objects. Between the end of the processing 
     *  of this event, and the beginning of the processing of the end or error events,
     *  it is possible to use the response object to write data on the open connection.
     *  Note that the response object and dependent OutputStream and Writer are  
     *  not synchronized, so when they are accessed by multiple threads adequate
     *  synchronization is needed. After processing the initial event, the request 
     *  is considered to be committed.</li>
     * <li>EOF - The end of file of the input has been reached, and no further data is
     *  available. This event is sent because it can be difficult to detect otherwise.
     *  Following the processing of this event and the processing of any subsequent
     *  event, the event will be suspended.</li>
     * <li>END - End may be called to end the processing of the request. Fields that have
     *  been initialized in the begin method should be reset. After this event has
     *  been processed, the request and response objects, as well as all their dependent
     *  objects will be recycled and used to process other requests. In particular,
     *  this event will be called if the HTTP session associated with the connection
     *  times out, if the web application is reloaded, if the server is shutdown, or
     *  if the connection was closed asynchronously.</li>
     * <li>ERROR - Error will be called by the container in the case where an IO exception
     *  or a similar unrecoverable error occurs on the connection. Fields that have
     *  been initialized in the begin method should be reset. After this event has
     *  been processed, the request and response objects, as well as all their dependent
     *  objects will be recycled and used to process other requests.</li>
     * <li>EVENT - Event will be called by the container after the resume() method is called,
     *  during which any operations can be performed, including closing the connection
     *  using the close() method.</li>
     * <li>READ - This indicates that input data is available, and that at least one 
     *  read can be made without blocking. The available and ready methods of the InputStream or
     *  Reader may be used to determine if there is a risk of blocking: the Servlet
     *  must continue reading while data is reported available. When encountering a read error, 
     *  the Servlet should report it by propagating the exception properly. Throwing 
     *  an exception will cause the error event to be invoked, and the connection 
     *  will be closed. 
     *  Alternately, it is also possible to catch any exception, perform clean up
     *  on any data structure the Servlet may be using, and using the close method
     *  of the event. It is not allowed to attempt reading data from the request 
     *  object outside of the processing of this event, unless the suspend() method
     *  has been used.</li>
     * <li>TIMEOUT - the connection timed out, but the connection will not be closed unless 
     *  the servlet uses the close method of the event</li>
     * <li>WRITE - Write is sent if the Servlet is using the ready method. This means that 
     *  the connection is ready to receive data to be written out. This event will never
     *  be received if the Servlet is not using the ready() method, or if the ready() 
     *  method always returns true.</li>
     * </ul>
     */
    public enum EventType { BEGIN, END, ERROR, EVENT, READ, EOF, TIMEOUT, WRITE }
    
    
    /**
     * Returns the HttpServletRequest.
     * 
     * @return HttpServletRequest
     */
    public HttpServletRequest getHttpServletRequest();
    
    /**
     * Returns the HttpServletResponse.
     * 
     * @return HttpServletResponse
     */
    public HttpServletResponse getHttpServletResponse();
    
    /**
     * Returns the event type.
     * 
     * @return EventType
     * @see #EventType
     */
    public EventType getType();
    
    /**
     * Ends the request, which marks the end of the event stream. This will send 
     * back to the client a notice that the server has no more data to send 
     * as part of this request. An END event will be sent to the Servlet.
     * 
     * @throws IOException if an IO exception occurs
     */
    public void close() throws IOException;

    /**
     * This method sets the timeout in milliseconds of idle time on the connection.
     * The timeout is reset every time data is received from the connection. If a timeout occurs, the 
     * Servlet will receive an TIMEOUT event which will not result in automatically closing
     * the event (the event may be closed using the close() method).
     * 
     * @param timeout The timeout in milliseconds for this connection, must be a positive value, larger than 0
     */
    public void setTimeout(int timeout);

    /**
     * Returns true when data may be read from the connection (the flag becomes false if no data
     * is available to read). When the flag becomes false, the Servlet can attempt to read additional
     * data, but it will block until data is available. This method is equivalent to 
     * Reader.ready() and (InputStream.available() > 0).
     * 
     * @return boolean true if data can be read without blocking
     */
    public boolean isReadReady();

    /**
     * Returns true when data may be written to the connection (the flag becomes false 
     * when the client is unable to accept data fast enough). When the flag becomes false, 
     * the Servlet must stop writing data. If there's an attempt to flush additional data 
     * to the client and data still cannot be written immediately, an IOException will be 
     * thrown. If calling this method returns false, it will also 
     * request notification when the connection becomes available for writing again, and the  
     * Servlet will receive a write event.
     * <br>
     * Note: If the Servlet is not using isWriteReady, and is writing its output inside the
     * container threads (inside the event() method processing, for example), using this method
     * is not mandatory, and writes will block until all bytes are written.
     * 
     * @return boolean true if data can be written without blocking
     */
    public boolean isWriteReady();

    /**
     * Suspend processing of the connection until the configured timeout occurs, 
     * or resume() is called. In practice, this means the servlet will no longer 
     * receive read events. Reading should always be performed synchronously in 
     * the Tomcat threads unless the connection has been suspended.
     */
    public void suspend();

    /**
     * Resume will cause the Servlet container to send a generic event 
     * to the Servlet, where the request can be processed synchronously 
     * (for example, it is possible to use this to complete the request after 
     * some asynchronous processing is done). This also resumes read events 
     * if they have been disabled using suspend. It is then possible to call suspend 
     * again later. It is also possible to call resume without calling suspend before.
     * This method must be called asynchronously.
     */
    public void resume();

}