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