portletrequest.java

GridSphere 门户 提供一个基于 portlet 的高级开放源代码门户。GridSphere 是在欧盟提供基金的 GridLab 项目下开发的

/**
 * Copyright 2003 IBM Corporation and Sun Microsystems, Inc.
 * All rights reserved.
 * Use is subject to license terms.
 */
package javax.portlet;

/**
 * The <CODE>PortletRequest</CODE> defines the base interface to provide client
 * request information to a portlet. The portlet container uses two specialized
 * versions of this interface when invoking a portlet, <CODE>ActionRequest</CODE>
 * and <CODE>RenderRequest</CODE>. The portlet container creates these objects and
 * passes them as  arguments to the portlet's <CODE>processAction</CODE> and
 * <CODE>render</CODE> methods.
 *
 * @see ActionRequest
 * @see RenderRequest
 */
public interface PortletRequest {

    /**
     * Used to retrieve user information attributes with the
     * <code>getAttribute</code> call. The user information is returned
     * as a <code>Map</code> object. The portlet must define the
     * user information attribute it is interested in inside the
     * <code>user-attribute</code> section of the deployment descriptor.
     * If an attribute is not supported
     * by the current runtime system it will not show up in the user
     * attribute map.<BR>
     * If the user-attribute is supported by the runtime system, but not
     * defined for a particular user, then for that user the attribute
     * exists in the returned map and the attribute has a <code>null</code> value.
     * <p/>
     * If the user-attribute is not defined for the current user it
     * will not show up in the Map.
     * <p/>
     * The value is <code>javax.portlet.userinfo</code>.
     */
    public static final String USER_INFO = "javax.portlet.userinfo";

    /**
     * String identifier for Basic authentication. Value "BASIC".
     */
    public static final String BASIC_AUTH = "BASIC";

    /**
     * String identifier for Form based authentication. Value "FORM".
     */
    public static final String FORM_AUTH = "FORM";

    /**
     * String identifier for Certification based authentication. Value "CLIENT_CERT".
     */
    public static final String CLIENT_CERT_AUTH = "CLIENT_CERT";

    /**
     * String identifier for Digest based authentication. Value "DIGEST".
     */
    public static final String DIGEST_AUTH = "DIGEST";

    /**
     * Returns true, if the given window state is valid
     * to be set for this portlet in the context
     * of the current request.
     *
     * @param state window state to checked
     * @return true, if it is valid for this portlet
     *         in this request to change to the
     *         given window state
     */
    public boolean isWindowStateAllowed(WindowState state);

    /**
     * Returns true, if the given portlet mode is a valid
     * one to set for this portlet  in the context
     * of the current request.
     *
     * @param mode portlet mode to check
     * @return true, if it is valid for this portlet
     *         in this request to change to the
     *         given portlet mode
     */
    public boolean isPortletModeAllowed(PortletMode mode);

    /**
     * Returns the current portlet mode of the portlet.
     *
     * @return the portlet mode
     */
    public PortletMode getPortletMode();

    /**
     * Returns the current window state of the portlet.
     *
     * @return the window state
     */
    public WindowState getWindowState();

    /**
     * Returns the preferences object associated with the portlet.
     *
     * @return the portlet preferences
     */
    public PortletPreferences getPreferences();

    /**
     * Returns the current portlet session or, if there is no current session,
     * creates one and returns the new session.
     * <p/>
     * Creating a new portlet session will result in creating
     * a new <code>HttpSession</code> on which the portlet session is based on.
     *
     * @return the portlet session
     */
    public PortletSession getPortletSession();


    /**
     * Returns the current portlet session or, if there is no current session
     * and the given flag is <CODE>true</CODE>, creates one and returns
     * the new session.
     * <P>
     * If the given flag is <CODE>false</CODE> and there is no current
     * portlet session, this method returns <CODE>null</CODE>.
     * <p/>
     * Creating a new portlet session will result in creating
     * a new <code>HttpSession</code> on which the portlet session is based on.
     *
     * @param create <CODE>true</CODE> to create a new session, <BR>
     *               <CODE>false</CODE> to return <CODE>null</CODE> if there
     *               is no current session
     * @return the portlet session
     */

    public PortletSession getPortletSession(boolean create);


