/*
 * Copyright 2008-2011 Thomas Nichols.  http://blog.thomnichols.org
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 *
 * You are receiving this code free of charge, which represents many hours of
 * effort from other individuals and corporations.  As a responsible member
 * of the community, you are encouraged (but not required) to donate any
 * enhancements or improvements back to the community under a similar open
 * source license.  Thank you. -TMN
 */
package groovyx.net.http;

import static groovyx.net.http.URIBuilder.convertToURI;
import groovy.lang.Closure;

import java.io.ByteArrayInputStream;
import java.io.ByteArrayOutputStream;
import java.io.Closeable;
import java.io.IOException;
import java.io.InputStream;
import java.io.Reader;
import java.io.StringReader;
import java.io.StringWriter;
import java.net.URI;
import java.net.URISyntaxException;
import java.net.URL;
import java.util.Arrays;
import java.util.Map;

import org.apache.commons.logging.Log;
import org.apache.commons.logging.LogFactory;
import org.apache.http.Header;
import org.apache.http.HttpEntity;
import org.apache.http.HttpEntityEnclosingRequest;
import org.apache.http.HttpHost;
import org.apache.http.HttpResponse;
import org.apache.http.client.ClientProtocolException;
import org.apache.http.client.ResponseHandler;
import org.apache.http.client.methods.HttpGet;
import org.apache.http.client.methods.HttpPost;
import org.apache.http.client.methods.HttpRequestBase;
import org.apache.http.client.protocol.ClientContext;
import org.apache.http.conn.ClientConnectionManager;
import org.apache.http.conn.params.ConnRoutePNames;
import org.apache.http.cookie.params.CookieSpecPNames;
import org.apache.http.client.HttpClient;
import org.apache.http.impl.client.AbstractHttpClient;
import org.apache.http.impl.client.DefaultHttpClient;
import org.apache.http.params.BasicHttpParams;
import org.apache.http.params.HttpParams;
import org.apache.http.protocol.HttpContext;
import org.codehaus.groovy.runtime.DefaultGroovyMethods;
import org.codehaus.groovy.runtime.MethodClosure;

/** <p>
 * Groovy DSL for easily making HTTP requests, and handling request and response
 * data.  This class adds a number of convenience mechanisms built on top of
 * Apache HTTPClient for things like URL-encoded POSTs and REST requests that
 * require building and parsing JSON or XML.  Convenient access to a few common
 * authentication methods is also available.</p>
 *
 *
 * <h3>Conventions</h3>
 * <p>HTTPBuilder has properties for default headers, URI, contentType, etc.
 * All of these values are also assignable (and in many cases, in much finer
 * detail) from the {@link RequestConfigDelegate} as well.  In any cases where the value
 * is not set on the delegate (from within a request closure,) the builder's
 * default value is used.  </p>
 *
 * <p>For instance, any methods that do not take a <code>uri</code> parameter
 * assume you will set the <code>uri</code> property in the request closure or
 * use HTTPBuilder's assigned {@link #getUri() default URI}.</p>
 *
 *
 * <h3>Response Parsing</h3>
 * <p>By default, HTTPBuilder uses {@link ContentType#ANY} as the default
 * content-type.  This means the value of the request's <code>Accept</code>
 * header is <code>&#42;/*</code>, and the response parser is determined
 * based on the response <code>content-type</code> header. </p>
 *
 * <p><strong>If</strong> any contentType is given (either in
 * {@link #setContentType(Object)} or as a request method parameter), the
 * builder will attempt to parse the response using that content-type,
 * regardless of what the server actually responds with.  </p>
 *
 *
 * <h3>Examples:</h3>
 * Perform an HTTP GET and print the response:
 * <pre>
 *   def http = new HTTPBuilder('http://www.google.com')
 *
 *   http.get( path : '/search',
 *             contentType : TEXT,
 *             query : [q:'Groovy'] ) { resp, reader ->
 *     println "response status: ${resp.statusLine}"
 *     println 'Response data: -----'
 *     System.out << reader
 *     println '\n--------------------'
 *   }
 * </pre>
 *
 * Long form for other HTTP methods, and response-code-specific handlers.
 * This is roughly equivalent to the above example.
 *
 * <pre>
 *   def http = new HTTPBuilder('http://www.google.com/search?q=groovy')
 *
 *   http.request( GET, TEXT ) { req ->
 *
 *     // executed for all successful responses:
 *     response.success = { resp, reader ->
 *       println 'my response handler!'
 *       assert resp.statusLine.statusCode == 200
 *       println resp.statusLine
 *       System.out << reader // print response stream
 *     }
 *
 *     // executed only if the response status code is 401:
 *     response.'404' = { resp ->
 *       println 'not found!'
 *     }
 *   }
 * </pre>
 *
 * You can also set a default response handler called for any status
 * code > 399 that is not matched to a specific handler. Setting the value
 * outside a request closure means it will apply to all future requests with
 * this HTTPBuilder instance:
 * <pre>
 *   http.handler.failure = { resp ->
 *     println "Unexpected failure: ${resp.statusLine}"
 *   }
 * </pre>
 *
 *
 * And...  Automatic response parsing for registered content types!
 *
 * <pre>
 *   http.request( 'http://ajax.googleapis.com', GET, JSON ) {
 *     uri.path = '/ajax/services/search/web'
 *     uri.query = [ v:'1.0', q: 'Calvin and Hobbes' ]
 *
 *     response.success = { resp, json ->
 *       assert json.size() == 3
 *       println "Query response: "
 *       json.responseData.results.each {
 *         println "  ${it.titleNoFormatting} : ${it.visibleUrl}"
 *       }
 *     }
 *   }
 * </pre>
 *
 *
 * @author <a href='mailto:[email protected]'>Tom Nichols</a>
 */
public class HTTPBuilder {

    private HttpClient client;
    protected URIBuilder defaultURI = null;
    protected AuthConfig auth = new AuthConfig( this );

    protected final Log log = LogFactory.getLog( getClass() );

