Clover coverage report - Code Coverage for tapestry release 4.0-alpha-3
Coverage timestamp: Mon May 16 2005 09:05:49 EDT
file stats: LOC: 346   Methods: 0
NCLOC: 39   Classes: 1
30 day Evaluation Version distributed via the Maven Jar Repository. Clover is not free. You have 30 days to evaluate it. Please visit http://www.thecortex.net/clover to obtain a licensed version of Clover
 
 Source file Conditionals Statements Methods TOTAL
IRequestCycle.java - - - -
coverage
 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   
 }