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  ;
61  import java.io.IOException  ;
62  
63  import java.util.Locale  ;
64  import java.util.Enumeration  ;
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   getInitParameter (String   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   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   name, Object   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   getAttribute (String   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   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   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   path,
192                          PortletRequest request,
193                          PortletResponse response) throws PortletException,
194                                                           IOException  ;
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   getResourceAsStream (String   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   getText (String   key, String   bundleName, Locale   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   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   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
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags