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 }