/**
* Copyright 2015 Google Inc. All Rights Reserved.
*
* 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.apphosting.utils.http;
/**
* Generic Http request (subset of the Servlet specification.)
*/
public interface HttpRequest {
/**
* Returns any extra path information associated with the URL the client sent when it made this
* request. The extra path information follows the servlet path but precedes the query string and
* will start with a "/" character.
*
* <p>This method returns <code>null</code> if there was no extra path information.
*
* <p>Same as the value of the CGI variable PATH_INFO.
*
* @return a <code>String</code>, decoded by the web container, specifying extra path information
* that comes after the servlet path but before the query string in the request URL; or
* <code>null</code> if the URL does not have any extra path information
*/
String getPathInfo();
/**
* Returns the value of the specified request header as an <code>int</code>. If the request does
* not have a header of the specified name, this method returns -1. If the header cannot be
* converted to an integer, this method throws a <code>NumberFormatException</code>.
*
* <p>The header name is case insensitive.
*
* @param name a <code>String</code> specifying the name of a request header
* @return an integer expressing the value of the request header or -1 if the request doesn't
* have a header of this name
* @exception NumberFormatException If the header value can't be converted to an
* <code>int</code>
*/
String getHeader(String name);
/**
* Returns the value of a request parameter as a <code>String</code>, or <code>null</code> if the
* parameter does not exist. Request parameters are extra information sent with the request. For
* HTTP servlets, parameters are contained in the query string or posted form data.
*
* <p>You should only use this method when you are sure the parameter has only one value. If the
* parameter might have more than one value, use {@link #getParameterValues}.
*
* <p>If you use this method with a multivalued parameter, the value returned is equal to the
* first value in the array returned by <code>getParameterValues</code>.
*
* <p>If the parameter data was sent in the request body, such as occurs with an HTTP POST
* request, then reading the body directly via {@link #getInputStream} or {@link #getReader} can
* interfere with the execution of this method.
*
* @param name a <code>String</code> specifying the name of the parameter
* @return a <code>String</code> representing the single value of the parameter
*/
String getParameter(String name);
/**
* Stores an attribute in this request. Attributes are reset between requests. This method is
* most often used in conjunction with {@link javax.servlet.RequestDispatcher}.
*
* <p>Attribute names should follow the same conventions as package names. Names beginning with
* <code>java.*</code>, <code>javax.*</code>, and <code>com.sun.*</code>, are reserved for use by
* Sun Microsystems. <br> If the object passed in is null, the effect is the same as calling
* {@link #removeAttribute}. <br> It is warned that when the request is dispatched from the
* servlet resides in a different web application by <code>RequestDispatcher</code>, the object
* set by this method may not be correctly retrieved in the caller servlet.
*
* @param name a <code>String</code> specifying the name of the attribute
* @param value the <code>Object</code> to be stored
*/
void setAttribute(String name, Object value);
}