    /**
     * Returns the value of the specified request property
     * as a <code>String</code>. If the request did not include a property
     * of the specified name, this method returns <code>null</code>.
     * <p/>
     * A portlet can access portal/portlet-container specific properties
     * through this method and, if available, the
     * headers of the HTTP client request.
     * <p/>
     * This method should only be used if the
     * property has only one value. If the property might have
     * more than one value, use {@link #getProperties}.
     * <p/>
     * If this method is used with a multivalued
     * parameter, the value returned is equal to the first value
     * in the Enumeration returned by <code>getProperties</code>.
     *
     * @param name a <code>String</code> specifying the
     *             property name
     * @throws java.lang.IllegalArgumentException
     *          if name is <code>null</code>.
     * @return			a <code>String</code> containing the
     * value of the requested
     * property, or <code>null</code>
     * if the request does not
     * have a property of that name.
     */
    public String getProperty(String name);

    /**
     * Returns all the values of the specified request property
     * as a <code>Enumeration</code> of <code>String</code> objects.
     * <p/>
     * If the request did not include any propertys
     * of the specified name, this method returns an empty
     * <code>Enumeration</code>.
     * The property name is case insensitive. You can use
     * this method with any request property.
     *
     * @param name a <code>String</code> specifying the
     *             property name
     * @throws java.lang.IllegalArgumentException
     *          if name is <code>null</code>.
     * @return		a <code>Enumeration</code> containing
     * the values of the requested property. If
     * the request does not have any properties of
     * that name return an empty <code>Enumeration</code>.
     */
    public java.util.Enumeration getProperties(String name);

    /**
     * Returns a <code>Enumeration</code> of all the property names
     * this request contains. If the request has no
     * properties, this method returns an empty <code>Enumeration</code>.
     *
     * @return			an <code>Enumeration</code> of all the
     * property names sent with this
     * request; if the request has
     * no properties, an empty <code>Enumeration</code>.
     */
    public java.util.Enumeration getPropertyNames();

    /**
     * Returns the context of the calling portal.
     *
     * @return the context of the calling portal
     */
    public PortalContext getPortalContext();

    /**
     * Returns the name of the authentication scheme used for the
     * connection between client and portal,
     * for example, <code>BASIC_AUTH</code>, <code>CLIENT_CERT_AUTH</code>,
     * a custom one or <code>null</code> if there was no authentication.
     *
     * @return		one of the static members <code>BASIC_AUTH</code>,
     * <code>FORM_AUTH</code>, <code>CLIENT_CERT_AUTH</code>,
     * <code>DIGEST_AUTH</code> (suitable for == comparison)
     * indicating the authentication scheme,
     * a custom one, or
     * <code>null</code> if the request was
     * not authenticated.
     */
    public java.lang.String getAuthType();

    /**
     * Returns the context path which is the path prefix associated with the deployed
     * portlet application. If the portlet application is rooted at the
     * base of the web server URL namespace (also known as "default" context),
     * this path must be an empty string. Otherwise, it must be the path the
     * portlet application is rooted to, the path must start with a '/' and
     * it must not end with a '/' character.
     * <p/>
     * To encode a URL the {@link PortletResponse#encodeURL} method must be used.
     *
     * @return		a <code>String</code> specifying the
     * portion of the request URL that indicates the context
     * of the request
     * @see PortletResponse#encodeURL
     */
    public String getContextPath();

    /**
     * Returns the login of the user making this request, if the user
     * has been authenticated, or null if the user has not been authenticated.
     *
     * @return		a <code>String</code> specifying the login
     * of the user making this request, or <code>null</code>
     * if the user login is not known.
     */
    public java.lang.String getRemoteUser();

    /**
     * Returns a java.security.Principal object containing the name of the
     * current authenticated user.
     *
     * @return		a <code>java.security.Principal</code> containing
     * the name of the user making this request, or
     * <code>null</code> if the user has not been
     * authenticated.
     */
    public java.security.Principal getUserPrincipal();

    /**
     * Returns a boolean indicating whether the authenticated user is
     * included in the specified logical "role".  Roles and role membership can be
     * defined using deployment descriptors.  If the user has not been
     * authenticated, the method returns <code>false</code>.
     *
     * @param role a <code>String</code> specifying the name
     *             of the role
     * @return		a <code>boolean</code> indicating whether
     * the user making this request belongs to a given role;
     * <code>false</code> if the user has not been
     * authenticated.
     */