Clover coverage report - Code Coverage for tapestry release 4.0-beta-10
Coverage timestamp: Sat Oct 8 2005 19:08:05 EDT
file stats: LOC: 291   Methods: 0
NCLOC: 43   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.tapestry.event.ChangeObserver;
 20    import org.apache.tapestry.event.PageAttachListener;
 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.PageRenderListener;
 25    import org.apache.tapestry.event.PageValidateListener;
 26    import org.apache.tapestry.util.ContentType;
 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, implement the
 116    * {@link PageBeginRenderListener}interface.
 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
 128    * {@link PageBeginRenderListener#pageBeginRender(org.apache.tapestry.event.PageEvent)}
 129    * <li>Invokes {@link #beginResponse(IMarkupWriter, IRequestCycle)}
 130    * <li>Invokes {@link IRequestCycle#commitPageChanges()}(if not rewinding)
 131    * <li>Invokes {@link #render(IMarkupWriter, IRequestCycle)}
 132    * <li>Invokes {@link PageEndRenderListener#pageEndRender(org.apache.tapestry.event.PageEvent)}
 133    * (this occurs even if a previous step throws an exception).
 134    * </ul>
 135    */
 136   
 137    public void renderPage(IMarkupWriter writer, IRequestCycle cycle);
 138   
 139    /**
 140    * Invoked before a partial render of the page occurs (this happens when rewinding a
 141    * {@link org.apache.tapestry.form.Form}within the page). The page is expected to fire
 142    * appopriate events.
 143    *
 144    * @since 2.2
 145    */
 146   
 147    public void beginPageRender();
 148   
 149    /**
 150    * Invoked after a partial render of the page occurs (this happens when rewinding a
 151    * {@link org.apache.tapestry.form.Form}within the page). The page is expected to fire
 152    * appropriate events.
 153    *
 154    * @since 2.2
 155    */
 156   
 157    public void endPageRender();
 158   
 159    public void setChangeObserver(ChangeObserver value);
 160   
 161    /**
 162    * Method invoked by the page, action and direct services to validate that the user is allowed
 163    * to visit the page.
 164    * <p>
 165    * Most web applications have a concept of 'logging in' and pages that an anonymous (not logged
 166    * in) user should not be able to visit directly. This method acts as the first line of defense
 167    * against a malicous user hacking URLs.
 168    * <p>
 169    * Pages that should be protected will typically throw a {@linkPageRedirectException}, to
 170    * redirect the user to an appropriate part of the system (such as, a login page).
 171    * <p>
 172    * Since 3.0, it is easiest to not override this method, but to implement the
 173    * {@link PageValidateListener}interface instead.
 174    */
 175   
 176    public void validate(IRequestCycle cycle);
 177   
 178    /**
 179    * Invoked to obtain the content type to be used for the response. The implementation of this
 180    * method is the primary difference between an HTML page and an XML/WML/etc. page.
 181    */
 182   
 183    public ContentType getResponseContentType();
 184   
 185    /**
 186    * Invoked just before rendering of the page is initiated. This gives the page a chance to
 187    * perform any additional setup. One possible behavior is to set HTTP headers and cookies before
 188    * any output is generated.
 189    * <p>
 190    * The timing of this explicitly <em>before</em>
 191    * {@link org.apache.tapestry.engine.IPageRecorder page recorder}changes are committed.
 192    * Rendering occurs <em>after</em> the recorders are committed, when it is too late to make
 193    * changes to dynamic page properties.
 194    */
 195   
 196    public void beginResponse(IMarkupWriter writer, IRequestCycle cycle);
 197   
 198    /**
 199    * Returns the current {@link IRequestCycle}. This is set when the page is loaded (or obtained
 200    * from the pool) and attached to the {@link IEngine engine}.
 201    */
 202   
 203    public IRequestCycle getRequestCycle();
 204   
 205    /**
 206    * Returns the visit object for the application; the visit object contains application-specific
 207    * information.
 208    *
 209    * @deprecated To be removed in 4.1. Inject an application state object instead. <strong>Do not
 210    * attempt to inject property visit</strong>.
 211    */
 212   
 213    public Object getVisit();
 214   
 215    /**
 216    * Returns the globally shared application object. The global object is stored in the servlet
 217    * context.
 218    * <p>
 219    * Returns the global object, if it exists, or null if not defined.
 220    *
 221    * @since 2.3
 222    * @deprecated To be removed in 4.1. Inject an application state object instead. <strong>Do not
 223    * attempt to inject property global.</strong>
 224    */
 225   
 226    public Object getGlobal();
 227   
 228    /**
 229    * @since 1.0.5
 230    * @deprecated To be removed in 4.1 Use
 231    * {@link #addPageBeginRenderListener(PageBeginRenderListener)}or
 232    * {@link #addPageEndRenderListener(PageEndRenderListener)}.
 233    */
 234   
 235    public void addPageRenderListener(PageRenderListener listener);
 236   
 237    /**
 238    * @since 2.1
 239    * @deprecated To be removed in 4.1. Use
 240    * {@link #removePageBeginRenderListener(PageBeginRenderListener)}or
 241    * {@link #removePageEndRenderListener(PageEndRenderListener)}.
 242    */
 243   
 244    public void removePageRenderListener(PageRenderListener listener);
 245   
 246    /** @since 4.0 */
 247    public void addPageBeginRenderListener(PageBeginRenderListener listener);
 248   
 249    /** @since 4.0 */
 250    public void removePageBeginRenderListener(PageBeginRenderListener listener);
 251   
 252    /** @since 4.0 */
 253   
 254    public void addPageEndRenderListener(PageEndRenderListener listener);
 255   
 256    /** @since 4.0 */
 257   
 258    public void removePageEndRenderListener(PageEndRenderListener listener);
 259   
 260    /**
 261    * @since 1.0.5
 262    */
 263   
 264    public void addPageDetachListener(PageDetachListener listener);
 265   
 266    /**
 267    * @since 2.1
 268    */
 269   
 270    public void removePageDetachListener(PageDetachListener listener);
 271   
 272    /**
 273    * @since 3.0
 274    */
 275   
 276    public void addPageValidateListener(PageValidateListener listener);
 277   
 278    /**
 279    * @since 3.0
 280    */
 281   
 282    public void removePageValidateListener(PageValidateListener listener);
 283   
 284    /** @since 4.0 */
 285   
 286    public void addPageAttachListener(PageAttachListener listener);
 287   
 288    /** @since 4.0 */
 289   
 290    public void removePageAttachListener(PageAttachListener listener);
 291    }