KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > apache > jetspeed > portlet > PortletContext


1 /* ====================================================================
2  * The Apache Software License, Version 1.1
3  *
4  * Copyright (c) 2000-2001 The Apache Software Foundation. All rights
5  * reserved.
6  *
7  * Redistribution and use in source and binary forms, with or without
8  * modification, are permitted provided that the following conditions
9  * are met:
10  *
11  * 1. Redistributions of source code must retain the above copyright
12  * notice, this list of conditions and the following disclaimer.
13  *
14  * 2. Redistributions in binary form must reproduce the above copyright
15  * notice, this list of conditions and the following disclaimer in
16  * the documentation and/or other materials provided with the
17  * distribution.
18  *
19  * 3. The end-user documentation included with the redistribution,
20  * if any, must include the following acknowledgment:
21  * "This product includes software developed by the
22  * Apache Software Foundation (http://www.apache.org/)."
23  * Alternately, this acknowledgment may appear in the software itself,
24  * if and wherever such third-party acknowledgments normally appear.
25  *
26  * 4. The names "Apache" and "Apache Software Foundation" and
27  * "Apache Jetspeed" must not be used to endorse or promote products
28  * derived from this software without prior written permission. For
29  * written permission, please contact apache@apache.org.
30  *
31  * 5. Products derived from this software may not be called "Apache" or
32  * "Apache Jetspeed", nor may "Apache" appear in their name, without
33  * prior written permission of the Apache Software Foundation.
34  *
35  * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
36  * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
37  * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
38  * DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
39  * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
40  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
41  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
42  * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
43  * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
44  * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
45  * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
46  * SUCH DAMAGE.
47  * ====================================================================
48  *
49  * This software consists of voluntary contributions made by many
50  * individuals on behalf of the Apache Software Foundation. For more
51  * information on the Apache Software Foundation, please see
52  * <http://www.apache.org/>.
53  */

54
55 package org.apache.jetspeed.portlet;
56
57 import org.apache.jetspeed.portlet.event.MessageEvent;
58 import org.apache.jetspeed.portlet.event.MessageListener;
59
60 import java.io.InputStream JavaDoc;
61 import java.io.IOException JavaDoc;
62
63 import java.util.Locale JavaDoc;
64 import java.util.Enumeration JavaDoc;
65
66 /**
67  ** The <CODE>PortletContext</CODE> interface defines a portlet's view
68  ** of the portlet container within which each portlet is running.
69  ** The <CODE>PortletContext</CODE> also allows a portlet to access
70  ** resources available to it. Using the context, a portlet can access
71  ** the portlet log, and obtain URL references to resources.
72  **
73  ** @author <A HREF="mailto:tboehme@us.ibm.com">Thomas F. Boehme</A>
74  **/

