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: 287   Methods: 0
NCLOC: 44   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.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   
 }