001 /* 002 * Licensed to the Apache Software Foundation (ASF) under one or more contributor license 003 * agreements. See the NOTICE file distributed with this work for additional information regarding 004 * copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the 005 * "License"); you may not use this file except in compliance with the License. You may obtain a 006 * copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable 007 * law or agreed to in writing, software distributed under the License is distributed on an "AS IS" 008 * BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License 009 * for the specific language governing permissions and limitations under the License. 010 */ 011 package javax.portlet.faces; 012 013 import javax.portlet.ActionRequest; 014 import javax.portlet.ActionResponse; 015 import javax.portlet.PortletConfig; 016 import javax.portlet.PortletException; 017 import javax.portlet.RenderRequest; 018 import javax.portlet.RenderResponse; 019 import javax.portlet.UnavailableException; 020 021 /** 022 * The <CODE>Bridge</CODE> interface is used by a portlet to execute a JSF artifact. Its lifecycle 023 * follows the pattern used by other web components such as portlets or servlets, namely: 024 * <ul> 025 * <li><code>init</code>: one time (per portlet) initialization. Usually invoked during portlet 026 * <code>init</code> but may also occur lazily. Context is passed to the Bridge at initialization 027 * via <code>PortletContext</code> attributes. See method description for details. </li> 028 * <li><code>doFacesRequest</code>: called for each portlet request that is to be handled by 029 * Faces. Must only be called after the bridge has been initialized. </li> 030 * <li><code>destroy</code>: called to destroy this bridge instance. Usually invoked during 031 * portlet <code>destroy</code> but may also occur earlier if the portlet decides to reclaim 032 * resources. </li> 033 * </ul> 034 * <P> 035 * Portlet developers are encouraged to allow deployers an ability to configure the particular 036 * Bridge implementation it uses within a given deployment. This ensures a best fit solution for a 037 * given application server, portlet container, and/or Faces environment. The specifics for this 038 * configuation are undefined. Each portlet can define a preferred mechanism. Subclasses of 039 * {@link GenericFacesPortlet} automatically inherit this behavior as it recognizes a defined 040 * portlet initialization parameter. 041 * <p> 042 * Implementations of this <code>Bridge</code> interface are required to have a <code>code</code> 043 * constructor. 044 */ 045 046 public interface Bridge 047 { 048 049 // Base Bridge attribute/context parameter prefix 050 public static final String BRIDGE_PACKAGE_PREFIX = "javax.portlet.faces."; 051 052 // Following are the names of context init parameters that control 053 // Bridge behavior. These are specified in the web.xml 054 055 /** 056 * Context initialization parameter that specifies the maximum number of bridge 057 * request scopes to preserved across all uses within this application. 058 */ 059 public static final String MAX_MANAGED_REQUEST_SCOPES = BRIDGE_PACKAGE_PREFIX 060 + "MAX_MANAGED_REQUEST_SCOPES"; 061 062 /** 063 * Context initialization parameter that defines the policy the bridge uses for 064 * rendering. Parameter value is the string representaiton of one of the 065 * BridgeRenderPolicy enum values. 066 */ 067 public static final String RENDER_POLICY = BRIDGE_PACKAGE_PREFIX 068 + "RENDER_POLICY"; 069 /** 070 * Context initialization parameter that defines the lifecycle ID used to 071 * identify the Faces Lifecycle used for this application. 072 */ 073 public static final String LIFECYCLE_ID = "javax.faces.LIFECYCLE_ID"; 074 075 /** 076 * Bridge attribute that signals this request is a Faces postback. Its provided as 077 * an alternative signal to the common reliance on the view state parameter as 078 * an indicator that this is a postback request. Implementations needing this 079 * information and not using the view state parameter indicator can check this 080 * attribute when running in a portlet environment. 081 */ 082 // Attribute signifying whether this render is a postback or not. 083 public static final String IS_POSTBACK_ATTRIBUTE = BRIDGE_PACKAGE_PREFIX + "isPostback"; 084 085 // Names for special QueryString parameters names the Bridge recognizes in 086 // encodeActionURL as signifying to change the corresponding portlet values 087 // in the resulting URL 088 089 /** 090 * Special token parameter in the url passed to the bridge's ExternalContext.encodeActionURL() 091 * that it recognizes as an indication that this action should encode a PortletMode 092 * change to the one indicated by the parameter's value. 093 */ 094 public static final String PORTLET_MODE_PARAMETER = BRIDGE_PACKAGE_PREFIX + "PortletMode"; 095 096 /** 097 * Special token parameter in the url passed to the bridge's ExternalContext.encodeActionURL() 098 * that it recognizes as an indication that this action should encode a WindowState change to 099 * the one indicated by the parameter's value. 100 */ 101 public static final String PORTLET_WINDOWSTATE_PARAMETER = BRIDGE_PACKAGE_PREFIX + "WindowState"; 102 103 /** 104 * Special token parameter in the url passed to the bridge's ExternalContext.encodeActionURL() 105 * that it recognizes as an indication that this action should encode a security level change to 106 * the one indicated by the parameter's value. 107 */ 108 public static final String PORTLET_SECURE_PARAMETER = BRIDGE_PACKAGE_PREFIX + "Secure"; 109 110 /** 111 * Special token parameter in the url passed to the bridge's ExternalContext.encodeActionURL() 112 * that it recognizes as an indication that this action should be treated as a direct link 113 * and hence shouldn't be encoded as a Portlet action. Rather encodeActionURL merely returns 114 * this url unchanged. 115 */ 116 public static final String DIRECT_LINK = BRIDGE_PACKAGE_PREFIX + "DirectLink"; 117 118 /** 119 * Special token parameter in the url passed to the bridge's ExternalContext.encodeResourceURL() 120 * that it recognizes as an indication that an URL refering back to the page which 121 * contains this portlet should be encoded in the resource url. This reference is 122 * encoded as the value of a query string parameter whose name is the value of this back 123 * link token parameter. 124 */ 125 126 public static final String BACK_LINK = BRIDGE_PACKAGE_PREFIX + "BackLink"; 127 128 /** 129 * Special token parameter in the url passed to the bridge's ExternalContext.encodeResourceURL() 130 * that it recognizes as an indication that this url refers to Faces view (navigation) and 131 * hence should be encoded as an portlet ActionURL rather then a portlet resource url. This token 132 * is intended for use in urls signifying a view navigation using components such as 133 * <code>h:outputLink</code>. 134 */ 135 136 public static final String VIEW_LINK = BRIDGE_PACKAGE_PREFIX + "ViewLink"; 137 138 /** A PortletContext attribute that a portlet can set prior 139 * to calling the bridge's init() method to configure the bridge to preserve 140 * action parameters received by this portlet along with bridge's request scope so 141 * that they may be restored and acessed in subsequent renders. If "true", the 142 * action parameters are preserved. If "false", they are not preserved. The bridge 143 * default is "false". 144 * 145 * As this attribute is scoped to a specific portlet in an application-wide context 146 * the attribute name must be include the portlet name as follows: 147 * BRIDGE_PACKAGE_PREFIX + context.getPortletName() + preserveActionParams 148 */ 149 public static final String PRESERVE_ACTION_PARAMS = "preserveActionParams"; 150 151 152 /** A PortletContext attribute that a portlet can set prior 153 * to calling the bridge's init() method to configure the bridge to exclude 154 * specific attributes from its bridge request scope. Value is a comma delimited 155 * list containing either a fully qualified attribute name or package name terminated 156 * with a ".*" wildcard indicator. In this later case, all attributes in the package 157 * name which precedes the ".*" are excluded, non recursive. 158 * 159 * As this attribute is scoped to a specific portlet in an application-wide context 160 * the attribute name must be include the portlet name as follows: 161 * BRIDGE_PACKAGE_PREFIX + context.getPortletName() + excludedRequestAttributes 162 */ 163 public static final String EXCLUDED_REQUEST_ATTRIBUTES = "excludedRequestAttributes"; 164 165 166 /** A PortletRequest attribute set by the bridge in its 167 * <code>ViewHandler.renderView</code> prior to dispatching the request 168 * to the view (jsp)to indicating a filter should 169 * put the AFTER_VIEW_CONTENT in a buffer on the request for it to process after 170 * rendering the view components. In conjunction with the filter this enables 171 * preserving rendering order of native JSP rendering and Faces rendering in a jsp. 172 */ 173 public static final String RENDER_CONTENT_AFTER_VIEW = BRIDGE_PACKAGE_PREFIX 174 + "RenderContentAfterView"; 175 /** A PortletRequest attribute set by an include filter in recognition of the 176 * RenderContentAfterView bridge attribute. Its value is either char[] or byte[] 177 * holding the AFTER_VIEW_CONTENT generated while rendering this jsp. 178 * In conjunction with the bridge this enables 179 * preserving rendering order of native JSP rendering and Faces rendering in a jsp. 180 */ 181 public static final String AFTER_VIEW_CONTENT = BRIDGE_PACKAGE_PREFIX 182 + "AfterViewContent"; 183 184 /** PortletRequest attribute set by the portlet prior to calling the bridge's 185 * <code>doFacesRequest()</code> method. Its value is the default viewId the 186 * bridge is to use if it can't otherwise decode one from the request. 187 */ 188 public static final String DEFAULT_VIEWID = BRIDGE_PACKAGE_PREFIX 189 + "defaultViewId"; 190 191 /** PortletRequest attribute set by the bridge prior to creating/acquiring a 192 * <code>FacesContext</code>. Its value indicates which portlet phase this 193 * Faces is executing in. It can be used by Faces subsystems not only to determine 194 * the portlet exectution phase but if present (not null) as an indication the request 195 * is being processed in a portlet container. 196 */ 197 public static final String PORTLET_LIFECYCLE_PHASE = BRIDGE_PACKAGE_PREFIX + "phase"; 198 199 /** Name of PortletResponse property set by the bridge when it recognizes that the 200 * view has been rendered using a <code>NamingContainer</code> that ensures all 201 * generated ids are namespaced using the consumer provided unique portlet id. 202 */ 203 public static final String PORTLET_NAMESPACED_RESPONSE_PROPERTY = "X-JAVAX-PORTLET-NAMESPACED-RESPONSE"; 204 205 /** Enumeration whose values describe the current portlet phase the bridge 206 * is executing Faces within. 207 */ 208 209 public static enum PortletPhase 210 { 211 ACTION_PHASE, RENDER_PHASE; 212 } 213 214 /** Enumeration whose values describe the render policy used by the bridge 215 * to render portlets in this application. A policy of DEFAULT indicates 216 * the bridge will first delegate rendering and if this results in an 217 * exception being thrown will render the itself. A policy of ALWAYS_DELEGATE 218 * indicates the bridge will always delegate rendering, never rendering itself. 219 * A policy of NEVER_DELEGATE indicates the bridge will always render itself without 220 * delegating. 221 */ 222 public static enum BridgeRenderPolicy 223 { 224 DEFAULT, ALWAYS_DELEGATE, NEVER_DELEGATE; 225 } 226 227 /** 228 * Called by the portlet. It indicates that the bridge is being placed into service. 229 * <p> 230 * The portlet calls the <code>init</code> method exactly once before invoking other lifecycle 231 * methods. Usually, done immediately after instantiating the bridge. The <code>init</code> 232 * method must complete successfully before the bridge can receive any requests. 233 * <p> 234 * The portlet cannot place the bridge into service if the <code>init</code> method Throws a 235 * <code>BridgeException</code>. 236 * <p> 237 * Initialization context is passed to bridge via <code>PortletContext</code> attributes. The 238 * following attributes are defined: 239 * <ul> 240 * <li><code>javax.portlet.faces.encodeRedirectURL</code>: instructs the bridge to call 241 * <code>ExternalContext.encodeActionURL()</code> before processing the redirect request. This 242 * exists because some (newer) versions of JSF 1.2 call <code>encodeActionURL</code> before 243 * calling <code>redirect</code> while others do not. This flag adjusts the behavior of the 244 * bridge in accordance with the JSF 1.2 implementation it runs with. 245 * <li><code>javax.portlet.faces.numManagedActionScopes</code>: defines the maximum number of 246 * actionScopes this bridge preserves at any given time. Value is an integer. ActionScopes are 247 * managed on a per Bridge class portlet context wide basis. As a typical portlet application uses 248 * the same bridge implementation for all its Faces based portlets, this means that all 249 * actionScopes are managed in a single bucket.<br> 250 * For convenience this interface defines the <code>NUM_MANAGED_ACTIONSCOPES</code> constant. 251 * <li><code>javax.faces.lifecycleID</code>: defines the Faces <code>Lifecycle</code> id 252 * that bridge uses when acquiring the <code>Faces.Lifecycle</code> via which it executes the 253 * request. As a context wide attribute, all bridge instances in this portlet application will use 254 * this lifecyle. 255 * <li><code>javax.portlet.faces.[portlet name].preserveActionParams</code>: instructs the 256 * bridge to preserve action parameters in the action scope and represent them in subsequent 257 * renders. Should be used only when binding to a Faces implementation that relies on accessing 258 * such parameters during its render phase. As this is a portlet/bridge instance specific 259 * attribute, the <code>PortletContext</code>attribute name is qualified by the portlet 260 * instance name. This allows different portlets within the same portlet application to have 261 * different settings.<br> 262 * For convenience this interfaces defines a number of constants that simplifies constructing 263 * and/or recognizing this name. 264 * </ul> 265 * 266 * @param config 267 * a <code>PortletConfig</code> object containing the portlet's configuration and 268 * initialization parameters 269 * @exception BridgeException 270 * if an exception has occurred that interferes with the bridge's normal operation. 271 * For example, if the bridge is already initialized. 272 * @exception UnavailableException 273 * if the portlet cannot perform the initialization at this time. 274 */ 275 public void init(PortletConfig config) throws BridgeException; 276 277 /** 278 * Called by the portlet when it wants the bridge to process an action request. 279 * 280 * @param request 281 * the request object. 282 * @param response 283 * the response object. 284 * @throws BridgeDefaultViewNotSpecifiedException 285 * thrown if the request indicates to the Bridge that is should use the default ViewId 286 * and the portlet hasn't supplied one. 287 * @throws BridgeUninitializedException 288 * thrown if the bridge is not initialized. 289 * @throws BridgeException 290 * all other internal exceptions are converted to a BridgeException. 291 */ 292 public void doFacesRequest(ActionRequest request, ActionResponse response) 293 throws BridgeDefaultViewNotSpecifiedException, 294 BridgeException; 295 296 /** 297 * Called by the portlet when it wants the bridge to process a render request. 298 * 299 * @param request 300 * the request object. 301 * @param response 302 * the response object. 303 * @throws BridgeDefaultViewNotSpecifiedException 304 * thrown if the request indicates to the Bridge that is should use the default ViewId 305 * and the portlet hasn't supplied one. 306 * @throws BridgeUninitializedException 307 * thrown if the bridge is not initialized. 308 * @throws BridgeException 309 * all other internal exceptions are converted to a BridgeException. 310 */ 311 public void doFacesRequest(RenderRequest request, RenderResponse response) 312 throws BridgeDefaultViewNotSpecifiedException, 313 BridgeException; 314 315 /** 316 * Called by the portlet to take the bridge out of service. Once out of service, the bridge must 317 * be reinitialized before processing any further requests. 318 */ 319 public void destroy(); 320 321 }