Home » gridsphere-3.1-src » javax.portlet » [javadoc | source]

    1   /**
    2    * Copyright 2003 IBM Corporation and Sun Microsystems, Inc.
    3    * All rights reserved.
    4    * Use is subject to license terms.
    5    */
    6   
    7   package javax.portlet;
    8   
    9   
   10   /**
   11    * The <CODE>PortletContext</CODE> interface defines a portlet view
   12    * of the portlet container.
   13    * The <CODE>PortletContext</CODE> also makes resources available
   14    * to the portlet. Using the context, a portlet can access
   15    * the portlet log, and obtain URL references to resources.
   16    * <p/>
   17    * <p>There is one context per "portlet application" per Java Virtual Machine.  (A
   18    * "portlet application" is a collection of portlets, servlets, and content installed
   19    * under a specific subset of the server URL namespace, such as <code>/catalog</code>.
   20    * They are possibly installed via a <code>.war</code> file.)
   21    * As a web application, a portlet application also has a servlet context.
   22    * The portlet context leverages most of its functionality from the
   23    * servlet context of the portlet application.
   24    * <p/>
   25    * Attibutes stored in the context are global for <I>all</I> users and <I>all</I>
   26    * components in the portlet application.
   27    * <p/>
   28    * In the case of a web
   29    * application marked "distributed" in its deployment descriptor, there will
   30    * be one context instance for each virtual machine.  In this situation, the
   31    * context cannot be used as a location to share global information (because
   32    * the information is not truly global). Use an external resource, such as
   33    * a database to achieve sharing on a global scope.
   34    */
   35   public interface PortletContext {
   36   
   37       /**
   38        * Returns the name and version of the portlet container in which the
   39        * portlet is running.
   40        * <p/>
   41        * <P>
   42        * The form of the returned string is <code>containername/versionnumber</code>.
   43        *
   44        * @return the string containing at least name and version number
   45        */
   46   
   47       public String getServerInfo();
   48   
   49       /**
   50        * Returns a {@link PortletRequestDispatcher} object that acts
   51        * as a wrapper for the resource located at the given path.
   52        * A <code>PortletRequestDispatcher</code> object can be used include the
   53        * resource in a response. The resource can be dynamic or static.
   54        * <p/>
   55        * <p>The pathname must begin with a slash (<code> / </code>) and is interpreted as relative
   56        * to the current context root.
   57        * <p/>
   58        * <p>This method returns <code>null</code> if the <code>PortletContext</code>
   59        * cannot return a <code>PortletRequestDispatcher</code>
   60        * for any reason.
   61        *
   62        * @param path a <code>String</code> specifying the pathname
   63        *             to the resource
   64        * @return a <code>PortletRequestDispatcher</code> object
   65        *         that acts as a wrapper for the resource
   66        *         at the specified path.
   67        * @see PortletRequestDispatcher
   68        */
   69   
   70       public PortletRequestDispatcher getRequestDispatcher(String path);
   71   
   72   
   73       /**
   74        * Returns a {@link PortletRequestDispatcher} object that acts
   75        * as a wrapper for the named servlet.
   76        * <p/>
   77        * <p>Servlets (and also JSP pages) may be given names via server
   78        * administration or via a web application deployment descriptor.
   79        * <p/>
   80        * <p>This method returns <code>null</code> if the
   81        * <code>PortletContext</code> cannot return a
   82        * <code>PortletRequestDispatcher</code> for any reason.
   83        *
   84        * @param name a <code>String</code> specifying the name
   85        *             of a servlet to be wrapped
   86        * @return a <code>PortletRequestDispatcher</code> object
   87        *         that acts as a wrapper for the named servlet
   88        * @see PortletRequestDispatcher
   89        */
   90   
   91       public PortletRequestDispatcher getNamedDispatcher(String name);
   92   
   93   
   94       /**
   95        * Returns the resource located at the given path as an InputStream object.
   96        * The data in the InputStream can be of any type or length. The method returns
   97        * null if no resource exists at the given path.
   98        * <p/>
   99        * In order to access protected resources the path has to be prefixed with
  100        * <code>/WEB-INF/</code> (for example <code>/WEB-INF/myportlet/myportlet.jsp</code>).
  101        * Otherwise, the direct path is used
  102        * (for example <code>/myportlet/myportlet.jsp</code>).
  103        *
  104        * @param path the path to the resource
  105        * @return the input stream
  106        */
  107       public java.io.InputStream getResourceAsStream(String path);
  108   
  109   
  110       /**
  111        * Returns the major version of the Portlet API that this portlet
  112        * container supports.
  113        *
  114        * @return the major version
  115        * @see #getMinorVersion()
  116        */
  117   
  118       public int getMajorVersion();
  119   
  120   
  121       /**
  122        * Returns the minor version of the Portlet API that this portlet
  123        * container supports.
  124        *
  125        * @return the minor version
  126        * @see #getMajorVersion()
  127        */
  128   
  129       public int getMinorVersion();
  130   
  131   
  132       /**
  133        * Returns the MIME type of the specified file, or <code>null</code> if
  134        * the MIME type is not known. The MIME type is determined
  135        * by the configuration of the portlet container and may be specified
  136        * in a web application deployment descriptor. Common MIME
  137        * types are <code>text/html</code> and <code>image/gif</code>.
  138        *
  139        * @param file a <code>String</code> specifying the name
  140        *             of a file
  141        * @return a <code>String</code> specifying the MIME type of the file
  142        */
  143   
  144       public String getMimeType(String file);
  145   
  146   
  147       /**
  148        * Returns a <code>String</code> containing the real path
  149        * for a given virtual path. For example, the path <code>/index.html</code>
  150        * returns the absolute file path of the portlet container file system.
  151        * <p/>
  152        * <p>The real path returned will be in a form
  153        * appropriate to the computer and operating system on
  154        * which the portlet container is running, including the
  155        * proper path separators. This method returns <code>null</code>
  156        * if the portlet container cannot translate the virtual path
  157        * to a real path for any reason (such as when the content is
  158        * being made available from a <code>.war</code> archive).
  159        *
  160        * @param path a <code>String</code> specifying a virtual path
  161        * @return a <code>String</code> specifying the real path,
  162        *         or null if the transformation cannot be performed.
  163        */
  164   
  165       public String getRealPath(String path);
  166   
  167   
  168       /**
  169        * Returns a directory-like listing of all the paths to resources within
  170        * the web application longest sub-path of which
  171        * matches the supplied path argument. Paths indicating subdirectory paths
  172        * end with a slash (<code>/</code>). The returned paths are all
  173        * relative to the root of the web application and have a leading slash.
  174        * For example, for a web application
  175        * containing<br><br>
  176        * <code>
  177        * /welcome.html<br>
  178        * /catalog/index.html<br>
  179        * /catalog/products.html<br>
  180        * /catalog/offers/books.html<br>
  181        * /catalog/offers/music.html<br>
  182        * /customer/login.jsp<br>
  183        * /WEB-INF/web.xml<br>
  184        * /WEB-INF/classes/com.acme.OrderPortlet.class,<br><br>
  185        * </code>
  186        * <p/>
  187        * <code>getResourcePaths("/")</code> returns
  188        * <code>{"/welcome.html", "/catalog/", "/customer/", "/WEB-INF/"}</code><br>
  189        * <code>getResourcePaths("/catalog/")</code> returns
  190        * <code>{"/catalog/index.html", "/catalog/products.html", "/catalog/offers/"}</code>.<br>
  191        *
  192        * @param path the partial path used to match the resources, which must start with a slash
  193        * @return a Set containing the directory listing, or <code>null</code> if there
  194        *         are no resources in the web application of which the path
  195        *         begins with the supplied path.
  196        */
  197   
  198       public java.util.Set getResourcePaths(String path);
  199   
  200   
  201       /**
  202        * Returns a URL to the resource that is mapped to a specified
  203        * path. The path must begin with a slash (<code>/</code>) and is interpreted
  204        * as relative to the current context root.
  205        * <p/>
  206        * <p>This method allows the portlet container to make a resource
  207        * available to portlets from any source. Resources
  208        * can be located on a local or remote
  209        * file system, in a database, or in a <code>.war</code> file.
  210        * <p/>
  211        * <p>The portlet container must implement the URL handlers
  212        * and <code>URLConnection</code> objects that are necessary
  213        * to access the resource.
  214        * <p/>
  215        * <p>This method returns <code>null</code>
  216        * if no resource is mapped to the pathname.
  217        * <p/>
  218        * <p>Some containers may allow writing to the URL returned by
  219        * this method using the methods of the URL class.
  220        * <p/>
  221        * <p>The resource content is returned directly, so be aware that
  222        * requesting a <code>.jsp</code> page returns the JSP source code.
  223        * Use a <code>RequestDispatcher</code> instead to include results of
  224        * an execution.
  225        * <p/>
  226        * <p>This method has a different purpose than
  227        * <code>java.lang.Class.getResource</code>,
  228        * which looks up resources based on a class loader. This
  229        * method does not use class loaders.
  230        *
  231        * @param path a <code>String</code> specifying
  232        *             the path to the resource
  233        * @return the resource located at the named path,
  234        *         or <code>null</code> if there is no resource
  235        *         at that path
  236        * @throws java.net.MalformedURLException if the pathname is not given in
  237        *                                        the correct form
  238        */
  239   
  240       public java.net.URL getResource(String path) throws java.net.MalformedURLException;
  241   
  242   
  243       /**
  244        * Returns the portlet container attribute with the given name,
  245        * or null if there is no attribute by that name.
  246        * An attribute allows a portlet container to give the
  247        * portlet additional information not
  248        * already provided by this interface.
  249        * A list of supported attributes can be retrieved using
  250        * <code>getAttributeNames</code>.
  251        * <p/>
  252        * <p>The attribute is returned as a <code>java.lang.Object</code>
  253        * or some subclass.
  254        * Attribute names should follow the same convention as package
  255        * names. The Java Portlet API specification reserves names
  256        * matching <code>java.*</code>, <code>javax.*</code>,
  257        * and <code>sun.*</code>.
  258        *
  259        * @param name a <code>String</code> specifying the name
  260        *             of the attribute
  261        * @return an <code>Object</code> containing the value
  262        *         of the attribute, or <code>null</code>
  263        *         if no attribute exists matching the given
  264        *         name
  265        * @exception	java.lang.IllegalArgumentException if name is <code>null</code>.
  266        * @see #getAttributeNames
  267        */
  268   
  269       public java.lang.Object getAttribute(java.lang.String name);
  270   
  271   
  272       /**
  273        * Returns an <code>Enumeration</code> containing the attribute names
  274        * available within this portlet context, or an emtpy
  275        * <code>Enumeration</code> if no attributes are available. Use the
  276        * {@link #getAttribute} method with an attribute name
  277        * to get the value of an attribute.
  278        *
  279        * @return an <code>Enumeration</code> of attribute names
  280        * @see		#getAttribute
  281        */
  282   
  283       public java.util.Enumeration getAttributeNames();
  284   
  285   
  286       /**
  287        * Returns a String containing the value of the named context-wide
  288        * initialization parameter, or <code>null</code> if the parameter does not exist.
  289        * This method provides configuration information which may be useful for
  290        * an entire "portlet application".
  291        *
  292        * @return a <code>String</code> containing the value
  293        *         of the initialization parameter, or
  294        *         <code>null</code> if the parameter does not exist.
  295        * @param	name	a <code>String</code> containing the name of the
  296        * requested parameter
  297        * @exception	java.lang.IllegalArgumentException if name is <code>null</code>.
  298        * @see #getInitParameterNames
  299        */
  300   
  301       public java.lang.String getInitParameter(java.lang.String name);
  302   
  303   
  304       /**
  305        * Returns the names of the context initialization parameters as an
  306        * <code>Enumeration</code> of String objects, or an empty Enumeration if the context
  307        * has no initialization parameters.
  308        *
  309        * @return an <code>Enumeration</code> of <code>String</code>
  310        *         objects containing the names of the context
  311        *         initialization parameters
  312        * @see #getInitParameter
  313        */
  314   
  315       public java.util.Enumeration getInitParameterNames();
  316   
  317   
  318       /**
  319        * Writes the specified message to a portlet log file, usually an event log.
  320        * The name and type of the portlet log file is specific to the portlet container.
  321        * <p/>
  322        * This method mapps to the <code>ServletContext.log</code> method.
  323        * The portlet container may in addition log this message in a
  324        * portlet container specific log file.
  325        *
  326        * @param msg a <code>String</code> specifying the
  327        *            message to be written to the log file
  328        */
  329   
  330       public void log(java.lang.String msg);
  331   
  332   
  333       /**
  334        * Writes an explanatory message and a stack trace for a given
  335        * Throwable exception to the portlet log file.
  336        * The name and type of the portlet log file is specific to the
  337        * portlet container, usually an event log.
  338        * <p/>
  339        * This method is mapped to the <code>ServletContext.log</code> method.
  340        * The portlet container may in addition log this message in a
  341        * portlet container specific log file.
  342        *
  343        * @param message   a <code>String</code> that
  344        *                  describes the error or exception
  345        * @param throwable the <code>Throwable</code> error
  346        *                  or exception
  347        */
  348   
  349       public void log(java.lang.String message, java.lang.Throwable throwable);
  350   
  351   
  352       /**
  353        * Removes the attribute with the given name from the portlet context.
  354        * After removal, subsequent calls to
  355        * {@link #getAttribute} to retrieve the attribute's value
  356        * will return <code>null</code>.
  357        *
  358        * @param name a <code>String</code> specifying the name
  359        *             of the attribute to be removed
  360        * @exception	java.lang.IllegalArgumentException if name is <code>null</code>.
  361        */
  362   
  363       public void removeAttribute(java.lang.String name);
  364   
  365   
  366       /**
  367        * Binds an object to a given attribute name in this portlet context.
  368        * If the name specified is already used for an attribute, this method
  369        * removes the old attribute and binds the name to the new attribute.
  370        * <p/>
  371        * If a null value is passed, the effect is the same as calling
  372        * <code>removeAttribute()</code>.
  373        * <p/>
  374        * <p>Attribute names should follow the same convention as package
  375        * names. The Java Portlet API specification reserves names
  376        * matching <code>java.*</code>, <code>javax.*</code>, and
  377        * <code>sun.*</code>.
  378        *
  379        * @param name   a <code>String</code> specifying the name
  380        *               of the attribute
  381        * @param object an <code>Object</code> representing the
  382        *               attribute to be bound
  383        * @exception	java.lang.IllegalArgumentException if name is <code>null</code>.
  384        */
  385   
  386       public void setAttribute(java.lang.String name, java.lang.Object object);
  387   
  388   
  389       /**
  390        * Returns the name of this portlet application correponding to this PortletContext as specified
  391        * in the <code>web.xml</code> deployment descriptor for this web application by the
  392        * <code>display-name</code> element.
  393        *
  394        * @return The name of the web application or null if no name has been declared in the deployment descriptor.
  395        */
  396   
  397       public String getPortletContextName();
  398   
  399   }

Home » gridsphere-3.1-src » javax.portlet » [javadoc | source]