    protected Object defaultContentType = ContentType.ANY;
    protected Object defaultRequestContentType = null;
    protected boolean autoAcceptHeader = true;
    protected final Map<Object,Closure> defaultResponseHandlers =
        new StringHashMap<Closure>( buildDefaultResponseHandlers() );
    protected ContentEncodingRegistry contentEncodingHandler = new ContentEncodingRegistry();

    protected final Map<Object,Object> defaultRequestHeaders = new StringHashMap<Object>();

    protected EncoderRegistry encoders = new EncoderRegistry();
    protected ParserRegistry parsers = new ParserRegistry();

    /**
     * Creates a new instance with a <code>null</code> default URI.
     */
    public HTTPBuilder() {
        setContentEncoding( ContentEncoding.Type.GZIP,
                ContentEncoding.Type.DEFLATE );
    }

    /**
     * Give a default URI to be used for all request methods that don't
     * explicitly take a URI parameter.
     * @param defaultURI either a {@link URL}, {@link URI} or object whose
     *  <code>toString()</code> produces a valid URI string.  See
     *  {@link URIBuilder#convertToURI(Object)}.
     * @throws URISyntaxException if the given argument does not represent a valid URI
     */
    public HTTPBuilder( Object defaultURI ) throws URISyntaxException {
        setUri( defaultURI );
    }

    /**
     * Give a default URI to be used for all request methods that don't
     * explicitly take a URI parameter, and a default content-type to be used
     * for request encoding and response parsing.
     * @param defaultURI either a {@link URL}, {@link URI} or object whose
     *  <code>toString()</code> produces a valid URI string.  See
     *  {@link URIBuilder#convertToURI(Object)}.
     * @param defaultContentType content-type string.  See {@link ContentType}
     *   for common types.
     * @throws URISyntaxException if the uri argument does not represent a valid URI
     */
    public HTTPBuilder( Object defaultURI, Object defaultContentType ) throws URISyntaxException {
        setUri( defaultURI );
        this.defaultContentType = defaultContentType;
    }

    /**
     * <p>Convenience method to perform an HTTP GET.  It will use the HTTPBuilder's
     * {@link #getHandler() registered response handlers} to handle success or
     * failure status codes.  By default, the <code>success</code> response
     * handler will attempt to parse the data and simply return the parsed
     * object.</p>
     *
     * <p><strong>Note:</strong> If using the {@link #defaultSuccessHandler(HttpResponseDecorator, Object)
     * default <code>success</code> response handler}, be sure to read the
     * caveat regarding streaming response data.</p>
     *
     * @see #getHandler()
     * @see #defaultSuccessHandler(HttpResponseDecorator, Object)
     * @see #defaultFailureHandler(HttpResponseDecorator)
     * @param args see {@link RequestConfigDelegate#setPropertiesFromMap(Map)}
     * @return whatever was returned from the response closure.
     * @throws URISyntaxException if a uri argument is given which does not
     *      represent a valid URI
     * @throws IOException
     * @throws ClientProtocolException
     */
    public Object get( Map<String,?> args )
            throws ClientProtocolException, IOException, URISyntaxException {
        return this.get( args, null );
    }

    /**
     * <p>Convenience method to perform an HTTP GET.  The response closure will
     * be called only on a successful response.  </p>
     *
     * <p>A 'failed' response (i.e. any HTTP status code > 399) will be handled
     * by the registered 'failure' handler.  The
     * {@link #defaultFailureHandler(HttpResponseDecorator) default failure handler}
     * throws an {@link HttpResponseException}.</p>
     *
     * @param args see {@link RequestConfigDelegate#setPropertiesFromMap(Map)}
     * @param responseClosure code to handle a successful HTTP response
     * @return any value returned by the response closure.
     * @throws ClientProtocolException
     * @throws IOException
     * @throws URISyntaxException if a uri argument is given which does not
     *      represent a valid URI
     */
    public Object get( Map<String,?> args, Closure responseClosure )
            throws ClientProtocolException, IOException, URISyntaxException {
        RequestConfigDelegate delegate = new RequestConfigDelegate( new HttpGet(),
                this.defaultContentType,
                this.defaultRequestHeaders,
                this.defaultResponseHandlers );

        delegate.setPropertiesFromMap( args );
        if ( responseClosure != null ) delegate.getResponse().put(
                Status.SUCCESS, responseClosure );
        return this.doRequest( delegate );
    }

    /**
     * <p>Convenience method to perform an HTTP POST.  It will use the HTTPBuilder's
     * {@link #getHandler() registered response handlers} to handle success or
     * failure status codes.  By default, the <code>success</code> response
     * handler will attempt to parse the data and simply return the parsed
     * object. </p>
     *
     * <p><strong>Note:</strong> If using the {@link #defaultSuccessHandler(HttpResponseDecorator, Object)
     * default <code>success</code> response handler}, be sure to read the
     * caveat regarding streaming response data.</p>
     *
     * @see #getHandler()
     * @see #defaultSuccessHandler(HttpResponseDecorator, Object)
     * @see #defaultFailureHandler(HttpResponseDecorator)
     * @param args see {@link RequestConfigDelegate#setPropertiesFromMap(Map)}
     * @return whatever was returned from the response closure.
     * @throws IOException
     * @throws URISyntaxException if a uri argument is given which does not
     *      represent a valid URI
     * @throws ClientProtocolException
     */
    public Object post( Map<String,?> args )
            throws ClientProtocolException, URISyntaxException, IOException {
        return this.post( args, null );
    }

    /** <p>
     * Convenience method to perform an HTTP form POST.  The response closure will be
     * called only on a successful response.</p>
     *
     * <p>A 'failed' response (i.e. any
     * HTTP status code > 399) will be handled by the registered 'failure'
     * handler.  The {@link #defaultFailureHandler(HttpResponseDecorator) default
     * failure handler} throws an {@link HttpResponseException}.</p>
     *
     * <p>The request body (specified by a <code>body</code> named parameter)
     * will be converted to a url-encoded form string unless a different
     * <code>requestContentType</code> named parameter is passed to this method.
     *  (See {@link EncoderRegistry#encodeForm(Map)}.) </p>
     *
     * @param args see {@link RequestConfigDelegate#setPropertiesFromMap(Map)}
     * @param responseClosure code to handle a successful HTTP response
     * @return any value returned by the response closure.
     * @throws ClientProtocolException
     * @throws IOException
     * @throws URISyntaxException if a uri argument is given which does not
     *      represent a valid URI
     */
    public Object post( Map<String,?> args, Closure responseClosure )
            throws URISyntaxException, ClientProtocolException, IOException {
        RequestConfigDelegate delegate = new RequestConfigDelegate( new HttpPost(),
                this.defaultContentType,
                this.defaultRequestHeaders,
                this.defaultResponseHandlers );

        /* by default assume the request body will be URLEncoded, but allow
           the 'requestContentType' named argument to override this if it is
           given */
        delegate.setRequestContentType( ContentType.URLENC.toString() );
        delegate.setPropertiesFromMap( args );

        if ( responseClosure != null ) delegate.getResponse().put(
                Status.SUCCESS.toString(), responseClosure );

        return this.doRequest( delegate );
    }

    /**
     * Make an HTTP request to the default URI, and parse using the default
     * content-type.
     * @see #request(Object, Method, Object, Closure)
     * @param method {@link Method HTTP method}
     * @param configClosure request configuration options
     * @return whatever value was returned by the executed response handler.
     * @throws ClientProtocolException
     * @throws IOException
     */
    public Object request( Method method, Closure configClosure ) throws ClientProtocolException, IOException {
        return this.doRequest( this.defaultURI.toURI(), method,
                this.defaultContentType, configClosure );
    }

    /**
     * Make an HTTP request using the default URI, with the given method,
     * content-type, and configuration.
     * @see #request(Object, Method, Object, Closure)
     * @param method {@link Method HTTP method}
     * @param contentType either a {@link ContentType} or valid content-type string.
     * @param configClosure request configuration options
     * @return whatever value was returned by the executed response handler.
     * @throws ClientProtocolException
     * @throws IOException
     */
    public Object request( Method method, Object contentType, Closure configClosure )
            throws ClientProtocolException, IOException {
        return this.doRequest( this.defaultURI.toURI(), method,
                contentType, configClosure );
    }

    /**
     * Make a request for the given HTTP method and content-type, with
     * additional options configured in the <code>configClosure</code>.  See
     * {@link RequestConfigDelegate} for options.
     * @param uri either a {@link URL}, {@link URI} or object whose
     *  <code>toString()</code> produces a valid URI string.  See
     *  {@link URIBuilder#convertToURI(Object)}.
     * @param method {@link Method HTTP method}
     * @param contentType either a {@link ContentType} or valid content-type string.
     * @param configClosure closure from which to configure options like
     *   {@link RequestConfigDelegate#getUri() uri.path},
     *   {@link URIBuilder#setQuery(Map) request parameters},
     *   {@link RequestConfigDelegate#setHeaders(Map) headers},
     *   {@link RequestConfigDelegate#setBody(Object) request body} and
     *   {@link RequestConfigDelegate#getResponse() response handlers}.
     *
     * @return whatever value was returned by the executed response handler.
     * @throws ClientProtocolException
     * @throws IOException
     * @throws URISyntaxException if the uri argument does not represent a valid URI
     */
    public Object request( Object uri, Method method, Object contentType, Closure configClosure )
            throws ClientProtocolException, IOException, URISyntaxException {
        return this.doRequest( convertToURI( uri ), method, contentType, configClosure );
    }

    /**
     * Create a {@link RequestConfigDelegate} from the given arguments, execute the
     * config closure, then pass the delegate to {@link #doRequest(RequestConfigDelegate)},
     * which actually executes the request.
     */
    protected Object doRequest( URI uri, Method method, Object contentType, Closure configClosure )
            throws ClientProtocolException, IOException {

        HttpRequestBase reqMethod;
        try { reqMethod = method.getRequestType().newInstance();
        // this exception should reasonably never occur:
        } catch ( Exception e ) { throw new RuntimeException( e ); }

        reqMethod.setURI( uri );
        RequestConfigDelegate delegate = new RequestConfigDelegate( reqMethod, contentType,
                this.defaultRequestHeaders,
                this.defaultResponseHandlers );
        configClosure.setDelegate( delegate );
        configClosure.setResolveStrategy( Closure.DELEGATE_FIRST );
        configClosure.call( reqMethod );

        return this.doRequest( delegate );
    }

    /**
     * All <code>request</code> methods delegate to this method.
     */
    protected Object doRequest( final RequestConfigDelegate delegate )
            throws ClientProtocolException, IOException {
        delegate.encodeBody();
        final HttpRequestBase reqMethod = delegate.getRequest();

        final Object contentType = delegate.getContentType();

        if ( this.autoAcceptHeader ) {
            String acceptContentTypes = contentType.toString();
            if ( contentType instanceof ContentType )
                acceptContentTypes = ((ContentType)contentType).getAcceptHeader();
            reqMethod.setHeader( "Accept", acceptContentTypes );
        }

        reqMethod.setURI( delegate.getUri().toURI() );
        if ( reqMethod.getURI() == null)
            throw new IllegalStateException( "Request URI cannot be null" );

        log.debug( reqMethod.getMethod() + " " + reqMethod.getURI() );

        // set any request headers from the delegate
        Map<?,?> headers = delegate.getHeaders();
        for ( Object key : headers.keySet() ) {
            Object val = headers.get( key );
            if ( key == null ) continue;
            if ( val == null ) reqMethod.removeHeaders( key.toString() );
            else reqMethod.setHeader( key.toString(), val.toString() );
        }

        ResponseHandler<Object> responseHandler = new ResponseHandler<Object>() {
            public Object handleResponse(HttpResponse response)
                throws ClientProtocolException, IOException {
                HttpResponseDecorator resp = new HttpResponseDecorator(
                        response, delegate.getContext(), null );
                try {
                    int status = resp.getStatusLine().getStatusCode();
                    Closure responseClosure = delegate.findResponseHandler( status );
                    log.debug( "Response code: " + status + "; found handler: " + responseClosure );

                    Object[] closureArgs = null;
                    switch ( responseClosure.getMaximumNumberOfParameters() ) {
                    case 1 :
                        closureArgs = new Object[] { resp };
                        break;
                    case 2 : // parse the response entity if the response handler expects it:
                        HttpEntity entity = resp.getEntity();
                        try {
                            if ( entity == null || entity.getContentLength() == 0 )
                                closureArgs = new Object[] { resp, null };
                            else closureArgs = new Object[] { resp, parseResponse( resp, contentType ) };
                        }
                        catch ( Exception ex ) {
                            Header h = entity.getContentType();
                            String respContentType = h != null ? h.getValue() : null;
                            log.warn( "Error parsing '" + respContentType + "' response", ex );
                            throw new ResponseParseException( resp, ex );
                        }
                        break;
                    default:
                        throw new IllegalArgumentException(
                                "Response closure must accept one or two parameters" );
                    }

                    Object returnVal = responseClosure.call( closureArgs );
                    log.trace( "response handler result: " + returnVal );

                    return returnVal;
                }
                finally {
                    HttpEntity entity = resp.getEntity();
                    if ( entity != null ) entity.consumeContent();
                }
            }
        };

        return getClient().execute(reqMethod, responseHandler, delegate.getContext());
    }

