View Javadoc

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