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 }