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  ;
53  import java.util.ArrayList  ;
54  import java.util.Locale  ;
55  import java.util.Map  ;
56  import java.util.Set  ;
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  <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  <String  , String  > 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  <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  <String  > getSupportedContentTypes(PortletMode portletMode);
117 
118   /**
119    * Return the Locales supported, null if all Locales are permitted.
120    */
121   public Set  <Locale  > 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  , 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  , PortletException;
284 
285 }
286 
287
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags