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    }