001: /*
002: * The Apache Software License, Version 1.1
003: *
004: * Copyright (c) 2001-2004 Caucho Technology, Inc. All rights reserved.
005: *
006: * Redistribution and use in source and binary forms, with or without
007: * modification, are permitted provided that the following conditions
008: * are met:
009: *
010: * 1. Redistributions of source code must retain the above copyright
011: * notice, this list of conditions and the following disclaimer.
012: *
013: * 2. Redistributions in binary form must reproduce the above copyright
014: * notice, this list of conditions and the following disclaimer in
015: * the documentation and/or other materials provided with the
016: * distribution.
017: *
018: * 3. The end-user documentation included with the redistribution, if
019: * any, must include the following acknowlegement:
020: * "This product includes software developed by the
021: * Caucho Technology (http://www.caucho.com/)."
022: * Alternately, this acknowlegement may appear in the software itself,
023: * if and wherever such third-party acknowlegements normally appear.
024: *
025: * 4. The names "Hessian", "Resin", and "Caucho" must not be used to
026: * endorse or promote products derived from this software without prior
027: * written permission. For written permission, please contact
028: * info@caucho.com.
029: *
030: * 5. Products derived from this software may not be called "Resin"
031: * nor may "Resin" appear in their names without prior written
032: * permission of Caucho Technology.
033: *
034: * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
035: * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
036: * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
037: * DISCLAIMED. IN NO EVENT SHALL CAUCHO TECHNOLOGY OR ITS CONTRIBUTORS
038: * BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY,
039: * OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT
040: * OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
041: * BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
042: * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
043: * OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN
044: * IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
045: *
046: * @author Sam
047: */
048:
049: package com.caucho.portal.generic;
050:
051: import javax.portlet.*;
052: import java.io.IOException;
053: import java.util.ArrayList;
054: import java.util.Locale;
055: import java.util.Map;
056: import java.util.Set;
057:
058: /**
059: * A Window represents the use of a portlet on a page.
060: * The Window interface is the main point of contact between a portal
061: * implementation and the generic portlet codebase.
062: */
063: public interface Window {
064: public PortletConfig getPortletConfig();
065:
066: public Renderer getRenderer();
067:
068: /**
069: * Time in seconds, 0 disables caching and -1 means never expire.
070: */
071: public int getExpirationCache();
072:
073: /**
074: * Return true if the contents of the portlet are private.
075: *
076: * The portlet specification states that "cached content must not be shared
077: * across different user clients displaying the same portlet".
078: *
079: * If a portal implementation supports caching, then a return value of false
080: * will allow the portal to share the cached content across different user
081: * clients.
082: */
083: public boolean isPrivate();
084:
085: /**
086: * Return the default preferences for the portlet, null if there are no
087: * default preferences.
088: */
089: public PortletPreferences getDefaultPreferences();
090:
091: /**
092: * Return the preferences validators for the portlet, null if there are no
093: * preference validators.
094: */
095: public ArrayList<PreferencesValidator> getPreferencesValidators();
096:
097: /**
098: * Return a map that map's role names used by the portlet to the role names
099: * recognized by the portal, null if the role names used by the portlet
100: * are to be used unchanged.
101: */
102: public Map<String, String> getRoleRefMap();
103:
104: /**
105: * Return a list of {@link Constraint} that are applied before the
106: * processAction() and render() of the portlet are called, null if there
107: * are no Constraints.
108: */
109: public ArrayList<Constraint> getConstraints();
110:
111: /**
112: * Return the content types supported for the mode, null if all content
113: * types are permitted.
114: */
115: public Set<String> getSupportedContentTypes(PortletMode portletMode);
116:
117: /**
118: * Return the Locales supported, null if all Locales are permitted.
119: */
120: public Set<Locale> getSupportedLocales();
121:
122: /**
123: * Return a preferred buffer size, may be overridden by the portlet
124: * if it calls setBufferSize().
125: * A value of 0 disables buffering for the portlet.
126: * A value of -1 allows the portal to use a default buffer size.
127: */
128: public int getBufferSize();
129:
130: /**
131: * Return true if the WindowState is allowed.
132: * <code>portletRequest.getResponseContentType()</code> can be used
133: * if the allowed portlet modes depends on the mime type of the
134: * response.
135: */
136: public boolean isWindowStateAllowed(PortletRequest request,
137: WindowState windowState);
138:
139: /**
140: * Return true if the PortletMode is allowed.
141: * <code>portletRequest.getResponseContentType()</code> can be used
142: * if the allowed portlet modes depends on the mime type of the
143: * response.
144: */
145: public boolean isPortletModeAllowed(PortletRequest request,
146: PortletMode portletMode);
147:
148: /**
149: * This is called when a request arrives requesting a PortletMode
150: * that does not pass the isPortletModeAllowed() tests.
151: * It gives the Window an opportunity to return a PortletMode
152: * that can be used. If the returned mode is also not allowed, a
153: * PortletModeException occurs.
154: *
155: * Implementations can use {@link handleException} to handle
156: * PortletModeException.
157: *
158: * @return a new PortletMode to try, or null to cause an exception.
159: */
160: public PortletMode handlePortletModeFailure(PortletRequest request,
161: PortletMode notAllowed);
162:
163: /**
164: * This is called when a request arrives requesting a WindowState
165: * that does not pass the isWindowStateAllowed() tests.
166: * It gives the Window an opportunity to return a WindowState
167: * that can be used. If the returned window state is also not allowed, a
168: * WindowStateException occurs.
169: *
170: * Implementations can use {@link handleException} to handle
171: * WindowStateException.
172: *
173: * @return a new WindowState to try, or null to cause an exception,
174: */
175: public WindowState handleWindowStateFailure(PortletRequest request,
176: WindowState notAllowed);
177:
178: /**
179: * Optionally handle a constraint failure by sending some output to the
180: * client using the response or by hiding the window.
181: *
182: * When a Portlet fails a Constriant during processAction(), it is stored
183: * until the render stage, and handleConstriantFailure() is called instead of
184: * render().
185: *
186: * When a Portlet fails a Constraint during render(),
187: * handleConstriantFailure() is immediately called.
188: *
189: * If the implementation of this method does nothing, then the response of
190: * this window is reset() and the failure propagates to the parent window.
191: * If there is no parent window,
192: * {@link PortletConnection#handleConstraintFailure()} is called.
193: *
194: * Implementations of this method can change that behaviour by using the
195: * <code>event.setHandled(boolean hideWindow)</code> callback method.
196: *
197: * See {@link #handleException} for more information.
198: */
199: public void handleConstraintFailure(RenderRequest request,
200: RenderResponse response, ConstraintFailureEvent event)
201: throws IOException, PortletException;
202:
203: /**
204: * Optionally handle an exception by sending some output to the client
205: * using the response or by hiding the window.
206: *
207: * When a Portlet throws an Exception during processAction(), it is stored
208: * until the render stage, and handleException() is called instead of
209: * render().
210: *
211: * When a Portlet throws an exception during render(), the handleException()
212: * is immediately called.
213: *
214: * If the implementation of this method does nothing, then the repsonse of
215: * this window is reset() and the exception propagates to the parent window.
216: * If there is no parent window, {@link PortletConnection#handleException()}
217: * is called.
218: *
219: * Implementations of this method can change that behaviour by using the
220: * <code>event.setHandled(boolean hideWindow)</code> callback method.
221: *
222: * <h3>exceptionEvent.setHandled(false)</h3>
223: *
224: * If handleException calls exceptionEvent.setHandled(false) then
225: * the content that the portlet has written is kept, and the request
226: * continues. Implementations use this when they have written some
227: * contents to the portlet that should be visible to the user.
228: *
229: * <pre>
230: * public void handleException(RenderRequest request, RenderResponse response, ExceptionEvent event)
231: * throws PortletException, IOException
232: * {
233: * if (event.getException() instanceof UnavailableException) {
234: * PrintWriter out = response.getWriter();
235: * response.setContentType("text/html");
236: * out.println("This service is currently unavailable.");
237: * event.setHandled(false);
238: * }
239: * }
240: * </pre>
241: *
242: * If an implementation is handling an exception that can occur after the
243: * Portlet has written some content already, it should call response.reset()
244: * before it writes anything to the response.
245: *
246: * <pre>
247: * public void handleException(RenderRequest request, RenderResponse response, ExceptionEvent event)
248: * throws PortletException, IOException
249: * {
250: * response.reset();
251: * response.setContentType("text/html");
252: * PrintWriter out = response.getWriter();
253: * printFancyExceptionMessage(event.getException());
254: * event.setHandled(false);
255: * }
256: * </pre>
257: *
258: * <h3>exceptionEvent.setHandled(true)</h3>
259: *
260: * If handleException calls exceptionEvent.setHandled(true) then
261: * the output is reset(), including any output from a Renderer, and
262: * the request continues. The effect of this call is to make the window
263: * invisible, no content for this window is shown but other windows on
264: * the page will be shown. Implementations use this when they have dealt
265: * with the exception in some way and wish to hide the exception from the
266: * user.
267: *
268: * <pre>
269: * public void handleException(ExceptionEvent event)
270: * throws PortletException, IOException
271: * {
272: * log.log(Level.WARNING, ex.toString(), ex);
273: * event.setHandled(true);
274: * }
275: * </pre>
276: */
277: public void handleException(RenderRequest renderRequest,
278: RenderResponse renderResponse, ExceptionEvent exceptionEvent)
279: throws IOException, PortletException;
280:
281: }
|