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    }