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