IRequestCycle


1   // Copyright 2004, 2005 The Apache Software Foundation
2   //
3   // Licensed under the Apache License, Version 2.0 (the "License");
4   // you may not use this file except in compliance with the License.
5   // You may obtain a copy of the License at
6   //
7   //     http://www.apache.org/licenses/LICENSE-2.0
8   //
9   // Unless required by applicable law or agreed to in writing, software
10  // distributed under the License is distributed on an "AS IS" BASIS,
11  // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12  // See the License for the specific language governing permissions and
13  // limitations under the License.
14  
15  package org.apache.tapestry;
16  
17  import org.apache.hivemind.ApplicationRuntimeException;
18  import org.apache.tapestry.engine.IEngineService;
19  import org.apache.tapestry.engine.IMonitor;
20  import org.apache.tapestry.request.RequestContext;
21  import org.apache.tapestry.services.Infrastructure;
22  
23  /**
24   * Controller object that manages a single request cycle. A request cycle is one 'hit' on the web
25   * server. In the case of a Tapestry application, this will involve:
26   * <ul>
27   * <li>Responding to the URL by finding an {@link IEngineService}object
28   * <li>Determining the result page
29   * <li>Renderring the result page
30   * <li>Releasing any resources
31   * </ul>
32   * <p>
33   * Mixed in with this is:
34   * <ul>
35   * <li>Exception handling
36   * <li>Loading of pages and templates from resources
37   * <li>Tracking changes to page properties, and restoring pages to prior states
38   * <li>Pooling of page objects
39   * </ul>
40   * <p>
41   * A request cycle is broken up into two phases. The <em>rewind</em> phase is optional, as it tied
42   * to {@link org.apache.tapestry.link.ActionLink}or {@link org.apache.tapestry.form.Form}
43   * components. In the rewind phase, a previous page render is redone (discarding output) until a
44   * specific component of the page is reached. This rewinding ensures that the page is restored to
45   * the exact state it had when the URL for the request cycle was generated, taking into account the
46   * dynamic nature of the page ({@link org.apache.tapestry.components.Foreach},
47   * {@link org.apache.tapestry.components.Conditional}, etc.). Once this component is reached, it
48   * can notify its {@link IActionListener}. The listener has the ability to update the state of any
49   * pages and select a new result page.
50   * <p>
51   * Following the rewind phase is the <em>render</em> phase. During the render phase, a page is
52   * actually rendered and output sent to the client web browser.
53   * 
54   * @author Howard Lewis Ship
55   */
56  
57  public interface IRequestCycle
58  {
59      /**
60       * Invoked after the request cycle is no longer needed, to release any resources it may have.
61       * This includes releasing any loaded pages back to the page source.
62       */
63  
64      public void cleanup();
65  
66      /**
67       * Passes the String through
68       * {@link javax.servlet.http.HttpServletResponse#encodeURL(java.lang.String)}, which ensures
69       * that the session id is encoded in the URL (if necessary).
70       */
71  
72      public String   encodeURL(String   URL);
73  
74      /**
75       * Returns the engine which is processing this request cycle.
76       */
77  
78      public IEngine getEngine();
79  
80      /**
81       * Retrieves a previously stored attribute, returning null if not found. Attributes allow
82       * components to locate each other; primarily they allow a wrapped component to locate a
83       * component which wraps it. Attributes are cleared at the end of the render (or rewind).
84       */
85  
86      public Object   getAttribute(String   name);
87  
88      public IMonitor getMonitor();
89  
90      /**
91       * Returns the next action id. ActionLink ids are used to identify different actions on a page
92       * (URLs that are related to dynamic page state).
93       */
94  
95      public String   getNextActionId();
96  
97      /**
98       * Identifies the active page, the page which will ultimately render the response.
99       */
100 
101     public IPage getPage();
102 
103     /**
104      * Returns the page with the given name. If the page has been previously loaded in the current
105      * request cycle, that page is returned. Otherwise, the engine's page loader is used to load the
106      * page.
107      * 
108      * @throws PageNotFoundException
109      *             if the page does not exist.
110      * @see org.apache.tapestry.engine.IPageSource#getPage(IRequestCycle, String, IMonitor)
111      */
112 
113     public IPage getPage(String   name);
114 
115     /**
116      * Returns true if the context is being used to rewind a prior state of the page. This is only
117      * true when there is a target action id.
118      */
119 
120     public boolean isRewinding();
121 
122     /**
123      * Checks to see if the current action id matches the target action id. Returns true only if
124      * they match. Returns false if there is no target action id (that is, during page rendering).
125      * <p>
126      * If theres a match on action id, then the component is compared against the target component.
127      * If there's a mismatch then a {@link StaleLinkException}is thrown.
128      */
129 
130     public boolean isRewound(IComponent component) throws StaleLinkException;
131 
132     /**
133      * Removes a previously stored attribute, if one with the given name exists.
134      */
135 
136     public void removeAttribute(String   name);
137 
138     /**
139      * Renders the given page. Applications should always use this method to render the page, rather
140      * than directly invoking {@link IPage#render(IMarkupWriter, IRequestCycle)}since the request
141      * cycle must perform some setup before rendering.
142      */
143 
144     public void renderPage(IMarkupWriter writer);
145 
146     /**
147      * Rewinds a page and executes some form of action when the component with the specified action
148      * id is reached.
149      * 
150      * @see IAction
151      * @see org.apache.tapestry.link.ActionLink
152      */
153 
154     public void rewindPage(String   targetActionId, IComponent targetComponent);
155 
156     /**
157      * Allows a temporary object to be stored in the request cycle, which allows otherwise unrelated
158      * objects to communicate. This is similar to <code>HttpServletRequest.setAttribute()</code>,
159      * except that values can be changed and removed as well.
160      * <p>
161      * This is used by components to locate each other. A component, such as
162      * {@link org.apache.tapestry.html.Body}, will write itself under a well-known name into the
163      * request cycle, and components it wraps can locate it by that name.
164      * <p>
165      * Attributes are cleared at the end of each render or rewind phase.
166      */
167 
168     public void setAttribute(String   name, Object   value);
169 
170     /**
171      * Invoked just before rendering the response page to get all
172      * {@link org.apache.tapestry.engine.IPageRecorder page recorders}touched in this request cycle
173      * to commit their changes (save them to persistant storage).
174      * 
175      * @see org.apache.tapestry.engine.IPageRecorder#commit()
176      */
177 
178     public void commitPageChanges();
179 
180     /**
181      * Returns the service which initiated this request cycle.
182      * 
183      * @since 1.0.1
184      */
185 
186     public IEngineService getService();
187 
188     /**
189      * Used by {@link IForm forms}to perform a <em>partial</em> rewind so as to respond to the
190      * form submission (using the direct service).
191      * <p>
192      * Note: the targetActionId parameter was removed in release 4.0.
193      * 
194      * @since 1.0.2
195      */
196 
197     public void rewindForm(IForm form);
198 
199     /**
200      * Much like {@link #forgetPage(String)}, but the page stays active and can even record
201      * changes, until the end of the request cycle, at which point it is discarded (and any recorded
202      * changes are lost). This is used in certain rare cases where a page has persistent state but
203      * is being renderred "for the last time".
204      * 
205      * @since 2.0.2
206      * @deprecated To be removed in 4.1. Use {@link #forgetPage(String)}.
207      */
208 
209     public void discardPage(String   name);
210 
211     /**
212      * Invoked by a {@link IEngineService service}&nbsp;to store an array of application-specific
213      * parameters. These can later be retrieved (typically, by an application-specific listener
214      * method) by invoking {@link #getServiceParameters()}.
215      * <p>
216      * Through release 2.1, parameters was of type String[]. This is an incompatible change in 2.2.
217      * 
218      * @see org.apache.tapestry.engine.DirectService
219      * @since 2.0.3
220      * @deprecated To be removed in 4.1. Use {@link #setListenerParameters(Object[])}instead.
221      */
222 
223     public void setServiceParameters(Object  [] parameters);
224 
225     /**
226      * Invoked by a {@link IEngineService service}&nbsp;to store an array of application-specific
227      * parameters. These can later be retrieved (typically, by an application-specific listener
228      * method) by invoking {@link #getListenerParameters()}.
229      * 
230      * @see org.apache.tapestry.engine.DirectService
231      * @since 4.0
232      */
233     public void setListenerParameters(Object  [] parameters);
234 
235     /**
236      * Returns parameters previously stored by {@link #setServiceParameters(Object[])}.
237      * <p>
238      * Through release 2.1, the return type was String[]. This is an incompatible change in 2.2.
239      * 
240      * @since 2.0.3
241      * @deprecated To be removed in 4.1. Use {@link #getListenerParameters()}instead.
242      */
243 
244     public Object  [] getServiceParameters();
245 
246     /**
247      * Returns parameters previously stored by {@link #setListenerParameters(Object[])}.
248      * 
249      * @since 4.0
250      */
251 
252     public Object  [] getListenerParameters();
253 
254     /**
255      * A convienience for invoking {@link #activate(IPage)}. Invokes {@link #getPage(String)}to
256      * get an instance of the named page.
257      * 
258      * @since 3.0
259      */
260 
261     public void activate(String   name);
262 
263     /**
264      * Sets the active page for the request. The active page is the page which will ultimately
265      * render the response. The activate page is typically set by the {@link IEngineService service}.
266      * Frequently, the active page is changed (from a listener method) to choose an alternate page
267      * to render the response).
268      * <p>
269      * {@link IPage#validate(IRequestCycle)}is invoked on the page to be activated.
270      * {@link PageRedirectException}is caught and the page specified in the exception will be the
271      * active page instead (that is, a page may "pass the baton" to another page using the
272      * exception). The new page is also validated. This continues until a page does not throw
273      * {@link PageRedirectException}.
274      * <p>
275      * Validation loops can occur, where page A redirects to page B and then page B redirects back
276      * to page A (possibly with intermediate steps). This is detected and results in an
277      * {@link ApplicationRuntimeException}.
278      * 
279      * @since 3.0
280      */
281     public void activate(IPage page);
282 
283     /**
284      * Returns a query parameter value, or null if not provided in the request. If multiple values
285      * are provided, returns the first value.
286      * 
287      * @since 4.0
288      */
289     public String   getParameter(String   name);
290 
291     /**
292      * Returns all query parameter values for the given name. Returns null if no values were
293      * provided.
294      * 
295      * @since 4.0
296      */
297     public String  [] getParameters(String   name);
298 
299     /**
300      * Converts a partial URL into an absolute URL. Prefixes the provided URL with servlet context
301      * path (if any), then expands it to a full URL by prepending with the scheme, server and port
302      * (determined from the current {@link org.apache.tapestry.web.WebRequest request}.
303      * 
304      * @since 4.0
305      */
306 
307     public String   getAbsoluteURL(String   partialURL);
308 
309     /**
310      * Forgets any stored changes to the specified page. If the page has already been loaded (and
311      * rolled back) then the loaded page instance is not affected; if the page is only loaded
312      * subsequently, the page instance will not see any persisted property changes.
313      * 
314      * @since 4.0
315      */
316 
317     public void forgetPage(String   name);
318 
319     /**
320      * Returns the central {@link org.apache.tapestry.services.Infrastructure}&nbsp;object used to
321      * manage the processing of the request.
322      * 
323      * @since 4.0
324      */
325 
326     public Infrastructure getInfrastructure();
327 
328     /**
329      * Returns the {@link RequestContext}. This is provided to ease the upgrade from Tapestry 3.0.
330      * 
331      * @deprecated To be removed in 4.1.
332      */
333 
334     public RequestContext getRequestContext();
335 
336     /**
337      * Returns the provided string, possibly modified (with an appended suffix) to make it unique.
338      * 
339      * @param baseId
340      *            the base id from which to generate the unique string.
341      * @return baseId, or baseId with a suffix appended (if the method has been previously invoked
342      *         with the same baseId).
343      */
344 
345     public String   getUniqueId(String   baseId);
346 }
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags