/*
    * $Id: Request.java 1375743 2012-08-21 20:05:58Z nlebas $
    *
    * 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.tiles.request;
  
  import java.io.IOException;
  import java.io.OutputStream;
  import java.io.PrintWriter;
  import java.io.Writer;
  import java.util.List;
  import java.util.Locale;
  import java.util.Map;
  
  import org.apache.tiles.request.attribute.Addable;
  
  
  /**
   * Encapsulation of request information.
   *
   * @version $Rev: 1375743 $ $Date: 2012-08-22 06:05:58 +1000 (Wed, 22 Aug 2012) $
   */
  public interface Request {
  
      /** the name of the (mandatory) "application" scope */
      static String APPLICATION_SCOPE = "application";
  
      /** the name of the "request" context */
      static String REQUEST_SCOPE = "request";
  
      /**
       * Return an immutable Map that maps header names to the first (or only)
       * header value (as a String).
       *
       * @return The header map.
       */
      Map<String, String> getHeader();
  
      /**
       * Return an immutable Map that maps header names to the set of all values
       * specified in the request (as a String array). Header names must be
       * matched in a case-insensitive manner.
       *
       * @return The header values map.
       */
      Map<String, String[]> getHeaderValues();
  
      /**
       * Return an Addable object that can be used to write headers to the response.
       *
       * @return An Addable object.
       */
      Addable<String> getResponseHeaders();
  
      /**
       * Returns a context map, given the scope name.
       * This method always return a map for all the scope names returned by
       * getAvailableScopes(). That map may be writable, or immutable, depending
       * on the implementation.
       *
       * @param scope The name of the scope.
       * @return The context.
       */
      Map<String, Object> getContext(String scope);
  
      /**
       * Returns all available scopes.
       * The scopes are ordered according to their lifetime,
       * the innermost, shorter lived scope appears first,
       * and the outermost, longer lived scope appears last.
       * Besides, the scopes "request" and "application" always included
       * in the list.
       *
       * @return All the available scopes.
       */
      List<String> getAvailableScopes();
  
      /**
       * Returns the associated application context.
       *
       * @return The application context associated to this request.
       */
      ApplicationContext getApplicationContext();
 
     /**
      * Returns an output stream to be used to write directly in the response.
      *
      * @return The output stream that writes in the response.
      * @throws IOException If something goes wrong when getting the output stream.
      */
     OutputStream getOutputStream() throws IOException;
 
     /**
      * Returns a writer to be used to write directly in the response.
      *
      * @return The writer that writes in the response.
      * @throws IOException If something goes wrong when getting the writer.
      */
     Writer getWriter() throws IOException;
 
     /**
      * Returns a print writer to be used to write directly in the response.
      *
      * @return The print writer that writes in the response.
      * @throws IOException If something goes wrong when getting the print
      * writer.
      */
     PrintWriter getPrintWriter() throws IOException;
 
     /**
      * Checks if the response has been committed.
      *
      * @return <code>true</code> only if the response has been committed.
      */
     boolean isResponseCommitted();
 
     /**
      * Return an immutable Map that maps request parameter names to the first
      * (or only) value (as a String).
      *
      * @return The parameter map.
      */
     Map<String, String> getParam();
 
     /**
      * Return an immutable Map that maps request parameter names to the set of
      * all values (as a String array).
      *
      * @return The parameter values map.
      */
     Map<String, String[]> getParamValues();
 
     /**
      * Return the preferred Locale in which the client will accept content.
      *
      * @return The current request locale. It is the locale of the request
      * object itself and it is NOT the locale that the user wants to use. See
      * {@link org.apache.tiles.locale.LocaleResolver} to implement strategies to
      * resolve locales.
      */
     Locale getRequestLocale();
 
     /**
      * Determine whether or not the specified user is in the given role.
      * @param role the role to check against.
      * @return <code>true</code> if the user is in the given role.
      */
     boolean isUserInRole(String role);
 
 }