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