/*
 * GNU LESSER GENERAL PUBLIC LICENSE Copyright (C) 2006 The Lobo Project
 * 
 * This library 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 library 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 library; if not, write to the Free Software Foundation, Inc.,
 * 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
 * 
 * Contact info: lobochief@users.sourceforge.net
 */
/*
 * Created on Nov 13, 2005
 */
package com.nvarghese.beowulf.common.cobra.html;

import java.awt.Image;
import java.net.URL;

import org.w3c.dom.Document;

/**
 * The <code>HttpRequest</code> interface should be implemented to provide web
 * request capabilities. It is used a similar manner to
 * <code>XMLHttpRequest</code> in Javascript (AJAX). Normally, a listener will
 * be added by calling
 * {@link #addReadyStateChangeListener(ReadyStateChangeListener)}, the method
 * {@link #open(String, URL, boolean, String, String) open} will be called, and
 * finally, {@link #send(String)} will be called to complete the request.
 * 
 * @see UserAgentContext#createHttpRequest()
 */
public interface HttpRequest {

	/**
	 * The uninitialized request state.
	 */
	public static final int STATE_UNINITIALIZED = 0;

	/**
	 * The loading request state. The <code>open</code> method has been called,
	 * but a response has not been received yet.
	 */
	public static final int STATE_LOADING = 1;

	/**
	 * The loaded request state. Headers and status are now available.
	 */
	public static final int STATE_LOADED = 2;

	/**
	 * The interactive request state. Downloading response.
	 */
	public static final int STATE_INTERACTIVE = 3;

	/**
	 * The complete request state. All operations are finished.
	 */
	public static final int STATE_COMPLETE = 4;

	/**
	 * Gets the state of the request, a value between 0 and 4.
	 * 
	 * @return A value corresponding to one of the STATE* constants in this
	 *         class.
	 */
	public int getReadyState();

	/**
	 * Gets the request response as text.
	 */
	public String getResponseText();

	/**
	 * Gets the request response as an XML DOM.
	 */
	public Document getResponseXML();

	/**
	 * Gets the request response as an AWT image.
	 */
	public Image getResponseImage();

	/**
	 * Gets the request response bytes.
	 */
	public byte[] getResponseBytes();

	/**
	 * Gets the status of the response. Note that this can be 0 for file
	 * requests in addition to 200 for successful HTTP requests.
	 */
	public int getStatus();

	/**
	 * Gets the status text of the request, e.g. "OK" for 200.
	 */
	public String getStatusText();

	/**
	 * Aborts an ongoing request.
	 */
	public void abort();

	/**
	 * Gets a string with all the response headers.
	 */
	public String getAllResponseHeaders();

	/**
	 * Gets a response header value.
	 * 
	 * @param headerName
	 *            The name of the header.
	 */
	public String getResponseHeader(String headerName);

	/**
	 * Sets a request header
	 * 
	 * @param headerName
	 * @param value
	 */
	public void setRequestHeader(String headerName, String value);

	/**
	 * Starts an asynchronous request.
	 * 
	 * @param method
	 *            The request method.
	 * @param url
	 *            The destination URL.
	 */
	public void open(String method, String url) throws java.io.IOException;

	/**
	 * Opens an asynchronous request.
	 * 
	 * @param method
	 *            The request method.
	 * @param url
	 *            The destination URL.
	 */
	public void open(String method, URL url) throws java.io.IOException;

	/**
	 * Opens an request.
	 * 
	 * @param method
	 *            The request method.
	 * @param url
	 *            The destination URL.
	 * @param asyncFlag
	 *            Whether the request is asynchronous.
	 */
	public void open(String method, URL url, boolean asyncFlag) throws java.io.IOException;

	/**
	 * Opens a request.
	 * 
	 * @param method
	 *            The request method.
	 * @param url
	 *            The destination URL.
	 * @param asyncFlag
	 *            Whether the request should be asynchronous.
	 */
	public void open(String method, String url, boolean asyncFlag) throws java.io.IOException;

	/**
	 * Opens a request.
	 * 
	 * @param method
	 *            The request method.
	 * @param url
	 *            The destination URL.
	 * @param asyncFlag
	 *            Whether the request should be asynchronous.
	 * @param userName
	 *            The HTTP authentication user name.
	 */
	public void open(String method, java.net.URL url, boolean asyncFlag, String userName) throws java.io.IOException;

	/**
	 * Opens a request.
	 * 
	 * @param method
	 *            The request method.
	 * @param url
	 *            The destination URL.
	 * @param asyncFlag
	 *            Whether the request should be asynchronous.
	 * @param userName
	 *            The HTTP authentication user name.
	 * @param password
	 *            The HTTP authentication password.
	 */
	public void open(String method, java.net.URL url, boolean asyncFlag, String userName, String password) throws java.io.IOException;

	/**
	 * Sends POST content if any.
	 * 
	 * @param content
	 *            POST content or <code>null</code> for GET requests.
	 * @throws java.io.IOException
	 */
	public void send(String content) throws java.io.IOException;

	public boolean wasSend();

	/**
	 * Adds a listener of ReadyState changes. The listener should be invoked
	 * even in the case of errors.
	 * 
	 * @param listener
	 *            An instanceof of
	 *            {@link org.lobobrowser.html.ReadyStateChangeListener}
	 */
	public void addReadyStateChangeListener(ReadyStateChangeListener listener);
}