IPage


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 }
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags