KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > springframework > web > util > WebUtils


1 /*
2  * Copyright 2002-2007 the original author or authors.
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  * http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */

16
17 package org.springframework.web.util;
18
19 import java.io.File JavaDoc;
20 import java.io.FileNotFoundException JavaDoc;
21 import java.util.Enumeration JavaDoc;
22 import java.util.Iterator JavaDoc;
23 import java.util.Map JavaDoc;
24 import java.util.TreeMap JavaDoc;
25
26 import javax.servlet.ServletContext JavaDoc;
27 import javax.servlet.ServletRequest JavaDoc;
28 import javax.servlet.http.Cookie JavaDoc;
29 import javax.servlet.http.HttpServletRequest JavaDoc;
30 import javax.servlet.http.HttpSession JavaDoc;
31
32 import org.springframework.util.Assert;
33 import org.springframework.util.StringUtils;
34
35 /**
36  * Miscellaneous utilities for web applications.
37  * Used by various framework classes.
38  *
39  * @author Rod Johnson
40  * @author Juergen Hoeller
41  */

42 public abstract class WebUtils {
43
44     /**
45      * Standard Servlet 2.3+ spec request attributes for include URI and paths.
46      * <p>If included via a RequestDispatcher, the current resource will see the
47      * originating request. Its own URI and paths are exposed as request attributes.
48      */

49     public static final String JavaDoc INCLUDE_REQUEST_URI_ATTRIBUTE = "javax.servlet.include.request_uri";
50     public static final String JavaDoc INCLUDE_CONTEXT_PATH_ATTRIBUTE = "javax.servlet.include.context_path";
51     public static final String JavaDoc INCLUDE_SERVLET_PATH_ATTRIBUTE = "javax.servlet.include.servlet_path";
52     public static final String JavaDoc INCLUDE_PATH_INFO_ATTRIBUTE = "javax.servlet.include.path_info";
53     public static final String JavaDoc INCLUDE_QUERY_STRING_ATTRIBUTE = "javax.servlet.include.query_string";
54
55     /**
56      * Standard Servlet 2.4+ spec request attributes for forward URI and paths.
57      * <p>If forwarded to via a RequestDispatcher, the current resource will see its
58      * own URI and paths. The originating URI and paths are exposed as request attributes.
59      */

60     public static final String JavaDoc FORWARD_REQUEST_URI_ATTRIBUTE = "javax.servlet.forward.request_uri";
61     public static final String JavaDoc FORWARD_CONTEXT_PATH_ATTRIBUTE = "javax.servlet.forward.context_path";
62     public static final String JavaDoc FORWARD_SERVLET_PATH_ATTRIBUTE = "javax.servlet.forward.servlet_path";
63     public static final String JavaDoc FORWARD_PATH_INFO_ATTRIBUTE = "javax.servlet.forward.path_info";
64     public static final String JavaDoc FORWARD_QUERY_STRING_ATTRIBUTE = "javax.servlet.forward.query_string";
65
66
67     /**
68      * Prefix of the charset clause in a content type String: ";charset="
69      */

70     public static final String JavaDoc CONTENT_TYPE_CHARSET_PREFIX = ";charset=";
71
72     /**
73      * Default character encoding to use when <code>request.getCharacterEncoding</code>
74      * returns <code>null</code>, according to the Servlet spec.
75      * @see ServletRequest#getCharacterEncoding
76      */

77     public static final String JavaDoc DEFAULT_CHARACTER_ENCODING = "ISO-8859-1";
78
79     /**
80      * Standard Servlet spec context attribute that specifies a temporary
81      * directory for the current web application, of type <code>java.io.File</code>.
82      */

83     public static final String JavaDoc TEMP_DIR_CONTEXT_ATTRIBUTE = "javax.servlet.context.tempdir";
84
85     /**
86      * HTML escape parameter at the servlet context level
87      * (i.e. a context-param in <code>web.xml</code>): "defaultHtmlEscape".
88      */

89     public static final String JavaDoc HTML_ESCAPE_CONTEXT_PARAM = "defaultHtmlEscape";
90
91     /**
92      * Web app root key parameter at the servlet context level
93      * (i.e. a context-param in <code>web.xml</code>): "webAppRootKey".
94      */

95     public static final String JavaDoc WEB_APP_ROOT_KEY_PARAM = "webAppRootKey";
96
97     /** Default web app root key: "webapp.root" */
98     public static final String JavaDoc DEFAULT_WEB_APP_ROOT_KEY = "webapp.root";
99
100     /** Name suffixes in case of image buttons */
101     public static final String JavaDoc[] SUBMIT_IMAGE_SUFFIXES = {".x", ".y"};
102
103     /** Key for the mutex session attribute */
104     public static final String JavaDoc SESSION_MUTEX_ATTRIBUTE = WebUtils.class.getName() + ".MUTEX";
105
106
107     /**
108      * Set a system property to the web application root directory.
109      * The key of the system property can be defined with the "webAppRootKey"
110      * context-param in <code>web.xml</code>. Default is "webapp.root".
111      * <p>Can be used for tools that support substition with <code>System.getProperty</code>
112      * values, like Log4J's "${key}" syntax within log file locations.
113      * @param servletContext the servlet context of the web application
114      * @throws IllegalStateException if the system property is already set,
115      * or if the WAR file is not expanded
116      * @see #WEB_APP_ROOT_KEY_PARAM
117      * @see #DEFAULT_WEB_APP_ROOT_KEY
118      * @see WebAppRootListener
119      * @see Log4jWebConfigurer
120      */

121     public static void setWebAppRootSystemProperty(ServletContext JavaDoc servletContext) throws IllegalStateException JavaDoc {
122         Assert.notNull(servletContext, "ServletContext must not be null");
123         String JavaDoc root = servletContext.getRealPath("/");
124         if (root == null) {
125             throw new IllegalStateException JavaDoc(
126                 "Cannot set web app root system property when WAR file is not expanded");
127         }
128         String JavaDoc param = servletContext.getInitParameter(WEB_APP_ROOT_KEY_PARAM);
129         String JavaDoc key = (param != null ? param : DEFAULT_WEB_APP_ROOT_KEY);
130         String JavaDoc oldValue = System.getProperty(key);
131         if (oldValue != null && !StringUtils.pathEquals(oldValue, root)) {
132             throw new IllegalStateException JavaDoc(
133                 "Web app root system property already set to different value: '" +
134                 key + "' = [" + oldValue + "] instead of [" + root + "] - " +
135                 "Choose unique values for the 'webAppRootKey' context-param in your web.xml files!");
136         }
137         System.setProperty(key, root);
138         servletContext.log("Set web app root system property: '" + key + "' = [" + root + "]");
139     }
140
141     /**
142      * Remove the system property that points to the web app root directory.
143      * To be called on shutdown of the web application.
144      * @param servletContext the servlet context of the web application
145      * @see #setWebAppRootSystemProperty
146      */

147     public static void removeWebAppRootSystemProperty(ServletContext JavaDoc servletContext) {
148         Assert.notNull(servletContext, "ServletContext must not be null");
149         String JavaDoc param = servletContext.getInitParameter(WEB_APP_ROOT_KEY_PARAM);
150         String JavaDoc key = (param != null ? param : DEFAULT_WEB_APP_ROOT_KEY);
151         System.getProperties().remove(key);
152     }
153
154     /**
155      * Return whether default HTML escaping is enabled for the web application,
156      * i.e. the value of the "defaultHtmlEscape" context-param in <code>web.xml</code>
157      * (if any).
158      * @param servletContext the servlet context of the web application
159      * @return whether default HTML escaping is enabled (default is false)
160      */

161     public static boolean isDefaultHtmlEscape(ServletContext JavaDoc servletContext) {
162         Assert.notNull(servletContext, "ServletContext must not be null");
163         String JavaDoc param = servletContext.getInitParameter(HTML_ESCAPE_CONTEXT_PARAM);
164         return Boolean.valueOf(param).booleanValue();
165     }
166
167     /**
168      * Return the temporary directory for the current web application,
169      * as provided by the servlet container.
170      * @param servletContext the servlet context of the web application
171      * @return the File representing the temporary directory
172      */

173     public static File JavaDoc getTempDir(ServletContext JavaDoc servletContext) {
174         Assert.notNull(servletContext, "ServletContext must not be null");
175         return (File JavaDoc) servletContext.getAttribute(TEMP_DIR_CONTEXT_ATTRIBUTE);
176     }
177
178     /**
179      * Return the real path of the given path within the web application,
180      * as provided by the servlet container.
181      * <p>Prepends a slash if the path does not already start with a slash,
182      * and throws a FileNotFoundException if the path cannot be resolved to
183      * a resource (in contrast to ServletContext's <code>getRealPath</code>,
184      * which returns null).
185      * @param servletContext the servlet context of the web application
186      * @param path the path within the web application
187      * @return the corresponding real path
188      * @throws FileNotFoundException if the path cannot be resolved to a resource
189      * @see javax.servlet.ServletContext#getRealPath
190      */

191     public static String JavaDoc getRealPath(ServletContext JavaDoc servletContext, String JavaDoc path) throws FileNotFoundException JavaDoc {
192         Assert.notNull(servletContext, "ServletContext must not be null");
193         // Interpret location as relative to the web application root directory.
194
if (!path.startsWith("/")) {
195             path = "/" + path;
196         }
197         String JavaDoc realPath = servletContext.getRealPath(path);
198         if (realPath == null) {
199             throw new FileNotFoundException JavaDoc(
200                     "ServletContext resource [" + path + "] cannot be resolved to absolute file path - " +
201                     "web application archive not expanded?");
202         }
203         return realPath;
204     }
205
206
207     /**
208      * Determine the session id of the given request, if any.
209      * @param request current HTTP request
210      * @return the session id, or <code>null</code> if none
211      */

212     public static String JavaDoc getSessionId(HttpServletRequest JavaDoc request) {
213         Assert.notNull(request, "Request must not be null");
214         HttpSession JavaDoc session = request.getSession(false);
215         return (session != null ? session.getId() : null);
216     }
217
218     /**
219      * Check the given request for a session attribute of the given name.
220      * Returns null if there is no session or if the session has no such attribute.
221      * Does not create a new session if none has existed before!
222      * @param request current HTTP request
223      * @param name the name of the session attribute
224      * @return the value of the session attribute, or <code>null</code> if not found
225      */

226     public static Object JavaDoc getSessionAttribute(HttpServletRequest JavaDoc request, String JavaDoc name) {
227         Assert.notNull(request, "Request must not be null");
228         HttpSession JavaDoc session = request.getSession(false);
229         return (session != null ? session.getAttribute(name) : null);
230     }
231
232     /**
233      * Check the given request for a session attribute of the given name.
234      * Throws an exception if there is no session or if the session has no such
235      * attribute. Does not create a new session if none has existed before!
236      * @param request current HTTP request
237      * @param name the name of the session attribute
238      * @return the value of the session attribute, or <code>null</code> if not found
239      * @throws IllegalStateException if the session attribute could not be found
240      */

241     public static Object JavaDoc getRequiredSessionAttribute(HttpServletRequest JavaDoc request, String JavaDoc name)
242         throws IllegalStateException JavaDoc {
243
244         Object JavaDoc attr = getSessionAttribute(request, name);
245         if (attr == null) {
246             throw new IllegalStateException JavaDoc("No session attribute '" + name + "' found");
247         }
248         return attr;
249     }
250
251     /**
252      * Set the session attribute with the given name to the given value.
253      * Removes the session attribute if value is null, if a session existed at all.
254      * Does not create a new session if not necessary!
255      * @param request current HTTP request
256      * @param name the name of the session attribute
257      * @param value the value of the session attribute
258      */

259     public static void setSessionAttribute(HttpServletRequest JavaDoc request, String JavaDoc name, Object JavaDoc value) {
260         Assert.notNull(request, "Request must not be null");
261         if (value != null) {
262             request.getSession().setAttribute(name, value);
263         }
264         else {
265             HttpSession JavaDoc session = request.getSession(false);
266             if (session != null) {
267                 session.removeAttribute(name);
268             }
269         }
270     }
271
272     /**
273      * Get the specified session attribute, creating and setting a new attribute if
274      * no existing found. The given class needs to have a public no-arg constructor.
275      * Useful for on-demand state objects in a web tier, like shopping carts.
276      * @param session current HTTP session
277      * @param name the name of the session attribute
278      * @param clazz the class to instantiate for a new attribute
279      * @return the value of the session attribute, newly created if not found
280      * @throws IllegalArgumentException if the session attribute could not be instantiated
281      */

282     public static Object JavaDoc getOrCreateSessionAttribute(HttpSession JavaDoc session, String JavaDoc name, Class JavaDoc clazz)
283             throws IllegalArgumentException JavaDoc {
284
285         Assert.notNull(session, "Session must not be null");
286         Object JavaDoc sessionObject = session.getAttribute(name);
287         if (sessionObject == null) {
288             try {
289                 sessionObject = clazz.newInstance();
290             }
291             catch (InstantiationException JavaDoc ex) {
292                 throw new IllegalArgumentException JavaDoc(
293                     "Could not instantiate class [" + clazz.getName() +
294                     "] for session attribute '" + name + "': " + ex.getMessage());
295             }
296             catch (IllegalAccessException JavaDoc ex) {
297                 throw new IllegalArgumentException JavaDoc(
298                     "Could not access default constructor of class [" + clazz.getName() +
299                     "] for session attribute '" + name + "': " + ex.getMessage());
300             }
301             session.setAttribute(name, sessionObject);
302         }
303         return sessionObject;
304     }
305
306     /**
307      * Return the best available mutex for the given session:
308      * that is, an object to synchronize on for the given session.
309      * <p>Returns the session mutex attribute if available; usually,
310      * this means that the HttpSessionMutexListener needs to be defined
311      * in <code>web.xml</code>. Falls back to the HttpSession itself
312      * if no mutex attribute found.
313      * <p>The session mutex is guaranteed to be the same object during
314      * the entire lifetime of the session, available under the key defined
315      * by the <code>SESSION_MUTEX_ATTRIBUTE</code> constant. It serves as a
316      * safe reference to synchronize on for locking on the current session.
317      * <p>In many cases, the HttpSession reference itself is a safe mutex
318      * as well, since it will always be the same object reference for the
319      * same active logical session. However, this is not guaranteed across
320      * different servlet containers; the only 100% safe way is a session mutex.
321      * @param session the HttpSession to find a mutex for
322      * @return the mutex object (never <code>null</code>)
323      * @see #SESSION_MUTEX_ATTRIBUTE
324      * @see HttpSessionMutexListener
325      */

326     public static Object JavaDoc getSessionMutex(HttpSession JavaDoc session) {
327         Assert.notNull(session, "Session must not be null");
328         Object JavaDoc mutex = session.getAttribute(SESSION_MUTEX_ATTRIBUTE);
329         if (mutex == null) {
330             mutex = session;
331         }
332         return mutex;
333     }
334
335
336     /**
337      * Determine whether the given request is an include request,
338      * that is, not a top-level HTTP request coming in from the outside.
339      * <p>Checks the presence of the "javax.servlet.include.request_uri"
340      * request attribute. Could check any request attribute that is only
341      * present in an include request.
342      * @param request current servlet request
343      * @return whether the given request is an include request
344      */

345     public static boolean isIncludeRequest(ServletRequest JavaDoc request) {
346         return (request.getAttribute(INCLUDE_REQUEST_URI_ATTRIBUTE) != null);
347     }
348
349     /**
350      * Expose the current request URI and paths as {@link javax.servlet.http.HttpServletRequest}
351      * attributes under the keys defined in the Servlet 2.4 specification,
352      * for containers that implement 2.3 or an earlier version of the Servlet API:
353      * <code>javax.servlet.forward.request_uri</code>,
354      * <code>javax.servlet.forward.context_path</code>,
355      * <code>javax.servlet.forward.servlet_path</code>,
356      * <code>javax.servlet.forward.path_info</code>,
357      * <code>javax.servlet.forward.query_string</code>.
358      * <p>Does not override values if already present, to not cause conflicts
359      * with the attributes exposed by Servlet 2.4+ containers themselves.
360      * @param request current servlet request
361      */

362     public static void exposeForwardRequestAttributes(HttpServletRequest JavaDoc request) {
363         if (request.getAttribute(FORWARD_REQUEST_URI_ATTRIBUTE) == null) {
364             request.setAttribute(FORWARD_REQUEST_URI_ATTRIBUTE, request.getRequestURI());
365         }
366         if (request.getAttribute(FORWARD_CONTEXT_PATH_ATTRIBUTE) == null) {
367             request.setAttribute(FORWARD_CONTEXT_PATH_ATTRIBUTE, request.getContextPath());
368         }
369         if (request.getAttribute(FORWARD_SERVLET_PATH_ATTRIBUTE) == null) {
370             request.setAttribute(FORWARD_SERVLET_PATH_ATTRIBUTE, request.getServletPath());
371         }
372         if (request.getAttribute(FORWARD_PATH_INFO_ATTRIBUTE) == null) {
373             request.setAttribute(FORWARD_PATH_INFO_ATTRIBUTE, request.getPathInfo());
374         }
375         if (request.getAttribute(FORWARD_QUERY_STRING_ATTRIBUTE) == null) {
376             request.setAttribute(FORWARD_QUERY_STRING_ATTRIBUTE, request.getQueryString());
377         }
378     }
379
380     /**
381      * Expose the given Map as request attributes, using the keys as attribute names
382      * and the values as corresponding attribute values. Keys need to be Strings.
383      * @param request current HTTP request
384      * @param attributes the attributes Map
385      * @throws IllegalArgumentException if an invalid key is found in the Map
386      */

387     public static void exposeRequestAttributes(ServletRequest JavaDoc request, Map JavaDoc attributes)
388             throws IllegalArgumentException JavaDoc {
389
390         Assert.notNull(request, "Request must not be null");
391         Iterator JavaDoc it = attributes.entrySet().iterator();
392         while (it.hasNext()) {
393             Map.Entry JavaDoc entry = (Map.Entry JavaDoc) it.next();
394             if (!(entry.getKey() instanceof String JavaDoc)) {
395                 throw new IllegalArgumentException JavaDoc(
396                         "Invalid key [" + entry.getKey() + "] in attributes Map - only Strings allowed as attribute keys");
397             }
398             request.setAttribute((String JavaDoc) entry.getKey(), entry.getValue());
399         }
400     }
401
402     /**
403      * Retrieve the first cookie with the given name. Note that multiple
404      * cookies can have the same name but different paths or domains.
405      * @param request current servlet request
406      * @param name cookie name
407      * @return the first cookie with the given name, or <code>null</code> if none is found
408      */

409     public static Cookie JavaDoc getCookie(HttpServletRequest JavaDoc request, String JavaDoc name) {
410         Assert.notNull(request, "Request must not be null");
411         Cookie JavaDoc cookies[] = request.getCookies();
412         if (cookies != null) {
413             for (int i = 0; i < cookies.length; i++) {
414                 if (name.equals(cookies[i].getName())) {
415                     return cookies[i];
416                 }
417             }
418         }
419         return null;
420     }
421
422     /**
423      * Check if a specific input type="submit" parameter was sent in the request,
424      * either via a button (directly with name) or via an image (name + ".x" or
425      * name + ".y").
426      * @param request current HTTP request
427      * @param name name of the parameter
428      * @return if the parameter was sent
429      * @see #SUBMIT_IMAGE_SUFFIXES
430      */

431     public static boolean hasSubmitParameter(ServletRequest JavaDoc request, String JavaDoc name) {
432         Assert.notNull(request, "Request must not be null");
433         if (request.getParameter(name) != null) {
434             return true;
435         }
436         for (int i = 0; i < SUBMIT_IMAGE_SUFFIXES.length; i++) {
437             String JavaDoc suffix = SUBMIT_IMAGE_SUFFIXES[i];
438             if (request.getParameter(name + suffix) != null) {
439                 return true;
440             }
441         }
442         return false;
443     }
444
445     /**
446      * Return a map containing all parameters with the given prefix.
447      * Maps single values to String and multiple values to String array.
448      * <p>For example, with a prefix of "spring_", "spring_param1" and
449      * "spring_param2" result in a Map with "param1" and "param2" as keys.
450      * <p>Similar to Servlet 2.3's <code>ServletRequest.getParameterMap</code>,
451      * but more flexible and compatible with Servlet 2.2.
452      * @param request HTTP request in which to look for parameters
453      * @param prefix the beginning of parameter names
454      * (if this is null or the empty string, all parameters will match)
455      * @return map containing request parameters <b>without the prefix</b>,
456      * containing either a String or a String array as values
457      * @see javax.servlet.ServletRequest#getParameterNames
458      * @see javax.servlet.ServletRequest#getParameterValues
459      * @see javax.servlet.ServletRequest#getParameterMap
460      */

461     public static Map JavaDoc getParametersStartingWith(ServletRequest JavaDoc request, String JavaDoc prefix) {
462         Assert.notNull(request, "Request must not be null");
463         Enumeration JavaDoc paramNames = request.getParameterNames();
464         Map JavaDoc params = new TreeMap JavaDoc();
465         if (prefix == null) {
466             prefix = "";
467         }
468         while (paramNames != null && paramNames.hasMoreElements()) {
469             String JavaDoc paramName = (String JavaDoc) paramNames.nextElement();
470             if ("".equals(prefix) || paramName.startsWith(prefix)) {
471                 String JavaDoc unprefixed = paramName.substring(prefix.length());
472                 String JavaDoc[] values = request.getParameterValues(paramName);
473                 if (values == null) {
474                     // Do nothing, no values found at all.
475
}
476                 else if (values.length > 1) {
477                     params.put(unprefixed, values);
478                 }
479                 else {
480                     params.put(unprefixed, values[0]);
481                 }
482             }
483         }
484         return params;
485     }
486
487     /**
488      * Extract the URL filename from the given request URL path.
489      * Correctly resolves nested paths such as "/products/view.html" as well.
490      * @param urlPath the request URL path (e.g. "/index.html")
491      * @return the extracted URI filename (e.g. "index")
492      */

493     public static String JavaDoc extractFilenameFromUrlPath(String JavaDoc urlPath) {
494         int begin = urlPath.lastIndexOf('/') + 1;
495         int end = urlPath.indexOf(';');
496         if (end == -1) {
497             end = urlPath.indexOf('?');
498             if (end == -1) {
499                 end = urlPath.length();
500             }
501         }
502         String JavaDoc filename = urlPath.substring(begin, end);
503         int dotIndex = filename.lastIndexOf('.');
504         if (dotIndex != -1) {
505             filename = filename.substring(0, dotIndex);
506         }
507         return filename;
508     }
509
510 }
511
Popular Tags