portletcontext.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>PortletContext</CODE> interface defines a portlet view
 * of the portlet container.
 * The <CODE>PortletContext</CODE> also makes resources available
 * to the portlet. Using the context, a portlet can access
 * the portlet log, and obtain URL references to resources.
 * <p/>
 * <p>There is one context per "portlet application" per Java Virtual Machine.  (A
 * "portlet application" is a collection of portlets, servlets, and content installed
 * under a specific subset of the server URL namespace, such as <code>/catalog</code>.
 * They are possibly installed via a <code>.war</code> file.)
 * As a web application, a portlet application also has a servlet context.
 * The portlet context leverages most of its functionality from the
 * servlet context of the portlet application.
 * <p/>
 * Attibutes stored in the context are global for <I>all</I> users and <I>all</I>
 * components in the portlet application.
 * <p/>
 * In the case of a web
 * application marked "distributed" in its deployment descriptor, there will
 * be one context instance for each virtual machine.  In this situation, the
 * context cannot be used as a location to share global information (because
 * the information is not truly global). Use an external resource, such as
 * a database to achieve sharing on a global scope.
 */
public interface PortletContext {

    /**
     * Returns the name and version of the portlet container in which the
     * portlet is running.
     * <p/>
     * <P>
     * The form of the returned string is <code>containername/versionnumber</code>.
     *
     * @return the string containing at least name and version number
     */

    public String getServerInfo();

    /**
     * Returns a {@link PortletRequestDispatcher} object that acts
     * as a wrapper for the resource located at the given path.
     * A <code>PortletRequestDispatcher</code> object can be used include the
     * resource in a response. The resource can be dynamic or static.
     * <p/>
     * <p>The pathname must begin with a slash (<code> / </code>) and is interpreted as relative
     * to the current context root.
     * <p/>
     * <p>This method returns <code>null</code> if the <code>PortletContext</code>
     * cannot return a <code>PortletRequestDispatcher</code>
     * for any reason.
     *
     * @param path a <code>String</code> specifying the pathname
     *             to the resource
     * @return a <code>PortletRequestDispatcher</code> object
     *         that acts as a wrapper for the resource
     *         at the specified path.
     * @see PortletRequestDispatcher
     */

    public PortletRequestDispatcher getRequestDispatcher(String path);


    /**
     * Returns a {@link PortletRequestDispatcher} object that acts
     * as a wrapper for the named servlet.
     * <p/>
     * <p>Servlets (and also JSP pages) may be given names via server
     * administration or via a web application deployment descriptor.
     * <p/>
     * <p>This method returns <code>null</code> if the
     * <code>PortletContext</code> cannot return a
     * <code>PortletRequestDispatcher</code> for any reason.
     *
     * @param name a <code>String</code> specifying the name
     *             of a servlet to be wrapped
     * @return a <code>PortletRequestDispatcher</code> object
     *         that acts as a wrapper for the named servlet
     * @see PortletRequestDispatcher
     */

    public PortletRequestDispatcher getNamedDispatcher(String name);


    /**
     * Returns the resource located at the given path as an InputStream object.
     * The data in the InputStream can be of any type or length. The method returns
     * null if no resource exists at the given path.
     * <p/>
     * In order to access protected resources the path has to be prefixed with
     * <code>/WEB-INF/</code> (for example <code>/WEB-INF/myportlet/myportlet.jsp</code>).
     * Otherwise, the direct path is used
     * (for example <code>/myportlet/myportlet.jsp</code>).
     *
     * @param path the path to the resource
     * @return the input stream
     */
    public java.io.InputStream getResourceAsStream(String path);


    /**
     * Returns the major version of the Portlet API that this portlet
     * container supports.
     *
     * @return the major version
     * @see #getMinorVersion()
     */

    public int getMajorVersion();


    /**
     * Returns the minor version of the Portlet API that this portlet
     * container supports.
     *
     * @return the minor version
     * @see #getMajorVersion()
     */

    public int getMinorVersion();


    /**
     * Returns the MIME type of the specified file, or <code>null</code> if
     * the MIME type is not known. The MIME type is determined
     * by the configuration of the portlet container and may be specified
     * in a web application deployment descriptor. Common MIME
     * types are <code>text/html</code> and <code>image/gif</code>.
     *
     * @param file a <code>String</code> specifying the name
     *             of a file
     * @return a <code>String</code> specifying the MIME type of the file
     */

    public String getMimeType(String file);


    /**
     * Returns a <code>String</code> containing the real path
     * for a given virtual path. For example, the path <code>/index.html</code>
     * returns the absolute file path of the portlet container file system.
     * <p/>
     * <p>The real path returned will be in a form
     * appropriate to the computer and operating system on
     * which the portlet container is running, including the
     * proper path separators. This method returns <code>null</code>
     * if the portlet container cannot translate the virtual path
     * to a real path for any reason (such as when the content is
     * being made available from a <code>.war</code> archive).
     *
     * @param path a <code>String</code> specifying a virtual path
     * @return a <code>String</code> specifying the real path,
     *         or null if the transformation cannot be performed.
     */

    public String getRealPath(String path);


    /**
     * Returns a directory-like listing of all the paths to resources within
     * the web application longest sub-path of which
     * matches the supplied path argument. Paths indicating subdirectory paths
     * end with a slash (<code>/</code>). The returned paths are all
     * relative to the root of the web application and have a leading slash.
     * For example, for a web application
     * containing<br><br>
     * <code>
     * /welcome.html<br>
     * /catalog/index.html<br>
     * /catalog/products.html<br>
     * /catalog/offers/books.html<br>
     * /catalog/offers/music.html<br>
     * /customer/login.jsp<br>
     * /WEB-INF/web.xml<br>
     * /WEB-INF/classes/com.acme.OrderPortlet.class,<br><br>
     * </code>
     * <p/>
     * <code>getResourcePaths("/")</code> returns
     * <code>{"/welcome.html", "/catalog/", "/customer/", "/WEB-INF/"}</code><br>
     * <code>getResourcePaths("/catalog/")</code> returns
     * <code>{"/catalog/index.html", "/catalog/products.html", "/catalog/offers/"}</code>.<br>
     *
     * @param path the partial path used to match the resources, which must start with a slash
     * @return a Set containing the directory listing, or <code>null</code> if there
     *         are no resources in the web application of which the path
     *         begins with the supplied path.
     */

    public java.util.Set getResourcePaths(String path);