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      public static final String MAX_MANAGED_REQUEST_SCOPES    = BRIDGE_PACKAGE_PREFIX
056                                                                 + "MAX_MANAGED_REQUEST_SCOPES";
057      public static final String RENDER_POLICY                 = BRIDGE_PACKAGE_PREFIX
058                                                                  + "RENDER_POLICY";
059    
060      public static final String LIFECYCLE_ID                  = "javax.faces.LIFECYCLE_ID";
061    
062      // Attribute signifying whether this render is a postback or not.
063      public static final String IS_POSTBACK_ATTRIBUTE         = BRIDGE_PACKAGE_PREFIX + "isPostback";
064    
065      // Special session attribute name to hold the application_scope in the
066      // portlet_scope of the session so these are accessible as well.
067      public static final String APPLICATION_SCOPE_MAP         = "javax.portlet.faces.ApplicationScopeMap";
068      
069      // Names for special QueryString parameters names the Bridge recognizes in
070      // encodeActionURL as signifying to change the corresponding portlet values
071      // in the resulting URL
072      public static final String PORTLET_MODE_PARAMETER = BRIDGE_PACKAGE_PREFIX + "PortletMode";
073      public static final String PORTLET_WINDOWSTATE_PARAMETER = BRIDGE_PACKAGE_PREFIX + "WindowState";
074      public static final String PORTLET_SECURE_PARAMETER = BRIDGE_PACKAGE_PREFIX + "Secure";
075    
076      // Following are the names of context attributes that a portlet can set prior
077      // to calling the bridge's init() method to control Bridge behavior.
078    
079      // These attributes are scoped to a specific portlet in the context
080      // hence to acquire one must include the portlet name within attribute name:
081      // BRIDGE_PACKAGE_PREFIX + context.getPortletName() + attributeName
082    
083      // if "true" indicates the bridge will preserve all the action params in its
084      // request scope and restore them as parameters in the subsequent renders
085      public static final String PRESERVE_ACTION_PARAMS        = "preserveActionParams";
086    
087      // allows a portlet to which request attributes the bridge excludes from its
088      // managed request scope.
089      public static final String EXCLUDED_REQUEST_ATTRIBUTES    = "excludedRequestAttributes";
090    
091      // Parameter that can be added to an ActionURL to signify it is a direct link
092      // and hence shouldn't be encoded by encodeActionURL as an actionURL
093      public static final String DIRECT_LINK                   = BRIDGE_PACKAGE_PREFIX + "DirectLink";
094    
095      // Session attribute pushed by bridge into session scope to give one access
096      // to Application scope
097      public static final String SESSION_APPLICATION_SCOPE_MAP = BRIDGE_PACKAGE_PREFIX
098                                                                 + "ApplicationScopeMap";
099    
100      // Request attribute pushed by bridge in renderView to indicate it can
101      // handle a filter putting the AFTER_VIEW_CONTENT in a buffer on the request.
102      // Allows rendering order to be preserved in jsps
103      public static final String RENDER_CONTENT_AFTER_VIEW     = BRIDGE_PACKAGE_PREFIX
104                                                                 + "RenderContentAfterView";
105    
106      // Request attribute set by servlet filter in request/responseWrapper to
107      // place the AFTER_VIEW_CONTENT in a buffer on the request.
108      // Allows filter to transfer such content back to the bridge/renderView so
109      // if can output in correct order. Should only be done if
110      // RENDER_CONTENT_AFTER_VIEW request attribute is true.
111      public static final String AFTER_VIEW_CONTENT            = BRIDGE_PACKAGE_PREFIX
112                                                                 + "AfterViewContent";
113    
114      // Following are names of request attributes a portlet must set before
115      // calling the Bridge to process a request
116      public static final String DEFAULT_VIEWID                = BRIDGE_PACKAGE_PREFIX
117                                                                 + "defaultViewId";
118    
119      // Following are the names of request attributes the Bridge must set before
120      // acquiring its first FacesContext/FacesContextFactory in each request
121      public static final String PORTLET_LIFECYCLE_PHASE       = BRIDGE_PACKAGE_PREFIX + "phase";
122    
123      public static final String PORTLET_ISNAMESPACED_PROPERTY = "X-JAVAX-PORTLET-IS-NAMESPACED";
124    
125      // The possible JSR168 portlet lifecycle phazses
126    
127      public static enum PortletPhase
128      {
129        ACTION_PHASE, RENDER_PHASE, ;
130      }
131    
132      public static enum BridgeRenderPolicy
133      {
134        DEFAULT, ALWAYS_DELEGATE, NEVER_DELEGATE, ;
135      }
136    
137      /**
138       * Called by the portlet. It indicates that the bridge is being placed into service.
139       * <p>
140       * The portlet calls the <code>init</code> method exactly once before invoking other lifecycle
141       * methods. Usually, done immediately after instantiating the bridge. The <code>init</code>
142       * method must complete successfully before the bridge can receive any requests.
143       * <p>
144       * The portlet cannot place the bridge into service if the <code>init</code> method Throws a
145       * <code>BridgeException</code>.
146       * <p>
147       * Initialization context is passed to bridge via <code>PortletContext</code> attributes. The
148       * following attributes are defined:
149       * <ul>
150       * <li><code>javax.portlet.faces.encodeRedirectURL</code>: instructs the bridge to call
151       * <code>ExternalContext.encodeActionURL()</code> before processing the redirect request. This
152       * exists because some (newer) versions of JSF 1.2 call <code>encodeActionURL</code> before
153       * calling <code>redirect</code> while others do not. This flag adjusts the behavior of the
154       * bridge in accordance with the JSF 1.2 implementation it runs with.
155       * <li><code>javax.portlet.faces.numManagedActionScopes</code>: defines the maximum number of
156       * actionScopes this bridge preserves at any given time. Value is an integer. ActionScopes are
157       * managed on a per Bridge class portlet context wide basis. As a typical portlet application uses
158       * the same bridge implementation for all its Faces based portlets, this means that all
159       * actionScopes are managed in a single bucket.<br>
160       * For convenience this interface defines the <code>NUM_MANAGED_ACTIONSCOPES</code> constant.
161       * <li><code>javax.faces.lifecycleID</code>: defines the Faces <code>Lifecycle</code> id
162       * that bridge uses when acquiring the <code>Faces.Lifecycle</code> via which it executes the
163       * request. As a context wide attribute, all bridge instances in this portlet application will use
164       * this lifecyle.
165       * <li><code>javax.portlet.faces.[portlet name].preserveActionParams</code>: instructs the
166       * bridge to preserve action parameters in the action scope and represent them in subsequent
167       * renders. Should be used only when binding to a Faces implementation that relies on accessing
168       * such parameters during its render phase. As this is a portlet/bridge instance specific
169       * attribute, the <code>PortletContext</code>attribute name is qualified by the portlet
170       * instance name. This allows different portlets within the same portlet application to have
171       * different settings.<br>
172       * For convenience this interfaces defines a number of constants that simplifies constructing
173       * and/or recognizing this name.
174       * </ul>
175       * 
176       * @param config
177       *          a <code>PortletConfig</code> object containing the portlet's configuration and
178       *          initialization parameters
179       * @exception PortletException
180       *              if an exception has occurred that interferes with the portlet's normal operation.
181       * @exception UnavailableException
182       *              if the portlet cannot perform the initialization at this time.
183       */
184      public void init(PortletConfig config) throws BridgeException;
185    
186      /**
187       * Called by the portlet when it wants the bridge to process an action request.
188       * 
189       * @param request
190       *          the request object.
191       * @param response
192       *          the response object.
193       * @throws BridgeDefaultViewNotSpecifiedException
194       *           thrown if the request indicates to the Bridge that is should use the default ViewId
195       *           and the portlet hasn't supplied one.
196       * @throws BridgeException
197       *           all other internal exceptions are converted to a BridgeException.
198       */
199      public void doFacesRequest(ActionRequest request, ActionResponse response)
200                                                                                throws BridgeDefaultViewNotSpecifiedException,
201                                                                                BridgeException;
202    
203      /**
204       * Called by the portlet when it wants the bridge to process a render request.
205       * 
206       * @param request
207       *          the request object.
208       * @param response
209       *          the response object.
210       * @throws BridgeDefaultViewNotSpecifiedException
211       *           thrown if the request indicates to the Bridge that is should use the default ViewId
212       *           and the portlet hasn't supplied one.
213       * @throws BridgeException
214       *           all other internal exceptions are converted to a BridgeException.
215       */
216      public void doFacesRequest(RenderRequest request, RenderResponse response)
217                                                                                throws BridgeDefaultViewNotSpecifiedException,
218                                                                                BridgeException;
219    
220      /**
221       * Called by the portlet to take the bridge out of service. Once out of service, the bridge must
222       * be reinitialized before processing any further requests.
223       */
224      public void destroy();
225    
226    }