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