    /**
     * Parse the response data based on the given content-type.
     * If the given content-type is {@link ContentType#ANY}, the
     * <code>content-type</code> header from the response will be used to
     * determine how to parse the response.
     * @param resp
     * @param contentType
     * @return whatever was returned from the parser retrieved for the given
     *  content-type, or <code>null</code> if no parser could be found for this
     *  content-type.  The parser will also return <code>null</code> if the
     *  response does not contain any content (e.g. in response to a HEAD request).
     * @throws HttpResponseException if there is a error parsing the response
     */
    protected Object parseResponse( HttpResponse resp, Object contentType )
            throws HttpResponseException {
        // For HEAD or OPTIONS requests, there should be no response entity.
        if ( resp.getEntity() == null ) {
            log.debug( "Response contains no entity.  Parsed data is null." );
            return null;
        }
        // first, start with the _given_ content-type
        String responseContentType = contentType.toString();
        // if the given content-type is ANY ("*/*") then use the response content-type
        try {
            if ( ContentType.ANY.toString().equals( responseContentType ) )
                responseContentType = ParserRegistry.getContentType( resp );
        }
        catch ( RuntimeException ex ) {
            log.warn( "Could not parse content-type: " + ex.getMessage() );
            /* if for whatever reason we can't determine the content-type, but
             * still want to attempt to parse the data, use the BINARY
             * content-type so that the response will be buffered into a
             * ByteArrayInputStream. */
            responseContentType = ContentType.BINARY.toString();
        }

        Object parsedData = null;
        Closure parser = parsers.getAt( responseContentType );
        if ( parser == null ) log.warn( "No parser found for content-type: "
            + responseContentType );
        else {
            log.debug( "Parsing response as: " + responseContentType );
            parsedData = parser.call( resp );
            if ( parsedData == null ) log.warn( "Parser returned null!" );
            else log.debug( "Parsed data to instance of: " + parsedData.getClass() );
        }
        return parsedData;
    }

    /**
     * Creates default response handlers for {@link Status#SUCCESS success} and
     * {@link Status#FAILURE failure} status codes.  This is used to populate
     * the handler map when a new HTTPBuilder instance is created.
     * @see #defaultSuccessHandler(HttpResponseDecorator, Object)
     * @see #defaultFailureHandler(HttpResponseDecorator)
     * @return the default response handler map.
     */
    protected Map<Object,Closure> buildDefaultResponseHandlers() {
        Map<Object,Closure> map = new StringHashMap<Closure>();
        map.put( Status.SUCCESS,
                new MethodClosure(this,"defaultSuccessHandler"));
        map.put(  Status.FAILURE,
                new MethodClosure(this,"defaultFailureHandler"));

        return map;
    }

    /**
     * <p>This is the default <code>response.success</code> handler.  It will be
     * executed if the response is not handled by a status-code-specific handler
     * (i.e. <code>response.'200'= {..}</code>) and no generic 'success' handler
     * is given (i.e. <code>response.success = {..}</code>.)  This handler simply
     * returns the parsed data from the response body.  In most cases you will
     * probably want to define a <code>response.success = {...}</code> handler
     * from the request closure, which will replace the response handler defined
     * by this method.  </p>
     *
     * <h4>Note for parsers that return streaming content:</h4>
     * <p>For responses parsed as {@link ParserRegistry#parseStream(HttpResponse)
     * BINARY} or {@link ParserRegistry#parseText(HttpResponse) TEXT}, the
     * parser will return streaming content -- an <code>InputStream</code> or
     * <code>Reader</code>.  In these cases, this handler will buffer the the
     * response content before the network connection is closed.  </p>
     *
     * <p>In practice, a user-supplied response handler closure is
     * <i>designed</i> to handle streaming content so it can be read directly from
     * the response stream without buffering, which will be much more efficient.
     * Therefore, it is recommended that request method variants be used which
     * explicitly accept a response handler closure in these cases.</p>
     *
     * @param resp HTTP response
     * @param parsedData parsed data as resolved from this instance's {@link ParserRegistry}
     * @return the parsed data object (whatever the parser returns).
     * @throws ResponseParseException if there is an error buffering a streaming
     *   response.
     */
    protected Object defaultSuccessHandler( HttpResponseDecorator resp, Object parsedData )
            throws ResponseParseException {
        try {
            //If response is streaming, buffer it in a byte array:
            if ( parsedData instanceof InputStream ) {
                ByteArrayOutputStream buffer = new ByteArrayOutputStream();
                DefaultGroovyMethods.leftShift( buffer, (InputStream)parsedData );
                parsedData = new ByteArrayInputStream( buffer.toByteArray() );
            }
            else if ( parsedData instanceof Reader ) {
                StringWriter buffer = new StringWriter();
                DefaultGroovyMethods.leftShift( buffer, (Reader)parsedData );
                parsedData = new StringReader( buffer.toString() );
            }
            else if ( parsedData instanceof Closeable )
                log.warn( "Parsed data is streaming, but will be accessible after " +
                        "the network connection is closed.  Use at your own risk!" );
            return parsedData;
        }
        catch ( IOException ex ) {
            throw new ResponseParseException( resp, ex );
        }
    }

