com.threewks.thundr.http.service.HttpRequest Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of thundr-http Show documentation
Provides an API for http connectivity functionality for thundr projects.
There is a newer version: 3.0.0
/*
 * This file is a component of thundr, a software library from 3wks.
 * Read more: http://3wks.github.io/thundr/
 * Copyright (C) 2015 3wks, 
 *
 * 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.threewks.thundr.http.service;

import java.net.HttpCookie;
import java.util.Collection;
import java.util.Map;

import com.threewks.thundr.http.ContentType;

public interface HttpRequest {
	/**
	 * Returns a new request with the which will follow redirects when executed as given
	 */
	public HttpRequest followRedirects(boolean value);

	/**
	 * Returns a new request with the timeout as given
	 * 
	 * @param millis
	 * @return
	 */
	public HttpRequest timeout(long millis);

	/**
	 * Returns a new request with the body as given
	 * 
	 * @param body
	 * @return
	 */
	public HttpRequest body(Object body);

	/**
	 * Returns a new request with the given header added
	 * 
	 * @param name
	 * @param value
	 * @return
	 */
	public HttpRequest header(String name, String value);

	/**
	 * Returns a new request with the given headers added
	 * 
	 * @param headers
	 * @return
	 */
	public HttpRequest headers(Map headers);

	/**
	 * Returns a new request with the given parameter added
	 * 
	 * GET: parameters are passed as a query string
	 * POST: parameters are passed in the body
	 * PUT: parameters are passed in the body
	 * DELETE: parameters are passed as a query string
	 */
	public HttpRequest parameter(String name, String value);

	/**
	 * Returns a new request with the given parameter added
	 * 
	 * GET: parameters are passed as a query string
	 * POST: parameters are passed in the body
	 * PUT: parameters are passed in the body
	 * DELETE: parameters are passed as a query string
	 * 
	 * @param name
	 * @param value
	 * @return
	 */
	public HttpRequest parameter(String name, Object value);

	/**
	 * Returns a new request with the given parameters added
	 * 
	 * GET: parameters are passed as a query string
	 * POST: parameters are passed in the body
	 * PUT: parameters are passed in the body
	 * DELETE: parameters are passed as a query string
	 * 
	 * @param parameters
	 * @return
	 */
	public HttpRequest parameters(Map parameters);

	/**
	 * Returns a new request with the given content type
	 * 
	 * @param contentType
	 * @return
	 */
	public HttpRequest contentType(ContentType contentType);

	/**
	 * Returns a new request with the given content type
	 * 
	 * @param contentType
	 * @return
	 */
	public HttpRequest contentType(String contentType);

	/**
	 * Returns a new request with the given cookie added
	 * 
	 * @param cookie
	 * @return
	 */
	public HttpRequest cookie(HttpCookie cookie);

	/**
	 * Returns a new request with the given cookie added
	 * 
	 * @param cookie
	 * @return
	 */
	public HttpRequest cookies(Collection cookie);

	/**
	 * Execute this request as a GET
	 * 
	 * @return
	 */
	public HttpResponse get();

	/**
	 * Execute this request as a POST
	 * 
	 * @return
	 */
	public HttpResponse post();

	/**
	 * /**
	 * Execute this request as a PUT
	 * 
	 * @return
	 */
	public HttpResponse put();

	/**
	 * Execute this request as a DELETE
	 * 
	 * @return
	 */
	public HttpResponse delete();

	/**
	 * Execute this request as a HEAD
	 * 
	 * @return
	 */
	public HttpResponse head();

	/**
	 * Causes the request to be authorized using the Basic scheme and the provided credentials.
	 * 
	 * @param username
	 * @param password
	 * 
	 * @return the {@link HttpRequest} for method chaining
	 * 
	 * @throws HttpRequestException if the Basic scheme is not supported
	 */
	public HttpRequest authorize(String username, String password);

	/**
	 * Causes the request to be authorized using the given scheme and the provided credentials.
	 * 
	 * @param username
	 * @param password
	 * @param scheme
	 * 
	 * @return the {@link HttpRequest} for method chaining
	 * 
	 * @throws HttpRequestException if the given scheme is not supported
	 */
	public HttpRequest authorize(String username, String password, String scheme);

	/**
	 * Adds a file parameter to the request. This cause the request to become a multipart/form-data
	 * request and is only required to work for post and put.
	 * 
	 * @param name
	 * @param filename
	 * @param body
	 * @return
	 */
	public HttpRequest file(String name, String filename, String contentType, Object body);

	public HttpRequest file(String name, String filename, ContentType contentType, Object body);

	// Attachments and multipart not implemented
	// public HttpRequest files(FileParameter... fileParameters);
	// public HttpRequest files(List fileParameters);
}