| // Copyright 2004 The Apache Software Foundation |
| // |
| // Licensed under the Apache License, Version 2.0 (the "License"); |
| // you may not use this file except in compliance with the License. |
| // You may obtain a copy of the License at |
| // |
| // http://www.apache.org/licenses/LICENSE-2.0 |
| // |
| // Unless required by applicable law or agreed to in writing, software |
| // distributed under the License is distributed on an "AS IS" BASIS, |
| // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| // See the License for the specific language governing permissions and |
| // limitations under the License. |
| |
| package org.apache.tapestry; |
| |
| import org.apache.tapestry.engine.IEngineService; |
| import org.apache.tapestry.engine.IMonitor; |
| import org.apache.tapestry.request.RequestContext; |
| |
| /** |
| * Controller object that manages a single request cycle. A request cycle |
| * is one 'hit' on the web server. In the case of a Tapestry application, |
| * this will involve: |
| * <ul> |
| * <li>Responding to the URL by finding an {@link IEngineService} object |
| * <li>Determining the result page |
| * <li>Renderring the result page |
| * <li>Releasing any resources |
| * </ul> |
| * |
| * <p>Mixed in with this is: |
| * <ul> |
| * <li>Exception handling |
| * <li>Loading of pages and templates from resources |
| * <li>Tracking changes to page properties, and restoring pages to prior states |
| * <li>Pooling of page objects |
| * </ul> |
| * |
| * <p>A request cycle is broken up into two phases. The <em>rewind</em> phase |
| * is optional, as it tied to {@link org.apache.tapestry.link.ActionLink} or |
| * {@link org.apache.tapestry.form.Form} components. In the rewind phase, |
| * a previous page render is redone (discarding output) until a specific component |
| * of the page is reached. This rewinding ensures that the page |
| * is restored to the exact state it had when the URL for the request cycle was |
| * generated, taking into account the dynamic nature of the page ({@link org.apache.tapestry.components.Foreach}, |
| * {@link org.apache.tapestry.components.Conditional}, etc.). Once this component is reached, it can notify |
| * its {@link IActionListener}. The listener has the ability to update the state |
| * of any pages and select a new result page. |
| * |
| * <p>Following the rewind phase is the <em>render</em> phase. During the render phase, |
| * a page is actually rendered and output sent to the client web browser. |
| * |
| * |
| * @author Howard Lewis Ship |
| * @version $Id$ |
| * |
| **/ |
| |
| public interface IRequestCycle |
| { |
| /** |
| * Invoked after the request cycle is no longer needed, to release any resources |
| * it may have. This includes releasing any loaded pages back to the page source. |
| * |
| **/ |
| |
| public void cleanup(); |
| |
| /** |
| * Passes the String through |
| * {@link javax.servlet.http.HttpServletResponse#encodeURL(java.lang.String)}, which |
| * ensures that the session id is encoded in the URL (if necessary). |
| * |
| **/ |
| |
| public String encodeURL(String URL); |
| |
| /** |
| * Returns the engine which is processing this request cycle. |
| * |
| **/ |
| |
| public IEngine getEngine(); |
| |
| /** |
| * Retrieves a previously stored attribute, returning null |
| * if not found. Attributes allow components to locate each other; primarily |
| * they allow a wrapped component to locate a component which wraps it. |
| * |
| **/ |
| |
| public Object getAttribute(String name); |
| |
| public IMonitor getMonitor(); |
| |
| /** |
| * Returns the next action id. ActionLink ids are used to identify different actions on a |
| * page (URLs that are related to dynamic page state). |
| * |
| **/ |
| |
| public String getNextActionId(); |
| |
| /** |
| * Identifies the active page, the page which will ultimately render the response. |
| * |
| **/ |
| |
| public IPage getPage(); |
| |
| /** |
| * Returns the page with the given name. If the page has been |
| * previously loaded in the current request cycle, that page is |
| * returned. Otherwise, the engine's page loader is used to |
| * load the page. |
| * |
| * @see IEngine#getPageSource() |
| **/ |
| |
| public IPage getPage(String name); |
| |
| public RequestContext getRequestContext(); |
| |
| /** |
| * Returns true if the context is being used to rewind a prior |
| * state of the page. This is only true when there is a target |
| * action id. |
| * |
| **/ |
| |
| public boolean isRewinding(); |
| |
| /** |
| * Checks to see if the current action id matches the target |
| * action id. Returns true only if they match. Returns false if |
| * there is no target action id (that is, during page rendering). |
| * |
| * <p>If theres a match on action id, then the component |
| * is compared against the target component. If there's a mismatch |
| * then a {@link StaleLinkException} is thrown. |
| **/ |
| |
| public boolean isRewound(IComponent component) throws StaleLinkException; |
| |
| /** |
| * Removes a previously stored attribute, if one with the given name exists. |
| * |
| **/ |
| |
| public void removeAttribute(String name); |
| |
| /** |
| * Renders the given page. Applications should always use this |
| * method to render the page, rather than directly invoking |
| * {@link IPage#render(IMarkupWriter, IRequestCycle)} since the |
| * request cycle must perform some setup before rendering. |
| * |
| **/ |
| |
| public void renderPage(IMarkupWriter writer); |
| |
| /** |
| * Rewinds a page and executes some form of action when the |
| * component with the specified action id is reached. |
| * |
| * @see IAction |
| * |
| **/ |
| |
| public void rewindPage(String targetActionId, IComponent targetComponent); |
| |
| /** |
| * Allows a temporary object to be stored in the request cycle, |
| * which allows otherwise unrelated objects to communicate. This |
| * is similar to <code>HttpServletRequest.setAttribute()</code>, |
| * except that values can be changed and removed as well. |
| * |
| * <p>This is used by components to locate each other. A component, such |
| * as {@link org.apache.tapestry.html.Body}, will write itself under a well-known name |
| * into the request cycle, and components it wraps can locate it by that name. |
| **/ |
| |
| public void setAttribute(String name, Object value); |
| |
| /** |
| * Sets the page to be rendered. This is called by a component |
| * during the rewind phase to specify an alternate page to render |
| * during the response phase. |
| * |
| * @deprecated To be removed in 3.1. Use {@link #activate(IPage)}. |
| * |
| **/ |
| |
| public void setPage(IPage page); |
| |
| /** |
| * Sets the page to be rendered. This is called by a component |
| * during the rewind phase to specify an alternate page to render |
| * during the response phase. |
| * |
| * @deprecated To be removed in 3.1. Use {@link #activate(String)}. |
| * |
| **/ |
| |
| public void setPage(String name); |
| |
| /** |
| * Invoked just before rendering the response page to get all |
| * {@link org.apache.tapestry.engine.IPageRecorder page recorders} touched in this request cycle |
| * to commit their changes (save them to persistant storage). |
| * |
| * @see org.apache.tapestry.engine.IPageRecorder#commit() |
| **/ |
| |
| public void commitPageChanges(); |
| |
| /** |
| * Returns the service which initiated this request cycle. This may return |
| * null (very early during the request cycle) if the service has not |
| * yet been determined. |
| * |
| * @since 1.0.1 |
| **/ |
| |
| public IEngineService getService(); |
| |
| /** |
| * Used by {@link IForm forms} to perform a <em>partial</em> rewind |
| * so as to respond to the form submission (using the direct service). |
| * |
| * @since 1.0.2 |
| **/ |
| |
| public void rewindForm(IForm form, String targetActionId); |
| |
| /** |
| * Much like {@link IEngine#forgetPage(String)}, but the page stays active and can even |
| * record changes, until the end of the request cycle, at which point it is discarded |
| * (and any recorded changes are lost). |
| * This is used in certain rare cases where a page has persistent state but is |
| * being renderred "for the last time". |
| * |
| * @since 2.0.2 |
| * |
| **/ |
| |
| public void discardPage(String name); |
| |
| /** |
| * Invoked by a {@link IEngineService service} to store an array of application-specific parameters. |
| * These can later be retrieved (typically, by an application-specific listener method) |
| * by invoking {@link #getServiceParameters()}. |
| * |
| * <p>Through release 2.1, parameters was of type String[]. This is |
| * an incompatible change in 2.2. |
| * |
| * @see org.apache.tapestry.engine.DirectService |
| * @since 2.0.3 |
| * |
| **/ |
| |
| public void setServiceParameters(Object[] parameters); |
| |
| /** |
| * Returns parameters previously stored by {@link #setServiceParameters(Object[])}. |
| * |
| * <p> |
| * Through release 2.1, the return type was String[]. This is |
| * an incompatible change in 2.2. |
| * |
| * @since 2.0.3 |
| * |
| **/ |
| |
| public Object[] getServiceParameters(); |
| |
| /** |
| * A convienience for invoking {@link #activate(IPage)}. Invokes |
| * {@link #getPage(String)} to get an instance of the named page. |
| * |
| * @since 3.0 |
| * |
| **/ |
| |
| public void activate(String name); |
| |
| /** |
| * Sets the active page for the request. The active page is the page |
| * which will ultimately render the response. The activate page |
| * is typically set by the {@link IEngineService service}. Frequently, |
| * the active page is changed (from a listener method) to choose |
| * an alternate page to render the response). |
| * |
| * <p> |
| * {@link IPage#validate(IRequestCycle)} is invoked on the |
| * page to be activated. {@link PageRedirectException} is caught |
| * and the page specified in the exception will be the |
| * active page instead (that is, a page may "pass the baton" to another |
| * page using the exception). The new page is also validated. This |
| * continues until a page does not throw {@link PageRedirectException}. |
| * |
| * <p> |
| * Validation loops can occur, where page A redirects to page B and then page B |
| * redirects back to page A (possibly with intermediate steps). This is detected and results |
| * in an {@link ApplicationRuntimeException}. |
| * |
| * @since 3.0 |
| * |
| */ |
| public void activate(IPage page); |
| |
| } |