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    
046    public interface Bridge
047    {
048    
049      // Base Bridge attribute/context parameter prefix
050      public static final String BRIDGE_PACKAGE_PREFIX         = "javax.portlet.faces.";
051    
052      // Following are the names of context init parameters that control
053      // Bridge behavior. These are specified in the web.xml
054    
055      /**
056       * Context initialization parameter that specifies the maximum number of bridge
057       * request scopes to preserved across all uses within this application.
058       */
059      public static final String MAX_MANAGED_REQUEST_SCOPES    = BRIDGE_PACKAGE_PREFIX
060                                                                 + "MAX_MANAGED_REQUEST_SCOPES";
061      
062      /**
063       * Context initialization parameter that defines the policy the bridge uses for
064       * rendering.  Parameter value is the string representaiton of one of the 
065       * BridgeRenderPolicy enum values.
066       */  
067      public static final String RENDER_POLICY                 = BRIDGE_PACKAGE_PREFIX
068                                                                  + "RENDER_POLICY";
069      /**
070       * Context initialization parameter that defines the lifecycle ID used to 
071       * identify the Faces Lifecycle used for this application.
072       */ 
073      public static final String LIFECYCLE_ID                  = "javax.faces.LIFECYCLE_ID";
074    
075      /**
076       * Bridge attribute that signals this request is a Faces postback.  Its provided as
077       * an alternative signal to the common reliance on the view state parameter as
078       * an indicator that this is a postback request.  Implementations needing this 
079       * information and not using the view state parameter indicator can check this 
080       * attribute when running in a portlet environment.
081       */ 
082      // Attribute signifying whether this render is a postback or not.
083      public static final String IS_POSTBACK_ATTRIBUTE         = BRIDGE_PACKAGE_PREFIX + "isPostback";
084    
085      // Names for special QueryString parameters names the Bridge recognizes in
086      // encodeActionURL as signifying to change the corresponding portlet values
087      // in the resulting URL
088      
089      /**
090       * Special token parameter in the url passed to the bridge's ExternalContext.encodeActionURL()
091       * that it recognizes as an indication that this action should encode a PortletMode
092       * change to the one indicated by the parameter's value.
093       */
094      public static final String PORTLET_MODE_PARAMETER = BRIDGE_PACKAGE_PREFIX + "PortletMode";
095      
096      /**
097       * Special token parameter in the url passed to the bridge's ExternalContext.encodeActionURL()
098       * that it recognizes as an indication that this action should encode a WindowState change to
099       * the one indicated by the parameter's value.
100       */
101      public static final String PORTLET_WINDOWSTATE_PARAMETER = BRIDGE_PACKAGE_PREFIX + "WindowState";
102    
103      /**
104       * Special token parameter in the url passed to the bridge's ExternalContext.encodeActionURL()
105       * that it recognizes as an indication that this action should encode a security level change to
106       * the one indicated by the parameter's value.
107       */
108      public static final String PORTLET_SECURE_PARAMETER = BRIDGE_PACKAGE_PREFIX + "Secure";
109    
110      /**
111       * Special token parameter in the url passed to the bridge's ExternalContext.encodeActionURL()
112       * that it recognizes as an indication that this action should be treated as a direct link
113       * and hence shouldn't be encoded as a Portlet action.  Rather encodeActionURL merely returns
114       * this url unchanged.
115       */
116      public static final String DIRECT_LINK                   = BRIDGE_PACKAGE_PREFIX + "DirectLink";
117    
118      /**
119       * Special token parameter in the url passed to the bridge's ExternalContext.encodeResourceURL()
120       * that it recognizes as an indication that an URL refering back to the page which
121       * contains this portlet should be encoded in the resource url. This reference is
122       * encoded as the value of a query string parameter whose name is the value of this back
123       * link token parameter.
124       */  
125    
126      public static final String BACK_LINK                     = BRIDGE_PACKAGE_PREFIX + "BackLink";
127    
128      /**
129       * Special token parameter in the url passed to the bridge's ExternalContext.encodeResourceURL()
130       * that it recognizes as an indication that this url refers to Faces view (navigation) and
131       * hence should be encoded as an portlet ActionURL rather then a portlet resource url.  This token
132       * is intended for use in urls signifying a view navigation using components such as
133       * <code>h:outputLink</code>. 
134       */  
135    
136      public static final String VIEW_LINK                     = BRIDGE_PACKAGE_PREFIX + "ViewLink";
137       
138      /** A PortletContext attribute that a portlet can set prior
139       * to calling the bridge's init() method to configure the bridge to preserve
140       * action parameters received by this portlet along with bridge's request scope so
141       * that they may be restored and acessed in subsequent renders.  If "true", the
142       * action parameters are preserved.  If "false", they are not preserved.  The bridge
143       * default is "false".
144       *
145       * As this attribute is scoped to a specific portlet in an application-wide context
146       * the attribute name must be include the portlet name as follows:
147       * BRIDGE_PACKAGE_PREFIX + context.getPortletName() + preserveActionParams
148       */
149      public static final String PRESERVE_ACTION_PARAMS        = "preserveActionParams";
150    
151    
152      /** A PortletContext attribute that a portlet can set prior
153       * to calling the bridge's init() method to configure the bridge to exclude
154       * specific attributes from its bridge request scope. Value is a comma delimited
155       * list containing either a fully qualified attribute name or package name terminated
156       * with a ".*" wildcard indicator.  In this later case, all attributes in the package
157       * name which precedes the ".*" are excluded, non recursive.
158       *
159       * As this attribute is scoped to a specific portlet in an application-wide context
160       * the attribute name must be include the portlet name as follows:
161       * BRIDGE_PACKAGE_PREFIX + context.getPortletName() + excludedRequestAttributes
162       */
163      public static final String EXCLUDED_REQUEST_ATTRIBUTES    = "excludedRequestAttributes";
164    
165    
166      /** A PortletRequest attribute set by the bridge in its
167       * <code>ViewHandler.renderView</code> prior to dispatching the request
168       * to the view (jsp)to indicating a filter should
169       * put the AFTER_VIEW_CONTENT in a buffer on the request for it to process after
170       * rendering the view components.  In conjunction with the filter this enables
171       * preserving rendering order of native JSP rendering and Faces rendering in a jsp.
172       */
173      public static final String RENDER_CONTENT_AFTER_VIEW     = BRIDGE_PACKAGE_PREFIX
174                                                                 + "RenderContentAfterView";
175      /** A PortletRequest attribute set by an include filter in recognition of the
176       * RenderContentAfterView bridge attribute.  Its value is either char[] or byte[]
177       * holding the AFTER_VIEW_CONTENT generated while rendering this jsp.
178       * In conjunction with the bridge this enables
179       * preserving rendering order of native JSP rendering and Faces rendering in a jsp.
180       */
181      public static final String AFTER_VIEW_CONTENT            = BRIDGE_PACKAGE_PREFIX
182                                                                 + "AfterViewContent";
183    
184      /** PortletRequest attribute set by the portlet prior to calling the bridge's
185       * <code>doFacesRequest()</code> method.  Its value is the default viewId the
186       * bridge is to use if it can't otherwise decode one from the request.
187       */
188      public static final String DEFAULT_VIEWID                = BRIDGE_PACKAGE_PREFIX
189                                                                 + "defaultViewId";
190      
191      /** PortletRequest attribute set by the bridge prior to creating/acquiring a
192       * <code>FacesContext</code>.  Its value indicates which portlet phase this 
193       * Faces is executing in.  It can be used by Faces subsystems not only to determine
194       * the portlet exectution phase but if present (not null) as an indication the request
195       * is being processed in a portlet container.
196       */
197      public static final String PORTLET_LIFECYCLE_PHASE       = BRIDGE_PACKAGE_PREFIX + "phase";
198    
199      /** Name of PortletResponse property set by the bridge when it recognizes that the 
200       * view has been rendered using a <code>NamingContainer</code> that ensures all
201       * generated ids are namespaced using the consumer provided unique portlet id.
202       */
203      public static final String PORTLET_NAMESPACED_RESPONSE_PROPERTY = "X-JAVAX-PORTLET-NAMESPACED-RESPONSE";
204    
205      /** Enumeration whose values describe the current portlet phase the bridge
206       * is executing Faces within.
207       */
208    
209      public static enum PortletPhase
210      {
211        ACTION_PHASE, RENDER_PHASE;
212      }
213    
214      /** Enumeration whose values describe the render policy used by the bridge
215       * to render portlets in this application.  A policy of DEFAULT indicates
216       * the bridge will first delegate rendering and if this results in an
217       * exception being thrown will render the itself.  A policy of ALWAYS_DELEGATE
218       * indicates the bridge will always delegate rendering, never rendering itself.
219       * A policy of NEVER_DELEGATE indicates the bridge will always render itself without
220       * delegating.
221       */
222      public static enum BridgeRenderPolicy
223      {
224        DEFAULT, ALWAYS_DELEGATE, NEVER_DELEGATE;
225      }
226    
227      /**
228       * Called by the portlet. It indicates that the bridge is being placed into service.
229       * <p>
230       * The portlet calls the <code>init</code> method exactly once before invoking other lifecycle
231       * methods. Usually, done immediately after instantiating the bridge. The <code>init</code>
232       * method must complete successfully before the bridge can receive any requests.
233       * <p>
234       * The portlet cannot place the bridge into service if the <code>init</code> method Throws a
235       * <code>BridgeException</code>.
236       * <p>
237       * Initialization context is passed to bridge via <code>PortletContext</code> attributes. The
238       * following attributes are defined:
239       * <ul>
240       * <li><code>javax.portlet.faces.encodeRedirectURL</code>: instructs the bridge to call
241       * <code>ExternalContext.encodeActionURL()</code> before processing the redirect request. This
242       * exists because some (newer) versions of JSF 1.2 call <code>encodeActionURL</code> before
243       * calling <code>redirect</code> while others do not. This flag adjusts the behavior of the
244       * bridge in accordance with the JSF 1.2 implementation it runs with.
245       * <li><code>javax.portlet.faces.numManagedActionScopes</code>: defines the maximum number of
246       * actionScopes this bridge preserves at any given time. Value is an integer. ActionScopes are
247       * managed on a per Bridge class portlet context wide basis. As a typical portlet application uses
248       * the same bridge implementation for all its Faces based portlets, this means that all
249       * actionScopes are managed in a single bucket.<br>
250       * For convenience this interface defines the <code>NUM_MANAGED_ACTIONSCOPES</code> constant.
251       * <li><code>javax.faces.lifecycleID</code>: defines the Faces <code>Lifecycle</code> id
252       * that bridge uses when acquiring the <code>Faces.Lifecycle</code> via which it executes the
253       * request. As a context wide attribute, all bridge instances in this portlet application will use
254       * this lifecyle.
255       * <li><code>javax.portlet.faces.[portlet name].preserveActionParams</code>: instructs the
256       * bridge to preserve action parameters in the action scope and represent them in subsequent
257       * renders. Should be used only when binding to a Faces implementation that relies on accessing
258       * such parameters during its render phase. As this is a portlet/bridge instance specific
259       * attribute, the <code>PortletContext</code>attribute name is qualified by the portlet
260       * instance name. This allows different portlets within the same portlet application to have
261       * different settings.<br>
262       * For convenience this interfaces defines a number of constants that simplifies constructing
263       * and/or recognizing this name.
264       * </ul>
265       * 
266       * @param config
267       *          a <code>PortletConfig</code> object containing the portlet's configuration and
268       *          initialization parameters
269       * @exception BridgeException
270       *              if an exception has occurred that interferes with the bridge's normal operation.
271       *              For example, if the bridge is already initialized.
272       * @exception UnavailableException
273       *              if the portlet cannot perform the initialization at this time.
274       */
275      public void init(PortletConfig config) throws BridgeException;
276    
277      /**
278       * Called by the portlet when it wants the bridge to process an action request.
279       * 
280       * @param request
281       *          the request object.
282       * @param response
283       *          the response object.
284       * @throws BridgeDefaultViewNotSpecifiedException
285       *           thrown if the request indicates to the Bridge that is should use the default ViewId
286       *           and the portlet hasn't supplied one.
287       * @throws BridgeUninitializedException
288       *           thrown if the bridge is not initialized.          
289       * @throws BridgeException
290       *           all other internal exceptions are converted to a BridgeException.
291       */
292      public void doFacesRequest(ActionRequest request, ActionResponse response)
293                                                                                throws BridgeDefaultViewNotSpecifiedException,
294                                                                                BridgeException;
295    
296      /**
297       * Called by the portlet when it wants the bridge to process a render request.
298       * 
299       * @param request
300       *          the request object.
301       * @param response
302       *          the response object.
303       * @throws BridgeDefaultViewNotSpecifiedException
304       *           thrown if the request indicates to the Bridge that is should use the default ViewId
305       *           and the portlet hasn't supplied one.
306       * @throws BridgeUninitializedException
307       *           thrown if the bridge is not initialized.      
308       * @throws BridgeException
309       *           all other internal exceptions are converted to a BridgeException.
310       */
311      public void doFacesRequest(RenderRequest request, RenderResponse response)
312                                                                                throws BridgeDefaultViewNotSpecifiedException,
313                                                                                BridgeException;
314    
315      /**
316       * Called by the portlet to take the bridge out of service. Once out of service, the bridge must
317       * be reinitialized before processing any further requests.
318       */
319      public void destroy();
320    
321    }