/*
 * Licensed to the Apache Software Foundation (ASF) under one
 * or more contributor license agreements.  See the NOTICE file
 * distributed with this work for additional information
 * regarding copyright ownership.  The ASF licenses this file
 * to you 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 org.apache.sling.api;

import java.util.Enumeration;
import java.util.List;
import java.util.Locale;
import java.util.ResourceBundle;

import javax.annotation.CheckForNull;
import javax.annotation.Nonnull;
import javax.servlet.RequestDispatcher;
import javax.servlet.http.Cookie;
import javax.servlet.http.HttpServletRequest;

import org.apache.sling.api.adapter.Adaptable;
import org.apache.sling.api.request.RequestDispatcherOptions;
import org.apache.sling.api.request.RequestParameter;
import org.apache.sling.api.request.RequestParameterMap;
import org.apache.sling.api.request.RequestPathInfo;
import org.apache.sling.api.request.RequestProgressTracker;
import org.apache.sling.api.resource.Resource;
import org.apache.sling.api.resource.ResourceResolver;

import org.osgi.annotation.versioning.ProviderType;

/**
 * The <code>SlingHttpServletRequest</code> defines the interface to provide
 * client request information to a servlet.
 * <p>
 * <b>Request Parameters</b> Generally request parameters are transmitted as
 * part of the URL string such as <code>GET /some/path?<b>param=value</b></code>
 * or as request data of content type <i>application/x-www-form-urlencoded</i>
 * or <i>multipart/form-data</i>. The Sling Framework must decode parameters
 * transferred as request data and make them available through the various
 * parameter accessor methods. Generally parameters transferred as
 * <i>multipart/form-data</i> will be accessed by one of the methods returning
 * {@link RequestParameter} instances.
 * <p>
 * In any case, the {@link #getReader()} and {@link #getInputStream()} methods
 * will throw an <code>IllegalStateException</code> if called after any methods
 * returning request parameters if the request content type is either
 * <i>application/x-www-form-urlencoded</i> or <i>multipart/form-data</i>
 * because the request data has already been processed.
 * <p>
 * Starting with Sling API 2.0.6, this interface als extends the
 * {@link Adaptable} interface.
 */
@ProviderType
public interface SlingHttpServletRequest extends HttpServletRequest, Adaptable {

    /**
     * Returns the {@link Resource} object on whose behalf the servlet acts.
     *
     * @return The <code>Resource</code> object of this request.
     */
    @Nonnull Resource getResource();

    /**
     * Returns the {@link ResourceResolver} which resolved the
     * {@link #getResource() resource} of this request.
     *
     * @return The resource resolver
     */
    @Nonnull ResourceResolver getResourceResolver();

    /**
     * Returns the {@link RequestPathInfo} pertaining to this request.
     *
     * @return the request path info.
     */
    @Nonnull RequestPathInfo getRequestPathInfo();

    /**
     * Returns the value of a request parameter as a {@link RequestParameter},
     * or <code>null</code> if the parameter does not exist.
     * <p>
     * This method should only be used if the parameter has only one value. If
     * the parameter might have more than one value, use
     * {@link #getRequestParameters(String)}.
     * <p>
     * If this method is used with a multivalued parameter, the value returned
     * is equal to the first value in the array returned by
     * <code>getRequestParameters</code>.
     * <p>
     * This method is a shortcut for
     * <code>getRequestParameterMap().getValue(String)</code>.
     *
     * @param name a <code>String</code> specifying the name of the parameter
     * @return a {@link RequestParameter} representing the single value of the
     *         parameter
     * @see #getRequestParameters(String)
     * @see RequestParameterMap#getValue(String)
     * @throws IllegalArgumentException if name is <code>null</code>.
     */
    @CheckForNull RequestParameter getRequestParameter(@Nonnull String name);

    /**
     * Returns an array of {@link RequestParameter} objects containing all of
     * the values the given request parameter has, or <code>null</code> if the
     * parameter does not exist.
     * <p>
     * If the parameter has a single value, the array has a length of 1.
     * <p>
     * This method is a shortcut for
     * <code>getRequestParameterMap().getValues(String)</code>.
     *
     * @param name a <code>String</code> containing the name of the parameter
     *            the value of which is requested
     * @return an array of {@link RequestParameter} objects containing the
     *         parameter values.
     * @see #getRequestParameter(String)
     * @see RequestParameterMap#getValues(String)
     * @throws IllegalArgumentException if name is <code>null</code>.
     */
    @CheckForNull RequestParameter[] getRequestParameters(@Nonnull String name);

    /**
     * Returns a <code>Map</code> of the parameters of this request.
     * <p>
     * The values in the returned <code>Map</code> are from type
     * {@link RequestParameter} array (<code>RequestParameter[]</code>).
     * <p>
     * If no parameters exist this method returns an empty <code>Map</code>.
     *
     * @return an immutable <code>Map</code> containing parameter names as
     *         keys and parameter values as map values, or an empty
     *         <code>Map</code> if no parameters exist. The keys in the
     *         parameter map are of type String. The values in the parameter map
     *         are of type {@link RequestParameter} array (<code>RequestParameter[]</code>).
     */
   @Nonnull RequestParameterMap getRequestParameterMap();

