KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > com > caucho > portal > generic > Window


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

48
49 package com.caucho.portal.generic;
50
51 import javax.portlet.*;
52 import java.io.IOException JavaDoc;
53 import java.util.ArrayList JavaDoc;
54 import java.util.Locale JavaDoc;
55 import java.util.Map JavaDoc;
56 import java.util.Set JavaDoc;
57
58 /**
59  * A Window represents the use of a portlet on a page.
60  * The Window interface is the main point of contact between a portal
61  * implementation and the generic portlet codebase.
62  */

63 public interface Window
64 {
65   public PortletConfig getPortletConfig();
66
67   public Renderer getRenderer();
68
69   /**
70    * Time in seconds, 0 disables caching and -1 means never expire.
71    */

72   public int getExpirationCache();
73
74   /**
75    * Return true if the contents of the portlet are private.
76    *
77    * The portlet specification states that "cached content must not be shared
78    * across different user clients displaying the same portlet".
79    *
80    * If a portal implementation supports caching, then a return value of false
81    * will allow the portal to share the cached content across different user
82    * clients.
83    */

84   public boolean isPrivate();
85
86   /**
87    * Return the default preferences for the portlet, null if there are no
88    * default preferences.
89    */

90   public PortletPreferences getDefaultPreferences();
91
92   /**
93    * Return the preferences validators for the portlet, null if there are no
94    * preference validators.
95    */

96   public ArrayList JavaDoc<PreferencesValidator> getPreferencesValidators();
97
98   /**
99    * Return a map that map's role names used by the portlet to the role names
100    * recognized by the portal, null if the role names used by the portlet
101    * are to be used unchanged.
102    */

103   public Map JavaDoc<String JavaDoc, String JavaDoc> getRoleRefMap();
104
105    /**
106     * Return a list of {@link Constraint} that are applied before the
107     * processAction() and render() of the portlet are called, null if there
108     * are no Constraints.
109     */

110   public ArrayList JavaDoc<Constraint> getConstraints();
111
112   /**
113    * Return the content types supported for the mode, null if all content
114    * types are permitted.
115    */

116   public Set JavaDoc<String JavaDoc> getSupportedContentTypes(PortletMode portletMode);
117
118   /**
119    * Return the Locales supported, null if all Locales are permitted.
120    */

121   public Set JavaDoc<Locale JavaDoc> getSupportedLocales();
122
123   /**
124    * Return a preferred buffer size, may be overridden by the portlet
125    * if it calls setBufferSize().
126    * A value of 0 disables buffering for the portlet.
127    * A value of -1 allows the portal to use a default buffer size.
128    */

129    public int getBufferSize();
130
131   /**
132    * Return true if the WindowState is allowed.
133    * <code>portletRequest.getResponseContentType()</code> can be used
134    * if the allowed portlet modes depends on the mime type of the
135    * response.
136    */

137   public boolean isWindowStateAllowed(PortletRequest request,
138                                       WindowState windowState);
139
140   /**
141    * Return true if the PortletMode is allowed.
142    * <code>portletRequest.getResponseContentType()</code> can be used
143    * if the allowed portlet modes depends on the mime type of the
144    * response.
145    */

146   public boolean isPortletModeAllowed(PortletRequest request,
147                                       PortletMode portletMode);
148
149   /**
150    * This is called when a request arrives requesting a PortletMode
151    * that does not pass the isPortletModeAllowed() tests.
152    * It gives the Window an opportunity to return a PortletMode
153    * that can be used. If the returned mode is also not allowed, a
154    * PortletModeException occurs.
155    *
156    * Implementations can use {@link handleException} to handle
157    * PortletModeException.
158    *
159    * @return a new PortletMode to try, or null to cause an exception.
160    */

161   public PortletMode handlePortletModeFailure( PortletRequest request,
162                                                PortletMode notAllowed );
163
164   /**
165    * This is called when a request arrives requesting a WindowState
166    * that does not pass the isWindowStateAllowed() tests.
167    * It gives the Window an opportunity to return a WindowState
168    * that can be used. If the returned window state is also not allowed, a
169    * WindowStateException occurs.
170    *
171    * Implementations can use {@link handleException} to handle
172    * WindowStateException.
173    *
174    * @return a new WindowState to try, or null to cause an exception,
175    */

176   public WindowState handleWindowStateFailure( PortletRequest request,
177                                                WindowState notAllowed );
178
179   /**
180    * Optionally handle a constraint failure by sending some output to the
181    * client using the response or by hiding the window.
182    *
183    * When a Portlet fails a Constriant during processAction(), it is stored
184    * until the render stage, and handleConstriantFailure() is called instead of
185    * render().
186    *
187    * When a Portlet fails a Constraint during render(),
188    * handleConstriantFailure() is immediately called.
189    *
190    * If the implementation of this method does nothing, then the response of
191    * this window is reset() and the failure propagates to the parent window.
192    * If there is no parent window,
193    * {@link PortletConnection#handleConstraintFailure()} is called.
194    *
195    * Implementations of this method can change that behaviour by using the
196    * <code>event.setHandled(boolean hideWindow)</code> callback method.
197    *
198    * See {@link #handleException} for more information.
199    */

200   public void handleConstraintFailure( RenderRequest request,
201                                        RenderResponse response,
202                                        ConstraintFailureEvent event)
203     throws IOException JavaDoc, PortletException;
204
205
206   /**
207    * Optionally handle an exception by sending some output to the client
208    * using the response or by hiding the window.
209    *
210    * When a Portlet throws an Exception during processAction(), it is stored
211    * until the render stage, and handleException() is called instead of
212    * render().
213    *
214    * When a Portlet throws an exception during render(), the handleException()
215    * is immediately called.
216    *
217    * If the implementation of this method does nothing, then the repsonse of
218    * this window is reset() and the exception propagates to the parent window.
219    * If there is no parent window, {@link PortletConnection#handleException()}
220    * is called.
221    *
222    * Implementations of this method can change that behaviour by using the
223    * <code>event.setHandled(boolean hideWindow)</code> callback method.
224    *
225    * <h3>exceptionEvent.setHandled(false)</h3>
226    *
227    * If handleException calls exceptionEvent.setHandled(false) then
228    * the content that the portlet has written is kept, and the request
229    * continues. Implementations use this when they have written some
230    * contents to the portlet that should be visible to the user.
231    *
232    * <pre>
233    * public void handleException(RenderRequest request, RenderResponse response, ExceptionEvent event)
234    * throws PortletException, IOException
235    * {
236    * if (event.getException() instanceof UnavailableException) {
237    * PrintWriter out = response.getWriter();
238    * response.setContentType("text/html");
239    * out.println("This service is currently unavailable.");
240    * event.setHandled(false);
241    * }
242    * }
243    * </pre>
244    *
245    * If an implementation is handling an exception that can occur after the
246    * Portlet has written some content already, it should call response.reset()
247    * before it writes anything to the response.
248    *
249    * <pre>
250    * public void handleException(RenderRequest request, RenderResponse response, ExceptionEvent event)
251    * throws PortletException, IOException
252    * {
253    * response.reset();
254    * response.setContentType("text/html");
255    * PrintWriter out = response.getWriter();
256    * printFancyExceptionMessage(event.getException());
257    * event.setHandled(false);
258    * }
259    * </pre>
260    *
261    * <h3>exceptionEvent.setHandled(true)</h3>
262    *
263    * If handleException calls exceptionEvent.setHandled(true) then
264    * the output is reset(), including any output from a Renderer, and
265    * the request continues. The effect of this call is to make the window
266    * invisible, no content for this window is shown but other windows on
267    * the page will be shown. Implementations use this when they have dealt
268    * with the exception in some way and wish to hide the exception from the
269    * user.
270    *
271    * <pre>
272    * public void handleException(ExceptionEvent event)
273    * throws PortletException, IOException
274    * {
275    * log.log(Level.WARNING, ex.toString(), ex);
276    * event.setHandled(true);
277    * }
278    * </pre>
279    */

280   public void handleException( RenderRequest renderRequest,
281                                RenderResponse renderResponse,
282                                ExceptionEvent exceptionEvent)
283   throws IOException JavaDoc, PortletException;
284
285 }
286
287
Popular Tags