// Copyright 2008 Google Inc.
//
// 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.google.enterprise.secmgr.http;

import com.google.common.collect.ListMultimap;

import java.io.IOException;
import java.io.InputStream;
import java.net.URL;
import java.util.List;

import javax.annotation.Nonnull;
import javax.annotation.Nullable;
import javax.annotation.ParametersAreNonnullByDefault;

/**
 * An abstraction for an HTTP exchange.  @see HttpClientInterface
 */
@ParametersAreNonnullByDefault
public interface HttpExchange {

  /**
   * Sets the proxy to use for the exchange.
   *
   * @param proxy The proxy host and port.
   */
  public void setProxy(String proxy);

  /**
   * Set credentials to use for HTTP Basic authentication.
   *
   * @param username The username to use, never null or empty.
   * @param password The password to use, never null or empty.
   */
  public void setBasicAuthCredentials(String username, String password);

  /**
   * Tells this exchange whether to follow redirects.  Default is to not follow
   * them.
   *
   * @param followRedirects {@code true} means follow them.
   */
  public void setFollowRedirects(boolean followRedirects);

  /**
   * Sets the timeout.
   */
  public void setTimeout(int timeout);

  /**
   * Gets the HTTP method name.
   *
   * @return The HTTP method string: e.g. {@code "GET"} or {@code "POST"}.
   */
  @Nonnull
  public String getHttpMethod();

  /**
   * Gets the request URL for this exchange.
   *
   * @return The URL for this exchange.
   */
  public URL getUrl();

  /**
   * Adds a parameter to the exchange.  Works only for POST methods.
   *
   * @param name The parameter's name.
   * @param value The parameter's value.
   */
  public void addParameter(String name, String value);

  /**
   * Adds an HTTP request header field.  Must not be used to set cookies (use
   * {@link #addCookies}).
   *
   * @param name The header's name (case insensitive).
   * @param value The header's value.
   */
  public void addRequestHeader(String name, String value);

  /**
   * Sets an HTTP request header field.  Overrides any previous header of that
   * name.  Must not be used to set cookies (use {@link #addCookies}).
   *
   * @param name The header's name (case insensitive).
   * @param value The header's value.
   */
  public void setRequestHeader(String name, String value);

  /**
   * Gets the request header values for a specified header name.
   *
   * @param headerName The header name (case insensitive).
   * @return The header values for that name.
   */
  @Nonnull
  public List<String> getRequestHeaderValues(String headerName);

  /**
   * Gets the request header value for a specified header name.  If there are
   * one or more headers with that name, returns the first one; otherwise
   * returns {@code null}.
   *
   * @param headerName The header's name (case insensitive).
   * @return The specified request header value.
   */
  @Nullable
  public String getRequestHeaderValue(String headerName);

  /**
   * Sets the entity of the request.
   *
   * @param byteArrayRequestEntity The bytes to use as an entity.
   */
  public void setRequestBody(byte[] byteArrayRequestEntity);

  /**
   * Performs the HTTP exchange.
   *
   * @return The status code from the exchange.
   * @throws IOException if there's a transport error.
   */
  public int exchange() throws IOException;

  /**
   * Gets the response entity (body) as a string.
   *
   * @return The entity.
   * @throws IOException if there's a transport error.
   */
  @Nonnull
  public String getResponseEntityAsString() throws IOException;

  /**
   * Gets the response entity (body) as an input stream.
   *
   * @return The entity input stream.
   * @throws IOException if there's a transport error.
   */
  @Nonnull
  public InputStream getResponseEntityAsStream() throws IOException;

  /**
   * Gets the response header values for a given header name.
   *
   * @param headerName The header name to use.
   * @return The values of all the response headers with that name.
   */
  @Nonnull
  public List<String> getResponseHeaderValues(String headerName);

  /**
   * Gets the response header value for a given header name.  If there are one
   * or more such headers, returns the first one; otherwise returns
   * {@code null}.
   *
   * @param headerName The header name to use.
   * @return The value of the specified response header.
   */
  @Nullable
  public String getResponseHeaderValue(String headerName);

  /**
   * Gets all of the headers in the response as a multimap.  The map keys will
   * always be lower case; convert a key argument to lower case before doing
   * lookup.
   *
   * @return An immutable multimap of all the received headers.
   */
  @Nonnull
  public ListMultimap<String, String> getResponseHeaders();

  /**
   * Gets the status code from the exchange.
   *
   * @return The status code.
   */
  public int getStatusCode();

  /**
   * Closes the exchange and reclaim its resources.
   */
  public void close();
}