001// Copyright 2006, 2007, 2008, 2011, 2012 The Apache Software Foundation 002// 003// Licensed under the Apache License, Version 2.0 (the "License"); 004// you may not use this file except in compliance with the License. 005// You may obtain a copy of the License at 006// 007// http://www.apache.org/licenses/LICENSE-2.0 008// 009// Unless required by applicable law or agreed to in writing, software 010// distributed under the License is distributed on an "AS IS" BASIS, 011// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 012// See the License for the specific language governing permissions and 013// limitations under the License. 014 015package org.apache.tapestry5.services; 016 017import java.util.List; 018import java.util.Locale; 019 020/** 021 * Generic version of {@link javax.servlet.http.HttpServletRequest}, used to encapsulate the Servlet API version, and to 022 * help bridge the differences between Servlet API and Porlet API. 023 * <p/> 024 * The Request service is a {@linkplain org.apache.tapestry5.ioc.services.PropertyShadowBuilder shadow} of the current 025 * thread's request. 026 */ 027public interface Request 028{ 029 /** 030 * Gets the {@link Session}. If create is false and the session has not be created previously, returns null. Also, 031 * if the session is invalidated and create is false, returns null. Invoking this method with true, when the session exists but has 032 * been invalidated, will force the creation of a new session. 033 * 034 * @param create 035 * true to force the creation of the session 036 * @return the session (or null if create is false the session has not been previously created) 037 */ 038 Session getSession(boolean create); 039 040 /** 041 * Returns the context path. This always starts with a "/" character and does not end with one, with the exception 042 * of servlets in the root context, which return the empty string. 043 * 044 * @deprecated in 5.4, inject the value for symbol {@link org.apache.tapestry5.SymbolConstants#CONTEXT_PATH} instead 045 */ 046 String getContextPath(); 047 048 /** 049 * Returns a list of query parameter names, in alphabetical order. 050 */ 051 List<String> getParameterNames(); 052 053 /** 054 * Returns the query parameter value for the given name. Returns null if no such parameter is in the request. For a 055 * multi-valued parameter, returns just the first value. 056 */ 057 String getParameter(String name); 058 059 /** 060 * Returns the parameter values for the given name. Returns null if no such parameter is in the request. 061 */ 062 String[] getParameters(String name); 063 064 /** 065 * Returns the path portion of the request, which starts with a "/" and contains everything up to the start of the 066 * query parameters. It doesn't include the context path. 067 */ 068 String getPath(); 069 070 /** 071 * Returns the locale of the client as determined from the request headers. 072 */ 073 Locale getLocale(); 074 075 /** 076 * Returns the names of all headers in the request. 077 */ 078 List<String> getHeaderNames(); 079 080 /** 081 * Returns the value of the specified request header as a <code>long</code> value that represents a 082 * <code>Date</code> object. Use this method with headers that contain dates, such as <code>If-Modified-Since</code> 083 * . 084 * <p/> 085 * The date is returned as the number of milliseconds since January 1, 1970 GMT. The header name is case 086 * insensitive. 087 * <p/> 088 * If the request did not have a header of the specified name, this method returns -1. If the header can't be 089 * converted to a date, the method throws an <code>IllegalArgumentException</code>. 090 * 091 * @param name 092 * a <code>String</code> specifying the name of the header 093 * @return a <code>long</code> value representing the date specified in the header expressed as the number of 094 * milliseconds since January 1, 1970 GMT, or -1 if the named header was not included with the reqest 095 * @throws IllegalArgumentException 096 * If the header value can't be converted to a date 097 */ 098 long getDateHeader(String name); 099 100 /** 101 * Returns the named header as a string, or null if not found. 102 */ 103 String getHeader(String name); 104 105 /** 106 * Returns true if the request originated on the client using XmlHttpRequest (the core of any Ajax behavior). Ajax 107 * action requests may behave quite differently than ordinary, page-based requests. This implementation currently 108 * depends on the client side setting a header: <strong>X-Requested-With=XMLHttpRequest</strong> (this is what 109 * Prototype does). 110 * 111 * @return true if the request has an XmlHttpRequest origin 112 */ 113 boolean isXHR(); 114 115 /** 116 * Returns a boolean indicating whether this request was made using a secure channel, such as HTTPS. 117 * 118 * @return a boolean indicating if the request was made using a secure channel 119 */ 120 public boolean isSecure(); 121 122 /** 123 * Returns the host name of the server to which the request was sent. It is the value of the part before ":" in the 124 * <code>Host</code> header, if any, or the resolved server name, or the server IP address. 125 * 126 * @return the name of the server 127 */ 128 public String getServerName(); 129 130 /** 131 * Checks whether the requested session ID is still valid. 132 * 133 * @return true if the request included a session id that is still active, false if the included session id has 134 * expired 135 */ 136 boolean isRequestedSessionIdValid(); 137 138 /** 139 * Returns the value of the named attribute as an <code>Object</code>, or <code>null</code> if no attribute of the 140 * given name exists. Because this method is a wrapper around 141 * {@link javax.servlet.ServletRequest#getAttribute(String)}, 142 * it is case <em>sensitive</em> (unlike most of Tapestry). 143 * 144 * @param name 145 * a <code>String</code> specifying the name of the attribute 146 * @return an <code>Object</code> containing the value of the attribute, or <code>null</code> if the attribute does 147 * not exist 148 */ 149 Object getAttribute(String name); 150 151 /** 152 * Returns a sorted list of attribute names. 153 * 154 * @since 5.4 155 */ 156 List<String> getAttributeNames(); 157 158 159 /** 160 * Stores an attribute in this request. Attributes are reset between requests (and remember that in Tapestry, there 161 * is usually two requests per operation: the action request that redirects to a render request). 162 * 163 * @param name 164 * a <code>String</code> specifying the name of the attribute 165 * @param value 166 * the <code>Object</code> to be stored, or null to remove the attribute 167 */ 168 void setAttribute(String name, Object value); 169 170 /** 171 * Returns the name of the HTTP method with which this request was made, for example, GET, POST, or PUT. 172 * 173 * @return a string specifying the name of the method with which this request was made 174 */ 175 String getMethod(); 176 177 /** 178 * Returns the Internet Protocol (IP) port number of the interface 179 * on which the request was received. 180 * 181 * @return an integer specifying the port number 182 * @since 5.2.0 183 */ 184 int getLocalPort(); 185 186 /** 187 * Returns the port number to which the request was sent. 188 * It is the value of the part after ":" in the <code>Host</code> header, if any, or the server port where the 189 * client connection 190 * was accepted on. 191 * 192 * @return an integer specifying the port number 193 * @since 5.2.5 194 */ 195 int getServerPort(); 196 197 /** 198 * Returns the fully qualified name of the client 199 * or the last proxy that sent the request. 200 * If the engine cannot or chooses not to resolve the hostname 201 * (to improve performance), this method returns the dotted-string form of 202 * the IP address. 203 * 204 * @return a <code>String</code> containing the fully 205 * qualified name of the client 206 * @since 5.3 207 */ 208 String getRemoteHost(); 209 210 /** 211 * Returns true if the request specified a session, and that session has been invalidated. 212 * 213 * @return true if session was invalidated during this request 214 * @since 5.4 215 */ 216 boolean isSessionInvalidated(); 217}