    /**
     * Returns the request parameters as instances of the
     * {@link RequestParameter} interface in the order or the request where the
     * query string parameters are first and the POST request parameters are
     * second.
     *
     * @return The list of {@link RequestParameter} in request declaration
     *         order.
     * @since 2.3  (Sling API Bundle 2.6.0)
     */
    @Nonnull List<RequestParameter> getRequestParameterList();

    /**
     * Returns a <code>RequestDispatcher</code> object that acts as a wrapper
     * for the resource located at the given path. A
     * <code>RequestDispatcher</code> object can be used to include the
     * resource in a response.
     * <p>
     * Returns <code>null</code> if a <code>RequestDispatcher</code> cannot
     * be returned for any reason.
     *
     * @param path a <code>String</code> specifying the pathname to the
     *            resource. If it is relative, it must be relative against the
     *            current servlet.
     * @param options influence the rendering of the included Resource
     * @return a <code>RequestDispatcher</code> object that acts as a wrapper
     *         for the <code>resource</code> or <code>null</code> if an
     *         error occurs preparing the dispatcher.
     */
    @CheckForNull RequestDispatcher getRequestDispatcher(@Nonnull String path,
            RequestDispatcherOptions options);

    /**
     * Returns a <code>RequestDispatcher</code> object that acts as a wrapper
     * for the resource located at the given resource. A
     * <code>RequestDispatcher</code> object can be used to include the
     * resource in a response.
     * <p>
     * Returns <code>null</code> if a <code>RequestDispatcher</code> cannot
     * be returned for any reason.
     *
     * @param resource The {@link Resource} instance whose response content may
     *            be included by the returned dispatcher.
     * @param options influence the rendering of the included Resource
     * @return a <code>RequestDispatcher</code> object that acts as a wrapper
     *         for the <code>resource</code> or <code>null</code> if an
     *         error occurs preparing the dispatcher.
     */
    @CheckForNull RequestDispatcher getRequestDispatcher(@Nonnull Resource resource,
            RequestDispatcherOptions options);

    /**
     * Same as {@link #getRequestDispatcher(Resource,RequestDispatcherOptions)}
     * but using empty options.
     * @param resource The {@link Resource} instance whose response content may
     *            be included by the returned dispatcher.
     * @return a <code>RequestDispatcher</code> object that acts as a wrapper
     *         for the <code>resource</code> or <code>null</code> if an
     *         error occurs preparing the dispatcher.
     */
    @CheckForNull RequestDispatcher getRequestDispatcher(@Nonnull Resource resource);

    /**
     * Returns the named cookie from the HTTP request or <code>null</code> if
     * no such cookie exists in the request.
     *
     * @param name The name of the cookie to return.
     * @return The named cookie or <code>null</code> if no such cookie exists.
     */
    @CheckForNull Cookie getCookie(String name);

    /**
     * Returns the framework preferred content type for the response. The
     * content type only includes the MIME type, not the character set.
     * <p>
     * For included resources this method will returned the same string as
     * returned by the <code>ServletResponse.getContentType()</code> without
     * the character set.
     *
     * @return preferred MIME type of the response
     */
    @CheckForNull String getResponseContentType();

    /**
     * Gets a list of content types which the framework accepts for the
     * response. This list is ordered with the most preferable types listed
     * first. The content type only includes the MIME type, not the character
     * set.
     * <p>
     * For included resources this method will returned an enumeration
     * containing a single entry which is the same string as returned by the
     * <code>ServletResponse.getContentType()</code> without the character
     * set.
     *
     * @return ordered list of MIME types for the response
     */
    @Nonnull Enumeration<String> getResponseContentTypes();

    /**
     * Returns the resource bundle for the given locale.
     *
     * @param locale the locale for which to retrieve the resource bundle. If
     *            this is <code>null</code>, the locale returned by
     *            {@link #getLocale()} is used to select the resource bundle.
     * @return the resource bundle for the given locale
     */
    @CheckForNull ResourceBundle getResourceBundle(Locale locale);

    /**
     * Returns the resource bundle of the given base name for the given locale.
     *
     * @param baseName The base name of the resource bundle to returned. If this
     *            parameter is <code>null</code>, the same resource bundle
     *            must be returned as if the {@link #getResourceBundle(Locale)}
     *            method is called.
     * @param locale the locale for which to retrieve the resource bundle. If
     *            this is <code>null</code>, the locale returned by
     *            {@link #getLocale()} is used to select the resource bundle.
     * @return the resource bundle for the given locale
     */
    @CheckForNull ResourceBundle getResourceBundle(String baseName, Locale locale);

    /**
     * Returns the {@link RequestProgressTracker} of this request.
     * @return The request progress tracker.
     */
    @Nonnull RequestProgressTracker getRequestProgressTracker();
}