1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
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 }