    /**
     * This is the default <code>response.failure</code> handler.  It will be
     * executed if no status-code-specific handler is set (i.e.
     * <code>response.'404'= {..}</code>).  This default handler will throw a
     * {@link HttpResponseException} when executed.  In most cases you
     * will want to define your own <code>response.failure = {...}</code>
     * handler from the request closure, if you don't want an exception to be
     * thrown for 4xx and 5xx status responses.

     * @param resp
     * @throws HttpResponseException
     */
    protected void defaultFailureHandler( HttpResponseDecorator resp ) throws HttpResponseException {
        throw new HttpResponseException( resp );
    }

    /**
     * Retrieve the map of response code handlers.  Each map key is a response
     * code as a string (i.e. '401') or either 'success' or 'failure'.  Use this
     * to set default response handlers, e.g.
     * <pre>builder.handler.'401' = { resp -> println "${resp.statusLine}" }</pre>
     * @see Status
     * @return
     */
    public Map<?,Closure> getHandler() {
        return this.defaultResponseHandlers;
    }

    /**
     * Retrieve the map of registered response content-type parsers.  Use
     * this to set default response parsers, e.g.
     * <pre>
     * builder.parser.'text/javascript' = { resp ->
     *    return resp.entity.content // just returns an InputStream
     * }</pre>
     * @return
     */
    public ParserRegistry getParser() {
        return this.parsers;
    }

    /**
     * Retrieve the map of registered request content-type encoders.  Use this
     * to customize a request encoder for specific content-types, e.g.
     * <pre>
     * builder.encoder.'text/javascript' = { body ->
     *   def json = body.call( new JsonGroovyBuilder() )
     *   return new StringEntity( json.toString() )
     * }</pre>
     * By default this map is populated by calling
     * {@link EncoderRegistry#buildDefaultEncoderMap()}.  This method is also
     * used by {@link RequestConfigDelegate} to retrieve the proper encoder for building
     * the request content body.
     *
     * @return a map of 'encoder' closures, keyed by content-type string.
     */
    public EncoderRegistry getEncoder() {
        return this.encoders;
    }

    /**
     * Set the default content type that will be used to select the appropriate
     * request encoder and response parser.  The {@link ContentType} enum holds
     * some common content-types that may be used, i.e. <pre>
     * import static ContentType.*
     * builder.contentType = XML
     * </pre>
     * Setting the default content-type does three things:
     * <ol>
     *   <li>It tells the builder to encode any {@link RequestConfigDelegate#setBody(Object)
     *   request body} as this content-type.  Calling {@link
     *   RequestConfigDelegate#setRequestContentType(String)} can override this
     *   on a per-request basis.</li>
     *   <li>Tells the builder to parse any response as this content-type,
     *   regardless of any <code>content-type</code> header that is sent in the
     *   response.</li>
     *   <li>Sets the <code>Accept</code> header to this content-type for all
     *   requests (see {@link ContentType#getAcceptHeader()}).  Note
     *   that any <code>Accept</code> header explicitly set either in
     *   {@link #setHeaders(Map)} or {@link RequestConfigDelegate#setHeaders(Map)}
     *   will override this value.</li>
     * </ol>
     * <p>Additionally, if the content-type is set to {@link ContentType#ANY},
     * HTTPBuilder <i>will</i> rely on the <code>content-type</code> response
     * header to determine how to parse the response data.  This allows the user
     * to rely on response headers if they are accurate, or ignore them and
     * forcibly use a certain response parser if so desired.</p>
     *
     * <p>This value is a default and may always be overridden on a per-request
     * basis by using the {@link #request(Method, Object, Closure)
     * builder.request( Method, ContentType, Closure )} method or passing a
     * <code>contentType</code> named parameter.
     * @see EncoderRegistry
     * @see ParserRegistry
     * @param ct either a {@link ContentType} or string value (i.e. <code>"text/xml"</code>.)
     */
    public void setContentType( Object ct ) {
        this.defaultContentType = ct;
    }

    /**
     * @return default content type used for request and response.
     */
    public Object getContentType() {
        return this.defaultContentType;
    }

    /**
     * Indicate whether or not this cliernt should send an <code>Accept</code>
     * header automatically based on the {@link #getContentType() contentType}
     * property.
     * @param shouldSendAcceptHeader <code>true</code> if the client should
     * automatically insert an <code>Accept</code> header, otherwise <code>false</code>.
     */
    public void setAutoAcceptHeader( boolean shouldSendAcceptHeader ) {
        this.autoAcceptHeader = shouldSendAcceptHeader;
    }

    /**
     * Indicates whether or not this client should automatically send an
     * <code>Accept</code> header based on the {@link #getContentType() contentType}
     * property.  Default is <code>true</code>.
     * @return <code>true</code> if the client should automatically add an
     * <code>Accept</code> header to the request; if <code>false</code>, no
     * header is added.
     */
    public boolean isAutoAcceptHeader() {
        return this.autoAcceptHeader;
    }

    /**
     * Set acceptable request and response content-encodings.
     * @see ContentEncodingRegistry
     * @param encodings each Object should be either a
     * {@link ContentEncoding.Type} value, or a <code>content-encoding</code>
     * string that is known by the {@link ContentEncodingRegistry}
     */
    public void setContentEncoding( Object... encodings ) {
                HttpClient client = getClient();
                if ( client instanceof AbstractHttpClient ) {
          this.contentEncodingHandler.setInterceptors( (AbstractHttpClient)client, encodings );
                } else {
                  throw new IllegalStateException("The HttpClient is not an AbstractHttpClient!");
                }

    }

