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 }