KickJava   Java API By Example, From Geeks To Geeks.

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


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 java.io.IOException JavaDoc;
58
59 import java.util.Locale JavaDoc;
60
61 /**
62  * The <CODE>Portlet</CODE> interface is used by the portlet container to
63  * invoke the portlet. However, a portlet cannot directly implement the
64  * <CODE>Portlet</CODE> interface directly. Instead, it has to extend
65  * one of the abstract portlet implementations, which indicates to the
66  * the portlet container the type of content (eg. content stream or
67  * SAX events) that the portlet will generate.
68  *
69  * <P>
70  * A portlet is a small Java program that runs within a portlet container.
71  * Portlets receive and respond to requests from the portlet container.
72  * There is ever only object instance of each portlet class, yet each
73  * user should be able to a have personalized view of that portlet instance.
74  * Therefore, the portlet session carries vital information for the
75  * portlet to create a personalized user experience. Portlet instance
76  * plus session create a <EM>virtual instance</EM> of the portlet. This
77  * is similar to the way a servlet relates to its servlet container.
78  * As a consequence, the portlet should not attempt to store the portlet
79  * session or any other user-related information as instance or class
80  * variabled. In fact, instance variables of a portlet can be considered
81  * to have similar behaviour as class variables, because there is ever
82  * only one instance which is shared by multiple threads. Therefore,
83  * any instance information has to be either read-only (as is the case
84  * for the portlet configuration), or carefully protected by the
85  * <CODE>synchronized</CODE> keyword.
86  * </P>
87  *
88  * <P>
89  * As part of running within the portlet container each portlet has a
90  * life-cycle. The corresponding methods are called in the following
91  * sequence:
92  * </P>
93  * <OL>
94  * <LI>The portlet is constructed, then initialized with the
95  * <CODE>init()</CODE> method.
96  * <LI>Any calls from the portlet container to the <CODE>service()</CODE>
97  * method are handled.
98  * <LI>The portlet is taken out of service, then destroyed with the
99  * <CODE>destroy()</CODE> method, then garbage collected and finalized.
100  * </OL>
101  *
102  * <P>
103  * The virtual instance is created and destroyed with the
104  * <CODE>login()</CODE> and <CODE>logout()</CODE> methods,
105  * respectively. If a portlet provides personalized views these methods
106  * should be implemented.
107  * </P>
108  *
109  * <P>
110  * The portlet container loads and instantiates the portlet class. This
111  * can happen during startup of the portal server or later, but no later
112  * then when the first request to the portlet has to be serviced.
113  * Also, if a portlet is taken temporarily out of service, for example
114  * while administrating it, the portlet container may finish the life-cycle
115  * before taking the portlet out of service. When the administration
116  * is done, the portlet will be newly initialized.
117  * </P>
118  *
119  * @author <A HREF="mailto:tboehme@us.ibm.com">Thomas F. Boehme</A>
120  */
121 public interface Portlet
122 {
123     /**
124      ** The <CODE>Mode</CODE> class is a finite enumeration of
125      ** the possible modes that a portlet can assume.
126      **/
127
128     public static class Mode implements java.io.Serializable JavaDoc
129     {
130         /**
131          ** The standard "one-of many" portlet view on a page.
132          **/
133
134         public final static Mode VIEW = new Mode ("View", 0);
135
136         /**
137          ** This mode allows the portlet to capture user-specific
138          ** parameterization, which leads to a personalized view of the
139          ** portlet.
140          **/
141
142         public final static Mode PERSONALIZE = new Mode ("Personalize", 1);
143
144         /**
145          ** A portlet should provide useful online help in this mode.
146          ** This may be a short description or a multi-page instruction on
147          ** how to use the portlet.
148          **/
149
150         public final static Mode HELP = new Mode ("Help", 2);
151
152         /**
153          ** Allows the portlet to bring its own configuration screen if
154          ** required. Only a user with administrator privileges should
155          ** be able to call a portlet in this mode.
156          **/
157
158         public final static Mode CONFIGURE = new Mode ("Configure", 3);
159
160         private String JavaDoc identifier;
161
162         private int value;
163
164         private Mode (String JavaDoc identifier, int value)
165         {
166             this.identifier = identifier;
167             this.value = value;
168         }
169
170         public int getId()
171         {
172             return value;
173         }
174
175         public String JavaDoc toString ()
176         {
177             return (identifier);
178         }
179     }
180
181     /**
182      ** Called by the portlet container to indicate to this portlet
183      ** that it is put into service.
184      **
185      ** <P>
186      ** The portlet container calls the <CODE>init()</CODE> method
187      ** for the whole life-cycle of the portlet. The
188      ** <CODE>init()</CODE> method must complete successfully before
189      ** virtual instances are created through the
190      ** <CODE>beginSession()</CODE> method.
191      **
192      ** <P>
193      ** The portlet container cannot place the portlet into service
194      ** if the <CODE>init()</CODE> method
195      **
196      ** <OL>
197      ** <LI>Throws a <CODE>PortletException</CODE>
198      ** <LI>Does not return within a time period defined by the portlet
199      ** container.
200      ** </OL>
201      **
202      ** @param config
203      ** the portlet configuration
204      **
205      ** @exception UnavailableException
206      ** if an exception has occurrred that interferes
207      ** with the portlet's normal initialization
208      **/
209
210     public void init (PortletConfig config) throws UnavailableException;
211
212     /**
213      ** Called by the portlet container to indicate to this portlet
214      ** that it is taken out of service. This method is only called
215      ** once all threads within the portlet's <CODE>service()</CODE>
216      ** method have exited or after a timeout period has passed. After
217      ** the portlet container calls this method, it will not call the
218      ** <CODE>service()</CODE> method again on this portlet.
219      **
220      ** <P>
221      ** This method gives the portlet an opportunity to clean up any
222      ** resources that are being held (for example, memory, file
223      ** handles, threads).
224      **/
225
226     public void destroy ();
227
228     /**
229      ** Called by the portlet container to ask the portlet to
230      ** initialize the given portlet for a user.
231      **
232      ** <P>
233      ** In addition to initializing the session this method allows the
234      ** portlet to initialize the virtual instance, for example, to
235      ** store attributes in the session.
236      ** </P>
237      **
238      ** @param request
239      ** the portlet request
240      **
241      ** @exception PortletException
242      ** if the portlet has trouble fulfilling the
243      ** request
244      **/
245
246     public void login (PortletRequest request) throws PortletException;
247
248     /**
249      ** Called by the portlet container to indicate that a virtual
250      ** instance of the portlet is being removed.
251      **
252      ** <P>
253      ** This method gives the virtual instance of the portlet an
254      ** opportunity to clean up any resources (for example, memory,
255      ** file handles, threads), before it is removed. This happens
256      ** if the user logs off, or decides to remove this portlet from
257      ** a page.
258      ** </P>
259      **
260      ** @param request
261      ** the portlet request
262      **
263      ** @exception PortletException
264      ** if the portlet has trouble fulfilling the
265      ** request
266      **/
267
268     public void logout (PortletRequest request) throws PortletException;
269
270     /**
271      ** Called by the portlet container to ask this portlet to generate
272      ** its markup using the given request/response pair. Depending
273      ** on the mode of the portlet and the requesting client device,
274      ** the markup will be different. Also, the portlet can take language
275      ** preferences and/or personalized settings into account.
276      **
277      ** @param request
278      ** the portlet request
279      ** @param response
280      ** the portlet response
281      **
282      ** @exception PortletException
283      ** if the portlet has trouble fulfilling the
284      ** rendering request
285      ** @exception IOException
286      ** if the streaming causes an I/O problem
287      **/
288
289     public void service (PortletRequest request,
290                          PortletResponse response) throws PortletException,
291                                                           IOException JavaDoc;
292
293 }
294
Popular Tags