portletutils.java

spring api 源代码

/*
 * Copyright 2002-2007 the original author or authors.
 *
 * 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 org.springframework.web.portlet.util;

import java.io.File;
import java.io.FileNotFoundException;
import java.util.Enumeration;
import java.util.HashMap;
import java.util.Iterator;
import java.util.Map;
import java.util.TreeMap;

import javax.portlet.ActionRequest;
import javax.portlet.ActionResponse;
import javax.portlet.PortletContext;
import javax.portlet.PortletRequest;
import javax.portlet.PortletSession;

import org.springframework.util.Assert;
import org.springframework.web.util.WebUtils;

/**
 * Miscellaneous utilities for portlet applications.
 * Used by various framework classes.
 *
 * @author Juergen Hoeller
 * @author William G. Thompson, Jr.
 * @author John A. Lewis
 * @since 2.0
 */
public abstract class PortletUtils {

	/**
	 * Return the temporary directory for the current web application,
	 * as provided by the portlet container.
	 * @param portletContext the portlet context of the web application
	 * @return the File representing the temporary directory
	 * @throws IllegalArgumentException if the supplied <code>portletContext</code> is <code>null</code>
	 */
	public static File getTempDir(PortletContext portletContext) {
		Assert.notNull(portletContext, "PortletContext must not be null");
		return (File) portletContext.getAttribute(WebUtils.TEMP_DIR_CONTEXT_ATTRIBUTE);
	}

	/**
	 * Return the real path of the given path within the web application,
	 * as provided by the portlet container.
	 * <p>Prepends a slash if the path does not already start with a slash,
	 * and throws a {@link java.io.FileNotFoundException} if the path cannot
	 * be resolved to a resource (in contrast to
	 * {@link javax.portlet.PortletContext#getRealPath PortletContext's <code>getRealPath</code>},
	 * which simply returns <code>null</code>).
	 * @param portletContext the portlet context of the web application
	 * @param path the relative path within the web application
	 * @return the corresponding real path
	 * @throws FileNotFoundException if the path cannot be resolved to a resource
	 * @throws IllegalArgumentException if the supplied <code>portletContext</code> is <code>null</code>
	 * @throws NullPointerException if the supplied <code>path</code> is <code>null</code>
	 * @see javax.portlet.PortletContext#getRealPath
	 */
	public static String getRealPath(PortletContext portletContext, String path) throws FileNotFoundException {
		Assert.notNull(portletContext, "PortletContext must not be null");
		// Interpret location as relative to the web application root directory.
		if (!path.startsWith("/")) {
			path = "/" + path;
		}
		String realPath = portletContext.getRealPath(path);
		if (realPath == null) {
			throw new FileNotFoundException(
					"PortletContext resource [" + path + "] cannot be resolved to absolute file path - " +
					"web application archive not expanded?");
		}
		return realPath;
	}


	/**
	 * Check the given request for a session attribute of the given name under the
	 * {@link javax.portlet.PortletSession#PORTLET_SCOPE}.
	 * Returns <code>null</code> if there is no session or if the session has no such attribute in that scope.
	 * Does not create a new session if none has existed before!
	 * @param request current portlet request
	 * @param name the name of the session attribute
	 * @return the value of the session attribute, or <code>null</code> if not found
	 * @throws IllegalArgumentException if the supplied <code>request</code> is <code>null</code>
	 */
	public static Object getSessionAttribute(PortletRequest request, String name) {
		return getSessionAttribute(request, name, PortletSession.PORTLET_SCOPE);
	}

	/**
	 * Check the given request for a session attribute of the given name in the given scope.
	 * Returns <code>null</code> if there is no session or if the session has no such attribute in that scope.
	 * Does not create a new session if none has existed before!
	 * @param request current portlet request
	 * @param name the name of the session attribute
	 * @param scope session scope of this attribute
	 * @return the value of the session attribute, or <code>null</code> if not found
	 * @throws IllegalArgumentException if the supplied <code>request</code> is <code>null</code>
	 */
	public static Object getSessionAttribute(PortletRequest request, String name, int scope) {
		Assert.notNull(request, "Request must not be null");
		PortletSession session = request.getPortletSession(false);
		return (session != null ? session.getAttribute(name, scope) : null);
	}

	/**
	 * Check the given request for a session attribute of the given name under the {@link javax.portlet.PortletSession#PORTLET_SCOPE}.
	 * Throws an exception if there is no session or if the session has no such attribute in that scope.
	 * Does not create a new session if none has existed before!
	 * @param request current portlet request
	 * @param name the name of the session attribute
	 * @return the value of the session attribute
	 * @throws IllegalStateException if the session attribute could not be found
	 * @throws IllegalArgumentException if the supplied <code>request</code> is <code>null</code>
	 */
	public static Object getRequiredSessionAttribute(PortletRequest request, String name)
			throws IllegalStateException {
		return getRequiredSessionAttribute(request, name, PortletSession.PORTLET_SCOPE);
	}

	/**
	 * Check the given request for a session attribute of the given name in the given scope.
	 * Throws an exception if there is no session or if the session has no such attribute in that scope.
	 * Does not create a new session if none has existed before!
	 * @param request current portlet request
	 * @param name the name of the session attribute
	 * @param scope session scope of this attribute
	 * @return the value of the session attribute
	 * @throws IllegalStateException if the session attribute could not be found
	 * @throws IllegalArgumentException if the supplied <code>request</code> is <code>null</code>
	 */
	public static Object getRequiredSessionAttribute(PortletRequest request, String name, int scope)
			throws IllegalStateException {
		Object attr = getSessionAttribute(request, name, scope);
		if (attr == null) {
			throw new IllegalStateException("No session attribute '" + name + "' found");
		}
		return attr;
	}

	/**
	 * Set the session attribute with the given name to the given value under the {@link javax.portlet.PortletSession#PORTLET_SCOPE}.
	 * Removes the session attribute if value is <code>null</code>, if a session existed at all.
	 * Does not create a new session if not necessary!
	 * @param request current portlet request
	 * @param name the name of the session attribute
	 * @param value the value of the session attribute
	 * @throws IllegalArgumentException if the supplied <code>request</code> is <code>null</code>
	 */
	public static void setSessionAttribute(PortletRequest request, String name, Object value) {
		setSessionAttribute(request, name, value, PortletSession.PORTLET_SCOPE);
	}

	/**
	 * Set the session attribute with the given name to the given value in the given scope.
	 * Removes the session attribute if value is <code>null</code>, if a session existed at all.
	 * Does not create a new session if not necessary!
	 * @param request current portlet request
	 * @param name the name of the session attribute
	 * @param value the value of the session attribute
	 * @param scope session scope of this attribute
	 * @throws IllegalArgumentException if the supplied <code>request</code> is <code>null</code>
	 */
	public static void setSessionAttribute(PortletRequest request, String name, Object value, int scope) {
		Assert.notNull(request, "Request must not be null");
		if (value != null) {
			request.getPortletSession().setAttribute(name, value, scope);
		}
		else {
			PortletSession session = request.getPortletSession(false);
			if (session != null) {
				session.removeAttribute(name, scope);
			}
		}
	}

	/**
	 * Get the specified session attribute under the {@link javax.portlet.PortletSession#PORTLET_SCOPE},
	 * creating and setting a new attribute if no existing found. The given class 
	 * needs to have a public no-arg constructor.
	 * Useful for on-demand state objects in a web tier, like shopping carts.
	 * @param session current portlet session
	 * @param name the name of the session attribute
	 * @param clazz the class to instantiate for a new attribute
	 * @return the value of the session attribute, newly created if not found
	 * @throws IllegalArgumentException if the session attribute could not be instantiated; or if the supplied <code>session</code> argument is <code>null</code>
	 */
	public static Object getOrCreateSessionAttribute(PortletSession session, String name, Class clazz)
			throws IllegalArgumentException {
		return getOrCreateSessionAttribute(session, name, clazz, PortletSession.PORTLET_SCOPE);
	}

	/**
	 * Get the specified session attribute in the given scope,
	 * creating and setting a new attribute if no existing found. The given class