    /**
     * Set the default URI used for requests that do not explicitly take a
     * <code>uri</code> param.
     * @param uri either a {@link URL}, {@link URI} or object whose
     *  <code>toString()</code> produces a valid URI string.  See
     *  {@link URIBuilder#convertToURI(Object)}.
     * @throws URISyntaxException if the uri argument does not represent a valid URI
     */
    public void setUri( Object uri ) throws URISyntaxException {
        this.defaultURI = uri != null ? new URIBuilder( convertToURI( uri ) ) : null;
    }

    /**
     * Get the default URI used for requests that do not explicitly take a
     * <code>uri</code> param.
     * @return a {@link URIBuilder} instance.  Note that the return type is Object
     * simply so that it matches with its JavaBean {@link #setUri(Object)}
     * counterpart.
     */
    public Object getUri() {
        return defaultURI;
    }

    /**
     * Set the default headers to add to all requests made by this builder
     * instance.  These values will replace any previously set default headers.
     * @param headers map of header names & values.
     */
    public void setHeaders( Map<?,?> headers ) {
        this.defaultRequestHeaders.clear();
        if ( headers == null ) return;
        for( Object key : headers.keySet() ) {
            Object val = headers.get( key );
            if ( val == null ) continue;
            this.defaultRequestHeaders.put( key.toString(), val.toString() );
        }
    }

    /**
     * Get the map of default headers that will be added to all requests.
     * This is a 'live' collection so it may be used to add or remove default
     * values.
     * @return the map of default header names and values.
     */
    public Map<?,?> getHeaders() {
        return this.defaultRequestHeaders;
    }

    /**
     * Return the underlying HTTPClient that is used to handle HTTP requests.
     * @return the client instance.
     */
    public HttpClient getClient() {
        if (client == null) {
            HttpParams defaultParams = new BasicHttpParams();
            defaultParams.setParameter( CookieSpecPNames.DATE_PATTERNS,
                    Arrays.asList("EEE, dd-MMM-yyyy HH:mm:ss z", "EEE, dd MMM yyyy HH:mm:ss z") );
            client = createClient(defaultParams);
        }
        return client;
    }

    public void setClient(HttpClient client) {
        this.client = client;
    }

    /**
     * Override this method in a subclass to customize creation of the
     * HttpClient instance.
     * @param params
     * @return
     */
    protected HttpClient createClient( HttpParams params ) {
        return new DefaultHttpClient(params);
    }

    /**
     * Used to access the {@link AuthConfig} handler used to configure common
     * authentication mechanism.  Example:
     * <pre>builder.auth.basic( 'myUser', 'somePassword' )</pre>
     * @return
     */
    public AuthConfig getAuth() { return this.auth; }

    /**
     * Set an alternative {@link AuthConfig} implementation to handle
     * authorization.
     * @param ac instance to use.
     */
    public void setAuthConfig( AuthConfig ac ) {
        this.auth = ac;
    }

    /**
     * Set a custom registry used to handle different request
     * <code>content-type</code>s.
     * @param er
     */
    public void setEncoderRegistry( EncoderRegistry er ) {
        this.encoders = er;
    }

    /**
     * Set a custom registry used to handle different response
     * <code>content-type</code>s
     * @param pr
     */
    public void setParserRegistry( ParserRegistry pr ) {
        this.parsers = pr;
    }

    /**
     * Set a custom registry used to handle different
     * <code>content-encoding</code> types in responses.
     * @param cer
     */
    public void setContentEncodingRegistry( ContentEncodingRegistry cer ) {
        this.contentEncodingHandler = cer;
    }

    /**
     * Set the default HTTP proxy to be used for all requests.
     * @see HttpHost#HttpHost(String, int, String)
     * @param host host name or IP
     * @param port port, or -1 for the default port
     * @param scheme usually "http" or "https," or <code>null</code> for the default
     */
    public void setProxy( String host, int port, String scheme ) {
        getClient().getParams().setParameter(
                ConnRoutePNames.DEFAULT_PROXY,
                new HttpHost(host,port,scheme) );
    }

    /**
     * Release any system resources held by this instance.
     * @see ClientConnectionManager#shutdown()
     */
    public void shutdown() {
        getClient().getConnectionManager().shutdown();
    }



    /**
     * <p>Encloses all properties and method calls used within the
     * {@link HTTPBuilder#request(Object, Method, Object, Closure)} 'config'
     * closure argument.  That is, an instance of this class is set as the
     * closure's delegate.  This allows the user to configure various parameters
     * within the scope of a single request.  </p>
     *
     * <p>All properties of this class are available from within the closure.
     * For example, you can manipulate various aspects of the
     * {@link HTTPBuilder#setUri(Object) default request URI} for this request
     * by calling <code>uri.path = '/api/location'</code>.  This allows for the
     * ability to modify parameters per-request while leaving any values set
     * directly on the HTTPBuilder instance unchanged for subsequent requests.
     * </p>
     *
     */
    protected class RequestConfigDelegate {
        private HttpRequestBase request;
        private Object contentType;
        private Object requestContentType;
        private Map<Object,Closure> responseHandlers = new StringHashMap<Closure>();
        private URIBuilder uri;
        private Map<Object,Object> headers = new StringHashMap<Object>();
        private HttpContextDecorator context = new HttpContextDecorator();
        private Object body;

        public RequestConfigDelegate( HttpRequestBase request, Object contentType,
                Map<?,?> defaultRequestHeaders,
                Map<?,Closure> defaultResponseHandlers ) {
            if ( request == null ) throw new IllegalArgumentException(
                    "Internal error - HttpRequest instance cannot be null" );
            this.request = request;
            this.headers.putAll( defaultRequestHeaders );
            this.contentType = contentType;
            if ( defaultRequestContentType != null )
                this.requestContentType = defaultRequestContentType.toString();
            this.responseHandlers.putAll( defaultResponseHandlers );
            URI uri = request.getURI();
            if ( uri != null ) this.uri = new URIBuilder(uri);
        }

