BetterHttpRequest.java

/* Copyright (c) 2009 Matthias Kaeppler
 *
 * 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.
 */

package com.github.droidfu.http;

import java.net.ConnectException;

import org.apache.http.client.HttpResponseException;
import org.apache.http.client.methods.HttpUriRequest;

public interface BetterHttpRequest {

	/**
	 * @return the HttpClient request object wrapped by this request
	 */
	public HttpUriRequest unwrap();

	/**
	 * @return the request URL
	 */
	public String getRequestUrl();

	/**
	 * Define the set of HTTP status codes which you anticipate to be returned
	 * by the server, including error codes you'd like to explicitly handle. Any
	 * status code part of this set will not be treated as an error, but
	 * returned to you as a normal server response. Any status codes returned by
	 * the server that are <i>not</i> part of this set will be raised as an
	 * {@link HttpResponseException}. This is very useful when dealing with
	 * REST-ful Web services, where it is common to serve error stati that
	 * indicate a failure in the application logic (e.g. 404 if a resource
	 * doesn't exist). You typically don't want to treat those as connection
	 * errors, but gracefully handle them like a normal success code.
	 * 
	 * @param statusCodes
	 *            the set of status codes that you want to manually handle as
	 *            part of the response
	 * @return this request
	 */
	public BetterHttpRequest expecting(Integer... statusCodes);

	/**
	 * Set maximum number of retries for this particular request.
	 * 
	 * @param retries
	 *            the maximum number of retries should the request fail
	 * @return this request
	 */
	public BetterHttpRequest retries(int retries);

	/**
	 * Set the socket timeout for this specific request.
	 * 
	 * @param timeout
	 *            the timeout in milliseconds
	 * @return this request
	 */
	public BetterHttpRequest withTimeout(int timeout);

	/**
	 * Sends the current request. This method uses a special retry-logic (on top
	 * of that employed by HttpClient, which is better suited to handle network
	 * fail-overs when e.g. switching between Wi-Fi and 3G).
	 */
	public BetterHttpResponse send() throws ConnectException;
}