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 public interface 046 047 Bridge 048 { 049 050 // Base Bridge attribute/context parameter prefix 051 public static final String BRIDGE_PACKAGE_PREFIX = "javax.portlet.faces."; 052 053 // Following are the names of context init parameters that control 054 // Bridge behavior. These are specified in the web.xml 055 056 /** 057 * Context initialization parameter that specifies the maximum number of bridge 058 * request scopes to preserved across all uses within this application. 059 */ 060 public static final String MAX_MANAGED_REQUEST_SCOPES = 061 BRIDGE_PACKAGE_PREFIX + "MAX_MANAGED_REQUEST_SCOPES"; 062 063 /** 064 * Context initialization parameter that defines the policy the bridge uses for 065 * rendering. Parameter value is the string representaiton of one of the 066 * BridgeRenderPolicy enum values. 067 */ 068 public static final String RENDER_POLICY = BRIDGE_PACKAGE_PREFIX + "RENDER_POLICY"; 069 070 /** 071 * Context initialization parameter that defines the lifecycle ID used to 072 * identify the Faces Lifecycle used for this application. 073 */ 074 public static final String LIFECYCLE_ID = "javax.faces.LIFECYCLE_ID"; 075 076 /** 077 * Context initialization parameter that defines the SAVESTATE_FIELD_MARKER 078 * in use in the given deployment. If not set, consult your bridge implementation 079 * documentation to determine which Faces implementations it automatically 080 * detects and supports. For example the bridge RI will detect and run 081 * properly in either the Faces RI or MyFaces environments without this being set. 082 */ 083 public static final String SAVESTATE_FIELD_MARKER = 084 BRIDGE_PACKAGE_PREFIX + "SAVESTATE_FIELD_MARKER"; 085 086 // Following are the names of context init attributes set by the portlet to control 087 // Bridge behavior. For the GenericFacesPortlet, the values for these come from 088 // portlet initialization parameters in the portlet.xml 089 090 /** A PortletContext attribute that a portlet can set prior 091 * to calling the bridge's init() method to configure the bridge to preserve 092 * action parameters received by this portlet along with bridge's request scope so 093 * that they may be restored and acessed in subsequent renders. If "true", the 094 * action parameters are preserved. If "false", they are not preserved. The bridge 095 * default is "false".<br> 096 * 097 * As this attribute is scoped to a specific portlet in an application-wide context 098 * the attribute name must be include the portlet name as follows: 099 * BRIDGE_PACKAGE_PREFIX + context.getPortletName() + preserveActionParams 100 */ 101 public static final String PRESERVE_ACTION_PARAMS = "preserveActionParams"; 102 103 104 /** A PortletContext attribute that a portlet can set prior 105 * to calling the bridge's init() method to configure the bridge to exclude 106 * specific attributes from its bridge request scope. Value is a comma delimited 107 * list containing either a fully qualified attribute name or package name terminated 108 * with a ".*" wildcard indicator. In this later case, all attributes in the package 109 * name which precedes the ".*" are excluded, non recursive.<br> 110 * 111 * As this attribute is scoped to a specific portlet in an application-wide context 112 * the attribute name must be include the portlet name as follows: 113 * BRIDGE_PACKAGE_PREFIX + context.getPortletName() + excludedRequestAttributes 114 */ 115 public static final String EXCLUDED_REQUEST_ATTRIBUTES = "excludedRequestAttributes"; 116 117 /** PortletContext attribute that a portlet must set prior 118 * to calling the bridge's init() method to convey to the bridge the set of default 119 * viewIds that correspond to this portlet's supported <code>PortletMode</code>s. 120 * Its value is a Map with one entry per mode. The mode name is the key. The entry's 121 * value is the corresponding default viewId the bridge should use for this mode. 122 * <br> 123 * 124 * As this attribute is scoped to a specific portlet in an application-wide context 125 * the attribute name must be include the portlet name as follows: 126 * BRIDGE_PACKAGE_PREFIX + context.getPortletName() + DEFAULT_VIEWID_MAP 127 */ 128 public static final String DEFAULT_VIEWID_MAP = "defaultViewIdMap"; 129 130 // The following are request attributes a portlet can set to control the request 131 // processing of the bridge. 132 133 /** PortletRequest attribute that a portlet may set prior 134 * to calling the bridge's doFacesRequest() method. The value of this 135 * attribute is a <code>String</code> representing the Faces viewId the 136 * bridge is to target for this request. Used by a portlet to specifically 137 * control a request's view target in situations such as navigating from 138 * a nonFaces view to a specific Faces view (other than the default).<p> 139 * Generally, the use of this attribute is mutually exclusive with the use 140 * of VIEW_PATH. If both have been set in a given request, the bridge gives 141 * precedence to VIEW_ID. 142 */ 143 public static final String VIEW_ID = BRIDGE_PACKAGE_PREFIX + "viewId"; 144 145 /** PortletRequest attribute that a portlet may set prior 146 * to calling the bridge's doFacesRequest() method. The value of this 147 * attribute is a <code>String</code> containing a <code>ContextPath</code> 148 * relative path in which the Faces viewId is encoded. Like VIEW_ID, this 149 * attribute provides a means for a portlet to explicitly control the Faces 150 * target for a specific request. It is used in situations such as navigating from 151 * a nonFaces view to a specific Faces view (other than the default).<p> 152 * Generally, the use of this attribute is mutually exclusive with the use 153 * of VIEW_PATH. If both have been set in a given request, the bridge gives 154 * precedence to VIEW_ID. 155 */ 156 public static final String VIEW_PATH = BRIDGE_PACKAGE_PREFIX + "viewPath"; 157 158 // Names for special QueryString parameters names the Bridge recognizes in 159 // encodeActionURL as signifying to change the corresponding portlet values 160 // in the resulting URL 161 162 /** 163 * Special token parameter in the url passed to the bridge's ExternalContext.encodeActionURL() 164 * that it recognizes as an indication that this action should encode a PortletMode 165 * change to the one indicated by the parameter's value. 166 */ 167 public static final String PORTLET_MODE_PARAMETER = BRIDGE_PACKAGE_PREFIX + "PortletMode"; 168 169 /** 170 * Special token parameter in the url passed to the bridge's ExternalContext.encodeActionURL() 171 * that it recognizes as an indication that this action should encode a WindowState change to 172 * the one indicated by the parameter's value. 173 */ 174 public static final String PORTLET_WINDOWSTATE_PARAMETER = BRIDGE_PACKAGE_PREFIX + "WindowState"; 175 176 /** 177 * Special token parameter in the url passed to the bridge's ExternalContext.encodeActionURL() 178 * that it recognizes as an indication that this action should encode a security level change to 179 * the one indicated by the parameter's value. 180 */ 181 public static final String PORTLET_SECURE_PARAMETER = BRIDGE_PACKAGE_PREFIX + "Secure"; 182 183 /** 184 * Special token parameter in the url passed to the bridge's ExternalContext.encodeActionURL() 185 * that it recognizes as an indication that this action should be treated as a direct link 186 * and hence shouldn't be encoded as a Portlet action. Rather encodeActionURL merely returns 187 * this url unchanged. 188 */ 189 public static final String DIRECT_LINK = BRIDGE_PACKAGE_PREFIX + "DirectLink"; 190 191 /** 192 * Special token parameter in the url passed to the bridge's ExternalContext.encodeResourceURL() 193 * that it recognizes as an indication that an URL refering back to the page which 194 * contains this portlet should be encoded in the resource url. This reference is 195 * encoded as the value of a query string parameter whose name is the value of this back 196 * link token parameter. 197 */ 198 public static final String BACK_LINK = BRIDGE_PACKAGE_PREFIX + "BackLink"; 199 200 /** 201 * Special token parameter in the url passed to the bridge's ExternalContext.encodeResourceURL() 202 * that it recognizes as an indication that this url refers to Faces view (navigation) and 203 * hence should be encoded as an portlet ActionURL rather then a portlet resource url. This token 204 * is intended for use in urls signifying a view navigation using components such as 205 * <code>h:outputLink</code>. 206 */ 207 public static final String VIEW_LINK = BRIDGE_PACKAGE_PREFIX + "ViewLink"; 208 209 210 // Request attributes set by the bridge that can be used by Faces extensions 211 // and/or applications to properly run in a portlet environment. 212 213 /** 214 * A PortletRequest attribute set by the bridge when processing a Faces request 215 * that signals this request is a Faces postback. Its provided as 216 * an alternative signal to the common reliance on the view state parameter as 217 * an indicator that this is a postback request. Implementations needing this 218 * information and not using the view state parameter indicator can check this 219 * attribute when running in a portlet environment. 220 */ 221 public static final String IS_POSTBACK_ATTRIBUTE = BRIDGE_PACKAGE_PREFIX + "isPostback"; 222 223 /** A PortletRequest attribute set by the bridge in its 224 * <code>ViewHandler.renderView</code> prior to dispatching the request 225 * to the view (jsp)to indicating a filter should 226 * put the AFTER_VIEW_CONTENT in a buffer on the request for it to process after 227 * rendering the view components. In conjunction with the filter this enables 228 * preserving rendering order of native JSP rendering and Faces rendering in a jsp. 229 */ 230 public static final String RENDER_CONTENT_AFTER_VIEW = 231 BRIDGE_PACKAGE_PREFIX + "RenderContentAfterView"; 232 233 /** A PortletRequest attribute set by an include filter in recognition of the 234 * RenderContentAfterView bridge attribute. Its value is either char[] or byte[] 235 * holding the AFTER_VIEW_CONTENT generated while rendering this jsp. 236 * In conjunction with the bridge this enables 237 * preserving rendering order of native JSP rendering and Faces rendering in a jsp. 238 */ 239 public static final String AFTER_VIEW_CONTENT = BRIDGE_PACKAGE_PREFIX + "AfterViewContent"; 240 241 /** PortletRequest attribute set by the bridge prior to creating/acquiring a 242 * <code>FacesContext</code>. Its value indicates which portlet phase this 243 * Faces is executing in. It can be used by Faces subsystems not only to determine 244 * the portlet exectution phase but if present (not null) as an indication the request 245 * is being processed in a portlet container. 246 */ 247 public static final String PORTLET_LIFECYCLE_PHASE = BRIDGE_PACKAGE_PREFIX + "phase"; 248 249 /** PortletSession attribute set by the bridge to hold the last viewId accessed in a given mode. 250 * The attribute (key) is composed of this name + the mode name. I.e. 251 * javax.portlet.faces.viewIdHistory.view. There is one attribute per supported portlet 252 * mode. The attributes are always set even if the user session has never entered the 253 * mode. Its initial setting/value is determined by the default viewId configured 254 * for the mode. Attribute is used by developers to reference/return to the last view in 255 * a given Mode from another mode. 256 */ 257 public static final String VIEWID_HISTORY = BRIDGE_PACKAGE_PREFIX + "viewIdHistory"; 258 259 260 /** Name of PortletResponse property set by the bridge when it recognizes that the 261 * view has been rendered using a <code>NamingContainer</code> that ensures all 262 * generated ids are namespaced using the consumer provided unique portlet id. 263 */ 264 public static final String PORTLET_NAMESPACED_RESPONSE_PROPERTY = 265 "X-JAVAX-PORTLET-FACES-NAMESPACED-RESPONSE"; 266 267 /** Name of the render parameter set by the bridge when it encodes a navigation 268 * link to a nonFaces target. Though the bridge recognizes nonFaces targets when 269 * it encodes a navigational link, it does not handle the subsequent request. 270 * It only handles requests for Faces targets. It is the portlet's responsibility 271 * to detect and handle these requests. When the nonFaces target is a path based 272 * resource (such as a jsp or servlet), the <code>ContextPath</code> relative path 273 * of the resource is written as the value of this render parameter. For convenience, 274 * the GenericFacesPortlet recognizes this render parameter in received requests 275 * and uses the <code>PortletRequestDispatcher</code> to dispatch to the encoded 276 * path instead of calling the bridge to execute the request. 277 */ 278 public static final String NONFACES_TARGET_PATH_PARAMETER = "_jsfBridgeNonFacesView"; 279 280 /** Name of a request parameter (generally) encoded in a link from a nonFaces 281 * view response. It acts as a marker to the portlet that the nonFaces view 282 * intends to navigate to the Faces view expressed in the value of this parameter. 283 * It differs from the <code>FACES_VIEW_PATH_PARAMETER</code> in that its value 284 * is the actual Faces viewId of the target while the formaer is a 285 * <code>ContextPath</code> relative path containing the viewId.<p> 286 * Portlets receiving such a parameter should set the the corresponding request 287 * attribute <code>javax.portlet.faces.viewId</code> before calling the bridge 288 * to handle the request. 289 */ 290 public static final String FACES_VIEW_ID_PARAMETER = "_jsfBridgeViewId"; 291 292 /** Name of a request parameter (generally) encoded in a link from a nonFaces 293 * view response. It acts as a marker to the portlet that the nonFaces view 294 * intends to navigate to the Faces view expressed in the value of this parameter. 295 * It differs from the <code>FACES_VIEW_ID_PARAMETER</code> in that its value 296 * is a <code>ContextPath</code> relative path containing the viewId while the former 297 * is the viewId itself.<p> 298 * Portlets receiving such a parameter should set the the corresponding request 299 * attribute <code>javax.portlet.faces.viewPath</code> before calling the bridge 300 * to handle the request. 301 */ 302 public static final String FACES_VIEW_PATH_PARAMETER = "_jsfBridgeViewPath"; 303 304 305 /** Special value recognized during <code>encodeActionURL</code> of a portlet: url containing either 306 * the <code>_jsfBridgeViewId</code> or <code>_jsfBridgeViewPath</code> parameter. 307 * <code>encodeActionURL</code> recognizes this value as indicating it needs to generate and 308 * encode an URL to the current JSF including its current state. I.e. It not only 309 * encodes the link reference but also the existing render parameters so they can be carried forward 310 * to reestablish the state. 311 */ 312 public static final String FACES_USE_CURRENT_VIEW_PARAMETER = "_jsfBridgeCurrentView"; 313 314 /** Enumeration whose values describe the current portlet phase the bridge 315 * is executing Faces within. 316 */ 317 public static enum PortletPhase 318 { 319 ACTION_PHASE, 320 RENDER_PHASE, 321 ; 322 } 323 324 /** Enumeration whose values describe the render policy used by the bridge 325 * to render portlets in this application. A policy of DEFAULT indicates 326 * the bridge will first delegate rendering and if this results in an 327 * exception being thrown will render the itself. A policy of ALWAYS_DELEGATE 328 * indicates the bridge will always delegate rendering, never rendering itself. 329 * A policy of NEVER_DELEGATE indicates the bridge will always render itself without 330 * delegating. 331 */ 332 public static enum BridgeRenderPolicy 333 { 334 DEFAULT, 335 ALWAYS_DELEGATE, 336 NEVER_DELEGATE, 337 ; 338 } 339 340 /** 341 * Called by the portlet. It indicates that the bridge is being placed into service. 342 * <p> 343 * The portlet calls the <code>init</code> method exactly once before invoking other lifecycle 344 * methods. Usually, done immediately after instantiating the bridge. The <code>init</code> 345 * method must complete successfully before the bridge can receive any requests. 346 * <p> 347 * The portlet cannot place the bridge into service if the <code>init</code> method Throws a 348 * <code>BridgeException</code>. 349 * <p> 350 * Initialization context is passed to bridge via <code>PortletContext</code> attributes. The 351 * following attributes are defined: 352 * <ul> 353 * <li><code>javax.portlet.faces.encodeRedirectURL</code>: instructs the bridge to call 354 * <code>ExternalContext.encodeActionURL()</code> before processing the redirect request. This 355 * exists because some (newer) versions of JSF 1.2 call <code>encodeActionURL</code> before 356 * calling <code>redirect</code> while others do not. This flag adjusts the behavior of the 357 * bridge in accordance with the JSF 1.2 implementation it runs with. 358 * <li><code>javax.portlet.faces.numManagedActionScopes</code>: defines the maximum number of 359 * actionScopes this bridge preserves at any given time. Value is an integer. ActionScopes are 360 * managed on a per Bridge class portlet context wide basis. As a typical portlet application uses 361 * the same bridge implementation for all its Faces based portlets, this means that all 362 * actionScopes are managed in a single bucket.<br> 363 * For convenience this interface defines the <code>NUM_MANAGED_ACTIONSCOPES</code> constant. 364 * <li><code>javax.faces.lifecycleID</code>: defines the Faces <code>Lifecycle</code> id 365 * that bridge uses when acquiring the <code>Faces.Lifecycle</code> via which it executes the 366 * request. As a context wide attribute, all bridge instances in this portlet application will use 367 * this lifecyle. 368 * <li><code>javax.portlet.faces.[portlet name].preserveActionParams</code>: instructs the 369 * bridge to preserve action parameters in the action scope and represent them in subsequent 370 * renders. Should be used only when binding to a Faces implementation that relies on accessing 371 * such parameters during its render phase. As this is a portlet/bridge instance specific 372 * attribute, the <code>PortletContext</code>attribute name is qualified by the portlet 373 * instance name. This allows different portlets within the same portlet application to have 374 * different settings.<br> 375 * For convenience this interfaces defines a number of constants that simplifies constructing 376 * and/or recognizing this name. 377 * </ul> 378 * 379 * @param config 380 * a <code>PortletConfig</code> object containing the portlet's configuration and 381 * initialization parameters 382 * @exception BridgeException 383 * if an exception has occurred that interferes with the bridge's normal operation. 384 * For example, if the bridge is already initialized. 385 * @exception UnavailableException 386 * if the portlet cannot perform the initialization at this time. 387 */ 388 public void init(PortletConfig config) throws BridgeException; 389 390 /** 391 * Called by the portlet when it wants the bridge to process an action request. 392 * 393 * @param request 394 * the request object. 395 * @param response 396 * the response object. 397 * @throws BridgeDefaultViewNotSpecifiedException 398 * thrown if the request indicates to the Bridge that is should use the default ViewId 399 * and the portlet hasn't supplied one. 400 * @throws BridgeUninitializedException 401 * thrown if the bridge is not initialized. 402 * @throws BridgeException 403 * all other internal exceptions are converted to a BridgeException. 404 */ 405 public void doFacesRequest(ActionRequest request, 406 ActionResponse response) throws BridgeDefaultViewNotSpecifiedException, 407 BridgeUninitializedException, 408 BridgeException; 409 410 /** 411 * Called by the portlet when it wants the bridge to process a render request. 412 * 413 * @param request 414 * the request object. 415 * @param response 416 * the response object. 417 * @throws BridgeDefaultViewNotSpecifiedException 418 * thrown if the request indicates to the Bridge that is should use the default ViewId 419 * and the portlet hasn't supplied one. 420 * @throws BridgeUninitializedException 421 * thrown if the bridge is not initialized. 422 * @throws BridgeException 423 * all other internal exceptions are converted to a BridgeException. 424 */ 425 public void doFacesRequest(RenderRequest request, 426 RenderResponse response) throws BridgeDefaultViewNotSpecifiedException, 427 BridgeUninitializedException, 428 BridgeException; 429 430 /** 431 * Called by the portlet to take the bridge out of service. Once out of service, the bridge must 432 * be reinitialized before processing any further requests. 433 */ 434 public void destroy(); 435 436 }