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