001 // Copyright 2006, 2007, 2008, 2011 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 015 package org.apache.tapestry5.services; 016 017 import java.util.List; 018 import 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 * <p/> 025 * The Request service is a {@linkplain org.apache.tapestry5.ioc.services.PropertyShadowBuilder shadow} of the current 026 * thread's request. 027 */ 028 public interface Request 029 { 030 /** 031 * Gets the {@link Session}. If create is false and the session has not be created previously, returns null. Also, 032 * if the session is invalidated and create is false, returns null. 033 * 034 * @param create true to force the creation of the session 035 * @return the session (or null if create is false the session has not been previously created) 036 */ 037 Session getSession(boolean create); 038 039 /** 040 * Returns the context path. This always starts with a "/" character and does not end with one, with the exception 041 * of servlets in the root context, which return the empty string. 042 */ 043 String getContextPath(); 044 045 /** 046 * Returns a list of query parameter names, in alphabetical order. 047 */ 048 List<String> getParameterNames(); 049 050 /** 051 * Returns the query parameter value for the given name. Returns null if no such parameter is in the request. For a 052 * multi-valued parameter, returns just the first value. 053 */ 054 String getParameter(String name); 055 056 /** 057 * Returns the parameter values for the given name. Returns null if no such parameter is in the request. 058 */ 059 String[] getParameters(String name); 060 061 /** 062 * Returns the path portion of the request, which starts with a "/" and contains everything up to the start of the 063 * query parameters. It doesn't include the context path. 064 */ 065 String getPath(); 066 067 /** 068 * Returns the locale of the client as determined from the request headers. 069 */ 070 Locale getLocale(); 071 072 /** 073 * Returns the names of all headers in the request. 074 */ 075 List<String> getHeaderNames(); 076 077 /** 078 * Returns the value of the specified request header as a <code>long</code> value that represents a 079 * <code>Date</code> object. Use this method with headers that contain dates, such as <code>If-Modified-Since</code> 080 * . 081 * <p/> 082 * The date is returned as the number of milliseconds since January 1, 1970 GMT. The header name is case 083 * insensitive. 084 * <p/> 085 * If the request did not have a header of the specified name, this method returns -1. If the header can't be 086 * converted to a date, the method throws an <code>IllegalArgumentException</code>. 087 * 088 * @param name a <code>String</code> specifying the name of the header 089 * @return a <code>long</code> value representing the date specified in the header expressed as the number of 090 * milliseconds since January 1, 1970 GMT, or -1 if the named header was not included with the reqest 091 * @throws IllegalArgumentException If the header value can't be converted to a date 092 */ 093 long getDateHeader(String name); 094 095 /** 096 * Returns the named header as a string, or null if not found. 097 */ 098 String getHeader(String name); 099 100 /** 101 * Returns true if the request originated on the client using XmlHttpRequest (the core of any Ajax behavior). Ajax 102 * action requests may behave quite differently than ordinary, page-based requests. This implementation currently 103 * depends on the client side setting a header: <strong>X-Requested-With=XMLHttpRequest</strong> (this is what 104 * Prototype does). 105 * 106 * @return true if the request has an XmlHttpRequest origin 107 */ 108 boolean isXHR(); 109 110 /** 111 * Returns a boolean indicating whether this request was made using a secure channel, such as HTTPS. 112 * 113 * @return a boolean indicating if the request was made using a secure channel 114 */ 115 public boolean isSecure(); 116 117 /** 118 * Returns the host name of the server to which the request was sent. It is the value of the part before ":" in the 119 * <code>Host</code> header, if any, or the resolved server name, or the server IP address. 120 * 121 * @return the name of the server 122 */ 123 public String getServerName(); 124 125 /** 126 * Checks whether the requested session ID is still valid. 127 * 128 * @return true if the request included a session id that is still active, false if the included session id has 129 * expired 130 */ 131 boolean isRequestedSessionIdValid(); 132 133 /** 134 * Returns the value of the named attribute as an <code>Object</code>, or <code>null</code> if no attribute of the 135 * given name exists. Because this method is a wrapper around 136 * {@link javax.servlet.ServletRequest#getAttribute(String)}, 137 * it is case <em>sensitive</em> (unlike most of Tapestry). 138 * 139 * @param name a <code>String</code> specifying the name of the attribute 140 * @return an <code>Object</code> containing the value of the attribute, or <code>null</code> if the attribute does 141 * not exist 142 */ 143 Object getAttribute(String name); 144 145 /** 146 * Stores an attribute in this request. Attributes are reset between requests (and remember that in Tapestry, there 147 * is usually two requests per operation: the action request that redirects to a render request). 148 * 149 * @param name a <code>String</code> specifying the name of the attribute 150 * @param value the <code>Object</code> to be stored, or null to remove the attribute 151 */ 152 void setAttribute(String name, Object value); 153 154 /** 155 * Returns the name of the HTTP method with which this request was made, for example, GET, POST, or PUT. 156 * 157 * @return a string specifying the name of the method with which this request was made 158 */ 159 String getMethod(); 160 161 /** 162 * Returns the Internet Protocol (IP) port number of the interface 163 * on which the request was received. 164 * 165 * @return an integer specifying the port number 166 * @since 5.2.0 167 */ 168 int getLocalPort(); 169 170 /** 171 * Returns the port number to which the request was sent. 172 * It is the value of the part after ":" in the <code>Host</code> header, if any, or the server port where the 173 * client connection 174 * was accepted on. 175 * 176 * @return an integer specifying the port number 177 * @since 5.2.5 178 */ 179 int getServerPort(); 180 181 /** 182 * Returns the fully qualified name of the client 183 * or the last proxy that sent the request. 184 * If the engine cannot or chooses not to resolve the hostname 185 * (to improve performance), this method returns the dotted-string form of 186 * the IP address. 187 * 188 * @return a <code>String</code> containing the fully 189 * qualified name of the client 190 * @since 5.3 191 */ 192 String getRemoteHost(); 193 }