| // Copyright 2004, 2005 The Apache Software Foundation |
| // |
| // Licensed under the Apache License, Version 2.0 (the "License"); |
| // you may not use this file except in compliance with the License. |
| // You may obtain a copy of the License at |
| // |
| // http://www.apache.org/licenses/LICENSE-2.0 |
| // |
| // Unless required by applicable law or agreed to in writing, software |
| // distributed under the License is distributed on an "AS IS" BASIS, |
| // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| // See the License for the specific language governing permissions and |
| // limitations under the License. |
| |
| package org.apache.tapestry; |
| |
| import java.util.Locale; |
| |
| import org.apache.hivemind.ApplicationRuntimeException; |
| import org.apache.tapestry.event.ChangeObserver; |
| import org.apache.tapestry.event.PageAttachListener; |
| import org.apache.tapestry.event.PageBeginRenderListener; |
| import org.apache.tapestry.event.PageDetachListener; |
| import org.apache.tapestry.event.PageEndRenderListener; |
| import org.apache.tapestry.event.PageRenderListener; |
| import org.apache.tapestry.event.PageValidateListener; |
| import org.apache.tapestry.util.ContentType; |
| |
| /** |
| * A root level component responsible for generating an entire a page within the application. |
| * <p> |
| * Pages are created dynamically from their class names (part of the |
| * {@link org.apache.tapestry.spec.IComponentSpecification}). |
| * |
| * @see org.apache.tapestry.engine.IPageSource |
| * @see org.apache.tapestry.engine.IPageLoader |
| * @author Howard Lewis Ship |
| */ |
| |
| public interface IPage extends IComponent |
| { |
| /** |
| * Invoked on a page when it is no longer needed by the engine, just before is is returned to |
| * the pool. The page is expected to null the engine, visit and changeObserver properties. |
| * <p> |
| * Classes should also reset any properties to default values (as if the instance was freshly |
| * instantiated). |
| * |
| * @see org.apache.tapestry.engine.IPageSource#releasePage(IPage) |
| */ |
| |
| public void detach(); |
| |
| /** |
| * Returns the {@link IEngine}that the page is currently attached to. |
| */ |
| |
| public IEngine getEngine(); |
| |
| /** |
| * Returns the object (effectively, an {@link org.apache.tapestry.engine.IPageRecorder}) that |
| * is notified of any changes to persistant properties of the page. |
| */ |
| |
| public ChangeObserver getChangeObserver(); |
| |
| /** |
| * Returns the <code>Locale</code> of the page. The locale may be used to determine what |
| * template is used by the page and the components contained by the page. |
| */ |
| |
| public Locale getLocale(); |
| |
| /** |
| * Updates the page's locale. This is write-once, a subsequent attempt will throw an |
| * {@link ApplicationRuntimeException}. |
| */ |
| |
| public void setLocale(Locale value); |
| |
| /** |
| * Returns the fully qualified name of the page, including its namespace prefix, if any. |
| * |
| * @since 2.3 |
| */ |
| |
| public String getPageName(); |
| |
| /** |
| * Sets the name of the page. |
| * |
| * @param pageName |
| * fully qualified page name (including namespace prefix, if any) |
| * @since 3.0 |
| */ |
| |
| public void setPageName(String pageName); |
| |
| /** |
| * Returns a particular component from within the page. The path is a dotted name sequence |
| * identifying the component. It may be null in which case the page returns itself. |
| * |
| * @exception ApplicationRuntimeException |
| * runtime exception thrown if the path does not identify a component. |
| */ |
| |
| public IComponent getNestedComponent(String path); |
| |
| /** |
| * Attaches the page to the {@link IEngine engine}. This method is used when a pooled page is |
| * claimed for use with a particular engine; it will stay attached to the engine until the end |
| * of the current request cycle, then be returned to the pool. |
| * <p> |
| * This method will notify any {@link PageAttachListener}s. |
| * <p> |
| * This method is rarely overriden; to initialize page properties before a render, implement the |
| * {@link PageBeginRenderListener}interface. |
| */ |
| |
| public void attach(IEngine engine, IRequestCycle cycle); |
| |
| /** |
| * Used to explicitly fire {@link PageAttachListener}s for this page. This is used when a page |
| * is first loaded; The page loader attaches the newly created page <em>instance</em> before |
| * the rest of the page and components is loaded. In order to have meaningful event |
| * notifications when a page is first loaded (rather than pulled from the pool), it is necessary |
| * to fire page attach listeners at the end of the load. |
| * |
| * @since 4.0 |
| */ |
| |
| public void firePageAttached(); |
| |
| /** |
| * Invoked to render the entire page. This should only be invoked by |
| * {@link IRequestCycle#renderPage(IMarkupWriter writer)}. |
| * <p> |
| * The page performs a render using the following steps: |
| * <ul> |
| * <li>Invokes |
| * {@link PageBeginRenderListener#pageBeginRender(org.apache.tapestry.event.PageEvent)} |
| * <li>Invokes {@link #beginResponse(IMarkupWriter, IRequestCycle)} |
| * <li>Invokes {@link IRequestCycle#commitPageChanges()}(if not rewinding) |
| * <li>Invokes {@link #render(IMarkupWriter, IRequestCycle)} |
| * <li>Invokes {@link PageEndRenderListener#pageEndRender(org.apache.tapestry.event.PageEvent)} |
| * (this occurs even if a previous step throws an exception). |
| * </ul> |
| */ |
| |
| public void renderPage(IMarkupWriter writer, IRequestCycle cycle); |
| |
| /** |
| * Invoked before a partial render of the page occurs (this happens when rewinding a |
| * {@link org.apache.tapestry.form.Form}within the page). The page is expected to fire |
| * appopriate events. |
| * |
| * @since 2.2 |
| */ |
| |
| public void beginPageRender(); |
| |
| /** |
| * Invoked after a partial render of the page occurs (this happens when rewinding a |
| * {@link org.apache.tapestry.form.Form}within the page). The page is expected to fire |
| * appropriate events. |
| * |
| * @since 2.2 |
| */ |
| |
| public void endPageRender(); |
| |
| public void setChangeObserver(ChangeObserver value); |
| |
| /** |
| * Method invoked by the page, action and direct services to validate that the user is allowed |
| * to visit the page. |
| * <p> |
| * Most web applications have a concept of 'logging in' and pages that an anonymous (not logged |
| * in) user should not be able to visit directly. This method acts as the first line of defense |
| * against a malicous user hacking URLs. |
| * <p> |
| * Pages that should be protected will typically throw a {@linkPageRedirectException}, to |
| * redirect the user to an appropriate part of the system (such as, a login page). |
| * <p> |
| * Since 3.0, it is easiest to not override this method, but to implement the |
| * {@link PageValidateListener}interface instead. |
| */ |
| |
| public void validate(IRequestCycle cycle); |
| |
| /** |
| * Invoked to obtain the content type to be used for the response. The implementation of this |
| * method is the primary difference between an HTML page and an XML/WML/etc. page. |
| */ |
| |
| public ContentType getResponseContentType(); |
| |
| /** |
| * Invoked just before rendering of the page is initiated. This gives the page a chance to |
| * perform any additional setup. One possible behavior is to set HTTP headers and cookies before |
| * any output is generated. |
| * <p> |
| * The timing of this explicitly <em>before</em> |
| * {@link org.apache.tapestry.engine.IPageRecorder page recorder}changes are committed. |
| * Rendering occurs <em>after</em> the recorders are committed, when it is too late to make |
| * changes to dynamic page properties. |
| */ |
| |
| public void beginResponse(IMarkupWriter writer, IRequestCycle cycle); |
| |
| /** |
| * Returns the current {@link IRequestCycle}. This is set when the page is loaded (or obtained |
| * from the pool) and attached to the {@link IEngine engine}. |
| */ |
| |
| public IRequestCycle getRequestCycle(); |
| |
| /** |
| * Returns the visit object for the application; the visit object contains application-specific |
| * information. |
| * |
| * @deprecated To be removed in 4.1. Inject an application state object instead. <strong>Do not |
| * attempt to inject property visit</strong>. |
| */ |
| |
| public Object getVisit(); |
| |
| /** |
| * Returns the globally shared application object. The global object is stored in the servlet |
| * context. |
| * <p> |
| * Returns the global object, if it exists, or null if not defined. |
| * |
| * @since 2.3 |
| * @deprecated To be removed in 4.1. Inject an application state object instead. <strong>Do not |
| * attempt to inject property global.</strong> |
| */ |
| |
| public Object getGlobal(); |
| |
| /** |
| * @since 1.0.5 |
| * @deprecated To be removed in 4.1 Use |
| * {@link #addPageBeginRenderListener(PageBeginRenderListener)}or |
| * {@link #addPageEndRenderListener(PageEndRenderListener)}. |
| */ |
| |
| public void addPageRenderListener(PageRenderListener listener); |
| |
| /** |
| * @since 2.1 |
| * @deprecated To be removed in 4.1. Use |
| * {@link #removePageBeginRenderListener(PageBeginRenderListener)}or |
| * {@link #removePageEndRenderListener(PageEndRenderListener)}. |
| */ |
| |
| public void removePageRenderListener(PageRenderListener listener); |
| |
| /** @since 4.0 */ |
| public void addPageBeginRenderListener(PageBeginRenderListener listener); |
| |
| /** @since 4.0 */ |
| public void removePageBeginRenderListener(PageBeginRenderListener listener); |
| |
| /** @since 4.0 */ |
| |
| public void addPageEndRenderListener(PageEndRenderListener listener); |
| |
| /** @since 4.0 */ |
| |
| public void removePageEndRenderListener(PageEndRenderListener listener); |
| |
| /** |
| * @since 1.0.5 |
| */ |
| |
| public void addPageDetachListener(PageDetachListener listener); |
| |
| /** |
| * @since 2.1 |
| */ |
| |
| public void removePageDetachListener(PageDetachListener listener); |
| |
| /** |
| * @since 3.0 |
| */ |
| |
| public void addPageValidateListener(PageValidateListener listener); |
| |
| /** |
| * @since 3.0 |
| */ |
| |
| public void removePageValidateListener(PageValidateListener listener); |
| |
| /** @since 4.0 */ |
| |
| public void addPageAttachListener(PageAttachListener listener); |
| |
| /** @since 4.0 */ |
| |
| public void removePageAttachListener(PageAttachListener listener); |
| } |