Clover coverage report - Code Coverage for tapestry release 3.1-alpha-1
Coverage timestamp: Mon Feb 21 2005 09:16:14 EST
file stats: LOC: 285   Methods: 0
NCLOC: 43   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
IPage.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 java.io.OutputStream;
 18   
 import java.util.Locale;
 19   
 
 20   
 import org.apache.tapestry.event.ChangeObserver;
 21   
 import org.apache.tapestry.event.PageBeginRenderListener;
 22   
 import org.apache.tapestry.event.PageDetachListener;
 23   
 import org.apache.tapestry.event.PageEndRenderListener;
 24   
 import org.apache.tapestry.event.PageAttachListener;
 25   
 import org.apache.tapestry.event.PageRenderListener;
 26   
 import org.apache.tapestry.event.PageValidateListener;
 27   
 
 28   
 /**
 29   
  * A root level component responsible for generating an entire a page within the application.
 30   
  * <p>
 31   
  * Pages are created dynamically from thier class names (part of the
 32   
  * {@link org.apache.tapestry.spec.IComponentSpecification}).
 33   
  * 
 34   
  * @see org.apache.tapestry.engine.IPageSource
 35   
  * @see org.apache.tapestry.engine.IPageLoader
 36   
  * @author Howard Lewis Ship
 37   
  */
 38   
 
 39   
 public interface IPage extends IComponent
 40   
 {
 41   
     /**
 42   
      * Invoked on a page when it is no longer needed by the engine, just before is is returned to
 43   
      * the pool. The page is expected to null the engine, visit and changeObserver properties.
 44   
      * <p>
 45   
      * Classes should also reset any properties to default values (as if the instance was freshly
 46   
      * instantiated).
 47   
      * 
 48   
      * @see org.apache.tapestry.engine.IPageSource#releasePage(IPage)
 49   
      */
 50   
 
 51   
     public void detach();
 52   
 
 53   
     /**
 54   
      * Returns the {@link IEngine}that the page is currently attached to.
 55   
      */
 56   
 
 57   
     public IEngine getEngine();
 58   
 
 59   
     /**
 60   
      * Returns the object (effectively, an {@link org.apache.tapestry.engine.IPageRecorder}) that
 61   
      * is notified of any changes to persistant properties of the page.
 62   
      */
 63   
 
 64   
     public ChangeObserver getChangeObserver();
 65   
 
 66   
     /**
 67   
      * Returns the <code>Locale</code> of the page. The locale may be used to determine what
 68   
      * template is used by the page and the components contained by the page.
 69   
      */
 70   
 
 71   
     public Locale getLocale();
 72   
 
 73   
     /**
 74   
      * Updates the page's locale. This is write-once, a subsequent attempt will throw an
 75   
      * {@link ApplicationRuntimeException}.
 76   
      */
 77   
 
 78   
     public void setLocale(Locale value);
 79   
 
 80   
     /**
 81   
      * Returns the fully qualified name of the page, including its namespace prefix, if any.
 82   
      * 
 83   
      * @since 2.3
 84   
      */
 85   
 
 86   
     public String getPageName();
 87   
 
 88   
     /**
 89   
      * Sets the name of the page.
 90   
      * 
 91   
      * @param pageName
 92   
      *            fully qualified page name (including namespace prefix, if any)
 93   
      * @since 3.0
 94   
      */
 95   
 
 96   
     public void setPageName(String pageName);
 97   
 
 98   
     /**
 99   
      * Returns a particular component from within the page. The path is a dotted name sequence
 100   
      * identifying the component. It may be null in which case the page returns itself.
 101   
      * 
 102   
      * @exception ApplicationRuntimeException
 103   
      *                runtime exception thrown if the path does not identify a component.
 104   
      */
 105   
 
 106   
     public IComponent getNestedComponent(String path);
 107   
 
 108   
     /**
 109   
      * Attaches the page to the {@link IEngine engine}. This method is used when a pooled page is
 110   
      * claimed for use with a particular engine; it will stay attached to the engine until the end
 111   
      * of the current request cycle, then be returned to the pool.
 112   
      * <p>
 113   
      * This method will notify any {@link PageAttachListener}s.
 114   
      * <p>
 115   
      * This method is rarely overriden; to initialize page properties before a render, override
 116   
      * {@link #beginResponse(IMarkupWriter, IRequestCycle)}.
 117   
      */
 118   
 
 119   
     public void attach(IEngine engine, IRequestCycle cycle);
 120   
 
 121   
     /**
 122   
      * Invoked to render the entire page. This should only be invoked by
 123   
      * {@link IRequestCycle#renderPage(IMarkupWriter writer)}.
 124   
      * <p>
 125   
      * The page performs a render using the following steps:
 126   
      * <ul>
 127   
      * <li>Invokes {@link PageRenderListener#pageBeginRender(org.apache.tapestry.event.PageEvent)}
 128   
      * <li>Invokes {@link #beginResponse(IMarkupWriter, IRequestCycle)}
 129   
      * <li>Invokes {@link IRequestCycle#commitPageChanges()}(if not rewinding)
 130   
      * <li>Invokes {@link #render(IMarkupWriter, IRequestCycle)}
 131   
      * <li>Invokes {@link PageRenderListener#pageEndRender(org.apache.tapestry.event.PageEvent)}
 132   
      * (this occurs even if a previous step throws an exception).
 133   
      * </ul>
 134   
      */
 135   
 
 136   
     public void renderPage(IMarkupWriter writer, IRequestCycle cycle);
 137   
 
 138   
     /**
 139   
      * Invoked before a partial render of the page occurs (this happens when rewinding a
 140   
      * {@link org.apache.tapestry.form.Form}within the page). The page is expected to fire
 141   
      * appopriate events.
 142   
      * 
 143   
      * @since 2.2
 144   
      */
 145   
 
 146   
     public void beginPageRender();
 147   
 
 148   
     /**
 149   
      * Invoked after a partial render of the page occurs (this happens when rewinding a
 150   
      * {@link org.apache.tapestry.form.Form}within the page). The page is expected to fire
 151   
      * appropriate events.
 152   
      * 
 153   
      * @since 2.2
 154   
      */
 155   
 
 156   
     public void endPageRender();
 157   
 
 158   
     public void setChangeObserver(ChangeObserver value);
 159   
 
 160   
     /**
 161   
      * Method invoked by the page, action and direct services to validate that the user is allowed
 162   
      * to visit the page.
 163   
      * <p>
 164   
      * Most web applications have a concept of 'logging in' and pages that an anonymous (not logged
 165   
      * in) user should not be able to visit directly. This method acts as the first line of defense
 166   
      * against a malicous user hacking URLs.
 167   
      * <p>
 168   
      * Pages that should be protected will typically throw a {@linkPageRedirectException}, to
 169   
      * redirect the user to an appropriate part of the system (such as, a login page).
 170   
      * <p>
 171   
      * Since 3.0, it is easiest to not override this method, but to implement the
 172   
      * {@link PageValidateListener}interface instead.
 173   
      */
 174   
 
 175   
     public void validate(IRequestCycle cycle);
 176   
 
 177   
     /**
 178   
      * Invoked to create a response writer appropriate to the page (i.e., appropriate to the content
 179   
      * of the page).
 180   
      */
 181   
 
 182   
     public IMarkupWriter getResponseWriter(OutputStream out);
 183   
 
 184   
     /**
 185   
      * Invoked just before rendering of the page is initiated. This gives the page a chance to
 186   
      * perform any additional setup. One possible behavior is to set HTTP headers and cookies before
 187   
      * any output is generated.
 188   
      * <p>
 189   
      * The timing of this explicitly <em>before</em>
 190   
      * {@link org.apache.tapestry.engine.IPageRecorder page recorder}changes are committed.
 191   
      * Rendering occurs <em>after</em> the recorders are committed, when it is too late to make
 192   
      * changes to dynamic page properties.
 193   
      */
 194   
 
 195   
     public void beginResponse(IMarkupWriter writer, IRequestCycle cycle);
 196   
 
 197   
     /**
 198   
      * Returns the current {@link IRequestCycle}. This is set when the page is loaded (or obtained
 199   
      * from the pool) and attached to the {@link IEngine engine}.
 200   
      */
 201   
 
 202   
     public IRequestCycle getRequestCycle();
 203   
 
 204   
     /**
 205   
      * Returns the visit object for the application; the visit object contains application-specific
 206   
      * information.
 207   
      */
 208   
 
 209   
     public Object getVisit();
 210   
 
 211   
     /**
 212   
      * Returns the globally shared application object. The global object is stored in the servlet
 213   
      * context.
 214   
      * <p>
 215   
      * Returns the global object, if it exists, or null if not defined.
 216   
      * 
 217   
      * @since 2.3
 218   
      */
 219   
 
 220   
     public Object getGlobal();
 221   
 
 222   
     /**
 223   
      * @since 1.0.5
 224   
      * @deprecated To be removed in 3.2 Use
 225   
      *             {@link #addPageBeginRenderListener(PageBeginRenderListener)}or
 226   
      *             {@link #addPageEndRenderListener(PageEndRenderListener)}.
 227   
      */
 228   
 
 229   
     public void addPageRenderListener(PageRenderListener listener);
 230   
 
 231   
     /**
 232   
      * @since 2.1
 233   
      * @deprecated To be removed in 3.2. Use
 234   
      *             {@link #removePageBeginRenderListener(PageBeginRenderListener)}or
 235   
      *             {@link #removePageEndRenderListener(PageEndRenderListener)}.
 236   
      */
 237   
 
 238   
     public void removePageRenderListener(PageRenderListener listener);
 239   
 
 240   
     /** @since 3.1 */
 241   
     public void addPageBeginRenderListener(PageBeginRenderListener listener);
 242   
 
 243   
     /** @since 3.1 */
 244   
     public void removePageBeginRenderListener(PageBeginRenderListener listener);
 245   
 
 246   
     /** @since 3.1 */
 247   
 
 248   
     public void addPageEndRenderListener(PageEndRenderListener listener);
 249   
 
 250   
     /** @since 3.1 */
 251   
 
 252   
     public void removePageEndRenderListener(PageEndRenderListener listener);
 253   
 
 254   
     /**
 255   
      * @since 1.0.5
 256   
      */
 257   
 
 258   
     public void addPageDetachListener(PageDetachListener listener);
 259   
 
 260   
     /**
 261   
      * @since 2.1
 262   
      */
 263   
 
 264   
     public void removePageDetachListener(PageDetachListener listener);
 265   
 
 266   
     /**
 267   
      * @since 3.0
 268   
      */
 269   
 
 270   
     public void addPageValidateListener(PageValidateListener listener);
 271   
 
 272   
     /**
 273   
      * @since 3.0
 274   
      */
 275   
 
 276   
     public void removePageValidateListener(PageValidateListener listener);
 277   
 
 278   
     /** @since 3.1 */
 279   
 
 280   
     public void addPageAttachListener(PageAttachListener listener);
 281   
 
 282   
     /** @since 3.1 */
 283   
 
 284   
     public void removePageAttachListener(PageAttachListener listener);
 285   
 }