        public RequestConfigDelegate( Map<String,?> args, HttpRequestBase request, Closure successHandler )
                throws URISyntaxException {
            this( request, defaultContentType, defaultRequestHeaders, defaultResponseHandlers );
            if ( successHandler != null )
                this.responseHandlers.put( Status.SUCCESS.toString(), successHandler );
            setPropertiesFromMap( args );
        }

        /**
         * Use this object to manipulate parts of the request URI, like
         * query params and request path.  Example:
         * <pre>
         * builder.request(GET,XML) {
         *   uri.path = '../other/request.jsp'
         *   uri.query = [p1:1, p2:2]
         *   ...
         * }</pre>
         *
         * <p>This method signature returns <code>Object</code> so that the
         * complementary {@link #setUri(Object)} method can accept various
         * types. </p>
         * @return {@link URIBuilder} to manipulate the request URI
         */
        public URIBuilder getUri() { return this.uri; }

        /**
         * <p>Set the entire URI to be used for this request.  Acceptable
         * parameter types are:
         * <ul>
         *   <li><code>URL</code></li>
         *   <li><code>URI</code></li>
         *   <li><code>URIBuilder</code></li>
         * </ul>
         * Any other parameter type will be assumed that its
         * <code>toString()</code> method produces a valid URI.</p>
         *
         * <p>Note that if you want to change just a portion of the request URI,
         * (e.g. the host, port, path, etc.) you can call {@link #getUri()}
         * which will return a {@link URIBuilder} which can manipulate portions
         * of the request URI.</p>
         *
         * @see URIBuilder#convertToURI(Object)
         * @throws URISyntaxException if an argument is given that is not a valid URI
         * @param uri the URI to use for this request.
         */
        public void setUri( Object uri ) throws URISyntaxException {
            if ( uri instanceof URIBuilder ) this.uri = (URIBuilder)uri;
            this.uri = new URIBuilder( convertToURI( uri ) );
        }

        /**
         * Directly access the Apache HttpClient instance that will
         * be used to execute this request.
         * @see HttpRequestBase
         */
        protected HttpRequestBase getRequest() { return this.request; }

        /**
         * Get the content-type of any data sent in the request body and the
         * expected response content-type.  If the request content-type is
         * expected to differ from the response content-type (i.e. a URL-encoded
         * POST that should return an HTML page) then this value will be used
         * for the <i>response</i> content-type, while
         * {@link #setRequestContentType(String)} should be used for the request.
         *
         * @return whatever value was assigned via {@link #setContentType(Object)}
         * or passed from the {@link HTTPBuilder#defaultContentType} when this
         * RequestConfigDelegate instance was constructed.
         */
        protected Object getContentType() { return this.contentType; }

        /**
         * Set the content-type used for any data in the request body, as well
         * as the <code>Accept</code> content-type that will be used for parsing
         * the response. The value should be either a {@link ContentType} value
         * or a String, i.e. <code>"text/plain"</code>.  This will default to
         * {@link HTTPBuilder#getContentType()} for requests that do not
         * explicitly pass a <code>contentType</code> parameter (such as
         * {@link HTTPBuilder#request(Method, Object, Closure)}).
         * @param ct the value that will be used for the <code>Content-Type</code>
         * and <code>Accept</code> request headers.
         */
        protected void setContentType( Object ct ) {
            if ( ct == null ) this.contentType = defaultContentType;
            else this.contentType = ct;
        }

        /**
         * The request content-type, if different from the {@link #contentType}.
         * @return either a {@link ContentType} value or String like <code>text/plain</code>
         */
        protected Object getRequestContentType() {
            if ( this.requestContentType != null ) return this.requestContentType;
            else return this.getContentType();
        }

        /**
         * <p>Assign a different content-type for the request than is expected for
         * the response.  This is useful if i.e. you want to post URL-encoded
         * form data but expect the response to be XML or HTML.  The
         * {@link #getContentType()} will always control the <code>Accept</code>
         * header, and will be used for the request content <i>unless</i> this
         * value is also explicitly set.</p>
         * <p>Note that this method is used internally; calls within a request
         * configuration closure should call {@link #send(Object, Object)}
         * to set the request body and content-type at the same time.</p>
         * @param ct either a {@link ContentType} value or a valid content-type
         * String.
         */
        protected void setRequestContentType( Object ct ) {
            this.requestContentType = ct;
        }

        /**
         * Valid arguments:
         * <dl>
         *   <dt>uri</dt><dd>Either a URI, URL, or object whose
         *      <code>toString()</code> method produces a valid URI string.
         *      If this parameter is not supplied, the HTTPBuilder's default
         *      URI is used.</dd>
         *   <dt>path</dt><dd>Request path that is merged with the URI</dd>
         *   <dt>queryString</dt><dd>an escaped query string</dd>
         *   <dt>query</dt><dd>Map of URL query parameters</dd>
         *   <dt>headers</dt><dd>Map of HTTP headers</dd>
         *   <dt>contentType</dt><dd>Request content type and Accept header.
         *      If not supplied, the HTTPBuilder's default content-type is used.</dd>
         *   <dt>requestContentType</dt><dd>content type for the request, if it
         *      is different from the expected response content-type</dd>
         *   <dt>body</dt><dd>Request body that will be encoded based on the given contentType</dd>
         * </dl>
         * Note that if both <code>queryString</code> and <code>query</code> are given,
         * <code>query</code> will be merged with (and potentially override)
         * the parameters given as part of <code>queryString</code>.
         * @param args named parameters to set properties on this delegate.
         * @throws URISyntaxException if the uri argument does not represent a valid URI
         */
        @SuppressWarnings("unchecked")
        protected void setPropertiesFromMap( Map<String,?> args ) throws URISyntaxException {
            if ( args == null ) return;
            if ( args.containsKey( "url" ) ) throw new IllegalArgumentException(
                    "The 'url' parameter is deprecated; use 'uri' instead" );
            Object uri = args.remove( "uri" );
            if ( uri == null ) uri = defaultURI;
            if ( uri == null ) throw new IllegalStateException(
                    "Default URI is null, and no 'uri' parameter was given" );
            this.uri = new URIBuilder( convertToURI( uri ) );

            Map query = (Map)args.remove( "params" );
            if ( query != null ) {
                log.warn( "'params' argument is deprecated; use 'query' instead." );
                this.uri.setQuery( query );
            }
            String queryString = (String)args.remove("queryString");
            if ( queryString != null ) this.uri.setRawQuery(queryString);

            query = (Map)args.remove( "query" );
            if ( query != null ) this.uri.addQueryParams( query );
            Map headers = (Map)args.remove( "headers" );
            if ( headers != null ) this.getHeaders().putAll( headers );

            Object path = args.remove( "path" );
            if ( path != null ) this.uri.setPath( path.toString() );

            Object contentType = args.remove( "contentType" );
            if ( contentType != null ) this.setContentType( contentType );

            contentType = args.remove( "requestContentType" );
            if ( contentType != null ) this.setRequestContentType( contentType );

            Object body = args.remove("body");
            if ( body != null ) this.setBody( body );

            if ( args.size() > 0 ) {
                String invalidArgs = "";
                for ( String k : args.keySet() ) invalidArgs += k + ",";
                throw new IllegalArgumentException("Unexpected keyword args: " + invalidArgs);
            }
        }

        /**
         * Set request headers.  These values will be <strong>merged</strong>
         * with any {@link HTTPBuilder#getHeaders() default request headers.}
         * (The assumption is you'll probably want to add a bunch of headers to
         * whatever defaults you've already set).  If you <i>only</i> want to
         * use values set here, simply call {@link #getHeaders() headers.clear()}
         * first.
         */
        public void setHeaders( Map<?,?> newHeaders ) {
            this.headers.putAll( newHeaders );
        }

        /**
         * <p>Get request headers (including any default headers set on this
         * {@link HTTPBuilder#setHeaders(Map) HTTPBuilder instance}).  Note that
         * this will not include any <code>Accept</code>, <code>Content-Type</code>,
         * or <code>Content-Encoding</code> headers that are automatically
         * handled by any encoder or parsers in effect.  Note that any values
         * set here <i>will</i> override any of those automatically assigned
         * values.</p>
         *
         * <p>Example: <code>headers.'Accept-Language' = 'en, en-gb;q=0.8'</code></p>
         * @return a map of HTTP headers that will be sent in the request.
         */
        public Map<?,?> getHeaders() {
            return this.headers;
        }

        /**
         * Convenience method to set a request content-type at the same time
         * the request body is set.  This is a variation of
         * {@link #setBody(Object)} that allows for a different content-type
         * than what is expected for the response.
         *
         * <p>Example:
         * <pre>
         * http.request(POST,HTML) {
         *
         *   /* request data is interpreted as a JsonBuilder closure by
         *      HTTPBuilder's default EncoderRegistry implementation * /
         *   send( 'text/javascript' ) {
         *     a : ['one','two','three']
         *   }
         *
         *   // response content-type is what was specified in the outer request() argument:
         *   response.success = { resp, html ->
         *
         *   }
         * }
         * </pre>
         * The <code>send</code> call is equivalent to the following:
         * <pre>
         *   requestContentType = 'text/javascript'
         *   body = { a : ['one','two','three'] }
         * </pre>
         *
         * @param contentType either a {@link ContentType} or equivalent
         *   content-type string like <code>"text/xml"</code>
         * @param requestBody
         */
        public void send( Object contentType, Object requestBody ) {
            this.setRequestContentType( contentType );
            this.setBody( requestBody );
        }

        /**
         * Set the request body.  This value may be of any type supported by
         * the associated {@link EncoderRegistry request encoder}.  That is,
         * the value of <code>body</code> will be interpreted by the encoder
         * associated with the current {@link #getRequestContentType() request
         * content-type}.
         * @see #send(Object, Object)
         * @param body data or closure interpreted as the request body
         */
        public void setBody( Object body ) {
            this.body = body;
        }

        public void encodeBody() {
            if (body == null) {
                return;
            }
            if ( ! (request instanceof HttpEntityEnclosingRequest ) )
                throw new IllegalArgumentException(
                        "Cannot set a request body for a " + request.getMethod() + " method" );

            Closure encoder = encoders.getAt( this.getRequestContentType() );

            // Either content type or encoder is empty.
            if ( encoder == null )
                throw new IllegalArgumentException(
                        "No encoder found for request content type " + getRequestContentType() );

            HttpEntity entity = encoder.getMaximumNumberOfParameters() == 2
                    ? (HttpEntity)encoder.call( new Object[] { body, this.getRequestContentType() } )
                    : (HttpEntity)encoder.call( body );

            ((HttpEntityEnclosingRequest)this.request).setEntity( entity );
        }

        /**
         * Get the proper response handler for the response code.  This is called
         * by the {@link HTTPBuilder} class in order to find the proper handler
         * based on the response status code.
         *
         * @param statusCode HTTP response status code
         * @return the response handler
         */
        protected Closure findResponseHandler( int statusCode ) {
            Closure handler = this.getResponse().get( Integer.toString( statusCode ) );
            if ( handler == null ) handler =
                this.getResponse().get( Status.find( statusCode ).toString() );
            return handler;
        }

        /**
         * Access the response handler map to set response parsing logic.
         * i.e.<pre>
         * builder.request( GET, XML ) {
         *   response.success = { xml ->
         *      /* for XML content type, the default parser
         *         will return an XmlSlurper * /
         *      xml.root.children().each { println it }
         *   }
         * }</pre>
         * @return
         */
        public Map<Object,Closure> getResponse() { return this.responseHandlers; }

        /**
         * Get the {@link HttpContext} that will be used for this request.  By
         * default, a new context is created for each request.
         * @see ClientContext
         * @return
         */
        public HttpContextDecorator getContext() { return this.context; }

        /**
         * Set the {@link HttpContext} that will be used for this request.
         * @param ctx
         */
        public void setContext( HttpContext ctx ) { this.context = new HttpContextDecorator(ctx); }
    }
}