portletcontext.java.svn-base

portal越来越流行了

/*  Licensed to the Apache Software Foundation (ASF) under one
 *  or more contributor license agreements.  See the NOTICE file
 *  distributed with this work for additional information
 *  regarding copyright ownership.  The ASF licenses this file
 *  to you 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.
 */
/*
 * NOTE: this source code is based on an early draft version of JSR 286 and not intended for product
 * implementations. This file may change or vanish in the final version of the JSR 286 specification.
 */
/*
 * This source code implements specifications defined by the Java
 * Community Process. In order to remain compliant with the specification
 * DO NOT add / change / or delete method signatures!
 */
/**
  * Copyright 2006 IBM Corporation.
  */

package javax.portlet;

import java.net.MalformedURLException;




/**
 * 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>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>
 * Attributes 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>
   * 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>The pathname must begin with a slash (<code> / </code>) and is interpreted as relative
   * to the current context root.
   * 
   * <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>Servlets (and also JSP pages) may be given names via server 
   * administration or via a web application deployment descriptor.
   *
   * <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>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>
   *
   * <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