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