PortletContext


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