75
76 public interface PortletContext
77 {
78     /**
79      ** Returns the value of the context-wide initialization parameter with
80      ** the given name, or <CODE>null</CODE> if the parameter does not exist.
81      **
82      ** <P>
83      ** This method can make available configuration information useful to
84      ** all portlets.
85      **
86      ** @param name
87      ** the parameter name
88      **
89      ** @return the parameter value, <BR>
90      ** or <CODE>null</CODE> if it does not exist
91      **/

92
93     public String JavaDoc getInitParameter (String JavaDoc name);
94
95     /**
96      ** Returns the names of this contextís initialization parameters as
97      ** an enumeration, or an empty enumeration if this context has no
98      ** initialization parameters.
99      **
100      ** @return an enumeration of parameter names
101      **/

102
103     public Enumeration JavaDoc getInitParameterNames ();
104
105     /**
106      ** Associates an attribute with the given name and value
107      ** with this context. If a portlet needs to communicate
108      ** information to embedded servlets or JSP, this methods
109      ** can used carry the information along.
110      **
111      ** @param name
112      ** the attribute name
113      ** @param value
114      ** the attribute value
115      **/

116
117     public void setAttribute (String JavaDoc name, Object JavaDoc value);
118
119     /**
120      ** Returns the attribute value with the given name, or <CODE>null</CODE>
121      ** if no such attribute exists.
122      **
123      ** <P>
124      ** The context attributes can be used to share information between
125      ** the portlets of one portlet application.
126      **
127      ** @param name
128      ** the attribute name
129      **
130      ** @return the attribute value
131      **/

132
133     public Object JavaDoc getAttribute (String JavaDoc name);
134
135     /**
136      ** Returns an enumeration of the attribute names that this portlet
137      ** context is aware of.
138      **
139      ** @return an enumeration of attribute names
140      **/

141
142     public Enumeration JavaDoc getAttributeNames ();
143
144     /**
145      ** Removes the attribute with the given name.
146      **
147      ** @param name
148      ** the name of attribute to be removed
149      **/

150
151     public void removeAttribute (String JavaDoc name);
152
153     /**
154      * <P>
155      * Allows the portlet to delegate the rendering to another resource
156      * as specified by the given path. The path has to be relative
157      * and will be resolved by this method, so that the portlet's
158      * resources are accessed.
159      * </P>
160      * <P>
161      * To access protected resources the path has to be prefixed with
162      * /portlet-inf/ (e.g. /portlet-inf/myportlet/myportlet.jsp).
163      * Otherwise, the direct path is used. (e.g. /myportlet/myportlet.jsp).
164      * </P>
165      * <P>
166      * This method is enabled for multi-language and multi-device support.
167      * For example, a jsp file "/myportlet/mytemplate.jsp" will be searched for
168      * in the following order, when accessing via HTML-Browser:
169      * 1. /html/en/US/IE/mytemplate.jsp
170      * 2. /html/en/US/mytemplate.jsp
171      * 3. /html/en/mytemplate.jsp
172      * 4. /html/mytemplate.jsp
173      * 5. /en/US/IE/mytemplate.jsp
174      * 6. /en/US/mytemplate.jsp
175      * 7. /en/mytemplate.jsp
176      * 8. /mytemplate.jsp
177      * </P>
178      *
179      * @param path
180      * the path of the delegate resource
181      * @param request
182      * the portlet request
183      * @param response
184      * the portlet response
185      * @exception PortletException
186      * if the delegated resource has trouble fulfilling the
187      * rendering request
188      * @exception IOException
189      * if the streaming causes an I/O problem
190      */

191     public void include (String JavaDoc path,
192                          PortletRequest request,
193                          PortletResponse response) throws PortletException,
194                                                           IOException JavaDoc;
195
196      /**
197       * Returns the resource located at the given path as an
198       * <CODE>InputStream</CODE> object.
199       *
200       * <P>
201       * The data in the <CODE>InputStream</CODE> can be of any type
202       * or length. The method returns <CODE>null</CODE> if no resource
203       * exists at the given path.
204       * </P>
205       * <P>
206       * To access protected resources the path has to be prefixed with
207       * /portlet-inf/ (e.g. /portlet-inf/myportlet/myportlet.jsp).
208       * Otherwise, the direct path is used. (e.g. /myportlet/myportlet.jsp).
209       * </P>
210       *
211       * @param path
212       * the path to the resource
213       * @return the input stream
214       */

215      public InputStream JavaDoc getResourceAsStream (String JavaDoc path);
216
217      /**
218       ** Returns the localized text resource with the given key and
219       ** using the given locale.
220       **
221       ** <P>
222       ** To use this feature, the <CODE>CLASSPATH</CODE> has to contain a
223       ** resource bundle with the same name (including the package) as the
224       ** portlet.
225       **
226       ** @param key
227       ** the text key
228       ** @param bundleName
229       ** the name of the resource bundle
230       ** @param locale
231       ** the locale to observe
232       **
233       ** @return the localized text resource
234       **/

235
236      public String JavaDoc getText (String JavaDoc key, String JavaDoc bundleName, Locale JavaDoc locale);
237
238      /**
239       * Sends the given message to all portlets on the same
240       * page that have the given name. If the portlet name is
241       * <CODE>null</CODE> the message is broadcast to all portlets.
242       * If more than one instance of the portlet with the given
243       * name exists on the current page, the message is
244       * sent to every single instance of that portlet. If the
245       * source portlet has the same name as the target portlet(s),
246       * the message will not be sent to avoid possible cyclic calls.
247       *
248       * <P>
249       * The portlet(s) with the given name will only receive the
250       * message event if it has/they have registered the appropriate
251       * listener. This is done by registering the listener in the
252       * portlet descriptor.
253       * </P>
254       *
255       * @param aPortletName
256       * the name of the portlet(s) that this
257       * @param aMessage
258       * the message to be sent
259       */

260      public void send (String JavaDoc aPortletName, PortletMessage aMessage);
261
262      /**
263       ** Returns the major version of the Portlet API that this portlet
264       ** container supports.
265       **
266       ** @return the major version
267       **
268       ** @see #getMinorVersion()
269       **/

270
271      public int getMajorVersion ();
272
273      /**
274       ** Returns the minor version of the Portlet API that this portlet
275       ** container supports.
276       **
277       ** @return the minor version
278       **
279       ** @see #getMajorVersion()
280       **/

281
282      public int getMinorVersion ();
283
284      /**
285       ** Returns the name and version of the portlet container which the
286       ** portlet is running in.
287       **
288       ** <P>
289       ** The form of the returned string is <IT>servername/versionnumber</IT>.
290       ** For the Jetspeed Framework this method may return the string
291       ** <CODE>Apache Jetspeed/1.3a1</CODE>.
292       **
293       ** @return the string containing at least name and version number
294       **/

295
296       public String JavaDoc getContainerInfo ();
297
298       /**
299        ** Returns the portlet log which allows the portlet to write
300        ** informational, warning, or error messages to a log.
301        **
302        ** @return the portlet log
303        **/

304
305       public PortletLog getLog ();
306 }
307
Popular Tags