001: /**
002: * Copyright 2003 IBM Corporation and Sun Microsystems, Inc.
003: * All rights reserved.
004: * Use is subject to license terms.
005: */package javax.portlet;
006:
007: /**
008: * The <CODE>PortletContext</CODE> interface defines a portlet view
009: * of the portlet container.
010: * The <CODE>PortletContext</CODE> also makes resources available
011: * to the portlet. Using the context, a portlet can access
012: * the portlet log, and obtain URL references to resources.
013: *
014: * <p>There is one context per "portlet application" per Java Virtual Machine. (A
015: * "portlet application" is a collection of portlets, servlets, and content installed
016: * under a specific subset of the server URL namespace, such as <code>/catalog</code>.
017: * They are possibly installed via a <code>.war</code> file.)
018: * As a web application, a portlet application also has a servlet context.
019: * The portlet context leverages most of its functionality from the
020: * servlet context of the portlet application.
021: * <p>
022: * Attibutes stored in the context are global for <I>all</I> users and <I>all</I>
023: * components in the portlet application.
024: * <p>
025: * In the case of a web
026: * application marked "distributed" in its deployment descriptor, there will
027: * be one context instance for each virtual machine. In this situation, the
028: * context cannot be used as a location to share global information (because
029: * the information is not truly global). Use an external resource, such as
030: * a database to achieve sharing on a global scope.
031: */
032: public interface PortletContext {
033:
034: /**
035: * Returns the name and version of the portlet container in which the
036: * portlet is running.
037: *
038: * <P>
039: * The form of the returned string is <code>containername/versionnumber</code>.
040: *
041: *
042: * @return the string containing at least name and version number
043: */
044:
045: public String getServerInfo();
046:
047: /**
048: * Returns a {@link PortletRequestDispatcher} object that acts
049: * as a wrapper for the resource located at the given path.
050: * A <code>PortletRequestDispatcher</code> object can be used include the
051: * resource in a response. The resource can be dynamic or static.
052: *
053: * <p>The pathname must begin with a slash (<code> / </code>) and is interpreted as relative
054: * to the current context root.
055: *
056: * <p>This method returns <code>null</code> if the <code>PortletContext</code>
057: * cannot return a <code>PortletRequestDispatcher</code>
058: * for any reason.
059: *
060: *
061: * @param path a <code>String</code> specifying the pathname
062: * to the resource
063: * @return a <code>PortletRequestDispatcher</code> object
064: * that acts as a wrapper for the resource
065: * at the specified path.
066: * @see PortletRequestDispatcher
067: */
068:
069: public PortletRequestDispatcher getRequestDispatcher(String path);
070:
071: /**
072: * Returns a {@link PortletRequestDispatcher} object that acts
073: * as a wrapper for the named servlet.
074: *
075: * <p>Servlets (and also JSP pages) may be given names via server
076: * administration or via a web application deployment descriptor.
077: *
078: * <p>This method returns <code>null</code> if the
079: * <code>PortletContext</code> cannot return a
080: * <code>PortletRequestDispatcher</code> for any reason.
081: *
082: *
083: * @param name a <code>String</code> specifying the name
084: * of a servlet to be wrapped
085: *
086: * @return a <code>PortletRequestDispatcher</code> object
087: * that acts as a wrapper for the named servlet
088: *
089: * @see PortletRequestDispatcher
090: *
091: */
092:
093: public PortletRequestDispatcher getNamedDispatcher(String name);
094:
095: /**
096: * Returns the resource located at the given path as an InputStream object.
097: * The data in the InputStream can be of any type or length. The method returns
098: * null if no resource exists at the given path.
099: * <p>
100: * In order to access protected resources the path has to be prefixed with
101: * <code>/WEB-INF/</code> (for example <code>/WEB-INF/myportlet/myportlet.jsp</code>).
102: * Otherwise, the direct path is used
103: * (for example <code>/myportlet/myportlet.jsp</code>).
104: *
105: * @param path the path to the resource
106: *
107: * @return the input stream
108: */
109: public java.io.InputStream getResourceAsStream(String path);
110:
111: /**
112: * Returns the major version of the Portlet API that this portlet
113: * container supports.
114: *
115: * @return the major version
116: *
117: * @see #getMinorVersion()
118: */
119:
120: public int getMajorVersion();
121:
122: /**
123: * Returns the minor version of the Portlet API that this portlet
124: * container supports.
125: *
126: * @return the minor version
127: *
128: * @see #getMajorVersion()
129: */
130:
131: public int getMinorVersion();
132:
133: /**
134: * Returns the MIME type of the specified file, or <code>null</code> if
135: * the MIME type is not known. The MIME type is determined
136: * by the configuration of the portlet container and may be specified
137: * in a web application deployment descriptor. Common MIME
138: * types are <code>text/html</code> and <code>image/gif</code>.
139: *
140: *
141: * @param file a <code>String</code> specifying the name
142: * of a file
143: *
144: * @return a <code>String</code> specifying the MIME type of the file
145: *
146: */
147:
148: public String getMimeType(String file);
149:
150: /**
151: * Returns a <code>String</code> containing the real path
152: * for a given virtual path. For example, the path <code>/index.html</code>
153: * returns the absolute file path of the portlet container file system.
154: *
155: * <p>The real path returned will be in a form
156: * appropriate to the computer and operating system on
157: * which the portlet container is running, including the
158: * proper path separators. This method returns <code>null</code>
159: * if the portlet container cannot translate the virtual path
160: * to a real path for any reason (such as when the content is
161: * being made available from a <code>.war</code> archive).
162: *
163: * @param path a <code>String</code> specifying a virtual path
164: *
165: * @return a <code>String</code> specifying the real path,
166: * or null if the transformation cannot be performed.
167: */
168:
169: public String getRealPath(String path);
170:
171: /**
172: * Returns a directory-like listing of all the paths to resources within
173: * the web application longest sub-path of which
174: * matches the supplied path argument. Paths indicating subdirectory paths
175: * end with a slash (<code>/</code>). The returned paths are all
176: * relative to the root of the web application and have a leading slash.
177: * For example, for a web application
178: * containing<br><br>
179: * <code>
180: * /welcome.html<br>
181: * /catalog/index.html<br>
182: * /catalog/products.html<br>
183: * /catalog/offers/books.html<br>
184: * /catalog/offers/music.html<br>
185: * /customer/login.jsp<br>
186: * /WEB-INF/web.xml<br>
187: * /WEB-INF/classes/com.acme.OrderPortlet.class,<br><br>
188: * </code>
189: *
190: * <code>getResourcePaths("/")</code> returns
191: * <code>{"/welcome.html", "/catalog/", "/customer/", "/WEB-INF/"}</code><br>
192: * <code>getResourcePaths("/catalog/")</code> returns
193: * <code>{"/catalog/index.html", "/catalog/products.html", "/catalog/offers/"}</code>.<br>
194: *
195: * @param path
196: * the partial path used to match the resources, which must start with a slash
197: * @return a Set containing the directory listing, or <code>null</code> if there
198: * are no resources in the web application of which the path
199: * begins with the supplied path.
200: */
201:
202: public java.util.Set getResourcePaths(String path);
203:
204: /**
205: * Returns a URL to the resource that is mapped to a specified
206: * path. The path must begin with a slash (<code>/</code>) and is interpreted
207: * as relative to the current context root.
208: *
209: * <p>This method allows the portlet container to make a resource
210: * available to portlets from any source. Resources
211: * can be located on a local or remote
212: * file system, in a database, or in a <code>.war</code> file.
213: *
214: * <p>The portlet container must implement the URL handlers
215: * and <code>URLConnection</code> objects that are necessary
216: * to access the resource.
217: *
218: * <p>This method returns <code>null</code>
219: * if no resource is mapped to the pathname.
220: *
221: * <p>Some containers may allow writing to the URL returned by
222: * this method using the methods of the URL class.
223: *
224: * <p>The resource content is returned directly, so be aware that
225: * requesting a <code>.jsp</code> page returns the JSP source code.
226: * Use a <code>RequestDispatcher</code> instead to include results of
227: * an execution.
228: *
229: * <p>This method has a different purpose than
230: * <code>java.lang.Class.getResource</code>,
231: * which looks up resources based on a class loader. This
232: * method does not use class loaders.
233: *
234: * @param path a <code>String</code> specifying
235: * the path to the resource
236: *
237: * @return the resource located at the named path,
238: * or <code>null</code> if there is no resource
239: * at that path
240: *
241: * @exception MalformedURLException if the pathname is not given in
242: * the correct form
243: *
244: */
245:
246: public java.net.URL getResource(String path)
247: throws java.net.MalformedURLException;
248:
249: /**
250: * Returns the portlet container attribute with the given name,
251: * or null if there is no attribute by that name.
252: * An attribute allows a portlet container to give the
253: * portlet additional information not
254: * already provided by this interface.
255: * A list of supported attributes can be retrieved using
256: * <code>getAttributeNames</code>.
257: *
258: * <p>The attribute is returned as a <code>java.lang.Object</code>
259: * or some subclass.
260: * Attribute names should follow the same convention as package
261: * names. The Java Portlet API specification reserves names
262: * matching <code>java.*</code>, <code>javax.*</code>,
263: * and <code>sun.*</code>.
264: *
265: *
266: * @param name a <code>String</code> specifying the name
267: * of the attribute
268: *
269: * @return an <code>Object</code> containing the value
270: * of the attribute, or <code>null</code>
271: * if no attribute exists matching the given
272: * name
273: *
274: * @see #getAttributeNames
275: *
276: * @exception java.lang.IllegalArgumentException
277: * if name is <code>null</code>.
278: */
279:
280: public java.lang.Object getAttribute(java.lang.String name);
281:
282: /**
283: * Returns an <code>Enumeration</code> containing the attribute names
284: * available within this portlet context, or an emtpy
285: * <code>Enumeration</code> if no attributes are available. Use the
286: * {@link #getAttribute} method with an attribute name
287: * to get the value of an attribute.
288: *
289: * @return an <code>Enumeration</code> of attribute names
290: *
291: * @see #getAttribute
292: */
293:
294: public java.util.Enumeration getAttributeNames();
295:
296: /**
297: * Returns a String containing the value of the named context-wide
298: * initialization parameter, or <code>null</code> if the parameter does not exist.
299: * This method provides configuration information which may be useful for
300: * an entire "portlet application".
301: *
302: * @param name a <code>String</code> containing the name of the
303: * requested parameter
304: *
305: * @return a <code>String</code> containing the value
306: * of the initialization parameter, or
307: * <code>null</code> if the parameter does not exist.
308: *
309: * @see #getInitParameterNames
310: *
311: * @exception java.lang.IllegalArgumentException
312: * if name is <code>null</code>.
313: */
314:
315: public java.lang.String getInitParameter(java.lang.String name);
316:
317: /**
318: * Returns the names of the context initialization parameters as an
319: * <code>Enumeration</code> of String objects, or an empty Enumeration if the context
320: * has no initialization parameters.
321: *
322: * @return an <code>Enumeration</code> of <code>String</code>
323: * objects containing the names of the context
324: * initialization parameters
325: *
326: * @see #getInitParameter
327: */
328:
329: public java.util.Enumeration getInitParameterNames();
330:
331: /**
332: * Writes the specified message to a portlet log file, usually an event log.
333: * The name and type of the portlet log file is specific to the portlet container.
334: * <p>
335: * This method mapps to the <code>ServletContext.log</code> method.
336: * The portlet container may in addition log this message in a
337: * portlet container specific log file.
338: *
339: * @param msg a <code>String</code> specifying the
340: * message to be written to the log file
341: */
342:
343: public void log(java.lang.String msg);
344:
345: /**
346: * Writes an explanatory message and a stack trace for a given
347: * Throwable exception to the portlet log file.
348: * The name and type of the portlet log file is specific to the
349: * portlet container, usually an event log.
350: * <p>
351: * This method is mapped to the <code>ServletContext.log</code> method.
352: * The portlet container may in addition log this message in a
353: * portlet container specific log file.
354: *
355: * @param message a <code>String</code> that
356: * describes the error or exception
357: * @param throwable the <code>Throwable</code> error
358: * or exception
359: */
360:
361: public void log(java.lang.String message,
362: java.lang.Throwable throwable);
363:
364: /**
365: * Removes the attribute with the given name from the portlet context.
366: * After removal, subsequent calls to
367: * {@link #getAttribute} to retrieve the attribute's value
368: * will return <code>null</code>.
369: *
370: * @param name a <code>String</code> specifying the name
371: * of the attribute to be removed
372: *
373: * @exception java.lang.IllegalArgumentException
374: * if name is <code>null</code>.
375: */
376:
377: public void removeAttribute(java.lang.String name);
378:
379: /**
380: * Binds an object to a given attribute name in this portlet context.
381: * If the name specified is already used for an attribute, this method
382: * removes the old attribute and binds the name to the new attribute.
383: * <p>
384: * If a null value is passed, the effect is the same as calling
385: * <code>removeAttribute()</code>.
386: *
387: * <p>Attribute names should follow the same convention as package
388: * names. The Java Portlet API specification reserves names
389: * matching <code>java.*</code>, <code>javax.*</code>, and
390: * <code>sun.*</code>.
391: *
392: * @param name a <code>String</code> specifying the name
393: * of the attribute
394: * @param object an <code>Object</code> representing the
395: * attribute to be bound
396: *
397: * @exception java.lang.IllegalArgumentException
398: * if name is <code>null</code>.
399: */
400:
401: public void setAttribute(java.lang.String name,
402: java.lang.Object object);
403:
404: /**
405: * Returns the name of this portlet application correponding to this PortletContext as specified
406: * in the <code>web.xml</code> deployment descriptor for this web application by the
407: * <code>display-name</code> element.
408: *
409: *
410: * @return The name of the web application or null if no name has been declared in the deployment descriptor.
411: */
412:
413: public String getPortletContextName();
414:
415: }
|