|
|||||||||||||||||||
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.tapestry.event.ChangeObserver; | |
20 | import org.apache.tapestry.event.PageAttachListener; | |
21 | import org.apache.tapestry.event.PageBeginRenderListener; | |
22 | import org.apache.tapestry.event.PageDetachListener; | |
23 | import org.apache.tapestry.event.PageEndRenderListener; | |
24 | import org.apache.tapestry.event.PageRenderListener; | |
25 | import org.apache.tapestry.event.PageValidateListener; | |
26 | import org.apache.tapestry.util.ContentType; | |
27 | ||
28 | /** | |
29 | * A root level component responsible for generating an entire a page within the application. | |
30 | * <p> | |
31 | * Pages are created dynamically from thier class names (part of the | |
32 | * {@link org.apache.tapestry.spec.IComponentSpecification}). | |
33 | * | |
34 | * @see org.apache.tapestry.engine.IPageSource | |
35 | * @see org.apache.tapestry.engine.IPageLoader | |
36 | * @author Howard Lewis Ship | |
37 | */ | |
38 | ||
39 | public interface IPage extends IComponent | |
40 | { | |
41 | /** | |
42 | * Invoked on a page when it is no longer needed by the engine, just before is is returned to | |
43 | * the pool. The page is expected to null the engine, visit and changeObserver properties. | |
44 | * <p> | |
45 | * Classes should also reset any properties to default values (as if the instance was freshly | |
46 | * instantiated). | |
47 | * | |
48 | * @see org.apache.tapestry.engine.IPageSource#releasePage(IPage) | |
49 | */ | |
50 | ||
51 | public void detach(); | |
52 | ||
53 | /** | |
54 | * Returns the {@link IEngine}that the page is currently attached to. | |
55 | */ | |
56 | ||
57 | public IEngine getEngine(); | |
58 | ||
59 | /** | |
60 | * Returns the object (effectively, an {@link org.apache.tapestry.engine.IPageRecorder}) that | |
61 | * is notified of any changes to persistant properties of the page. | |
62 | */ | |
63 | ||
64 | public ChangeObserver getChangeObserver(); | |
65 | ||
66 | /** | |
67 | * Returns the <code>Locale</code> of the page. The locale may be used to determine what | |
68 | * template is used by the page and the components contained by the page. | |
69 | */ | |
70 | ||
71 | public Locale getLocale(); | |
72 | ||
73 | /** | |
74 | * Updates the page's locale. This is write-once, a subsequent attempt will throw an | |
75 | * {@link ApplicationRuntimeException}. | |
76 | */ | |
77 | ||
78 | public void setLocale(Locale value); | |
79 | ||
80 | /** | |
81 | * Returns the fully qualified name of the page, including its namespace prefix, if any. | |
82 | * | |
83 | * @since 2.3 | |
84 | */ | |
85 | ||
86 | public String getPageName(); | |
87 | ||
88 | /** | |
89 | * Sets the name of the page. | |
90 | * | |
91 | * @param pageName | |
92 | * fully qualified page name (including namespace prefix, if any) | |
93 | * @since 3.0 | |
94 | */ | |
95 | ||
96 | public void setPageName(String pageName); | |
97 | ||
98 | /** | |
99 | * Returns a particular component from within the page. The path is a dotted name sequence | |
100 | * identifying the component. It may be null in which case the page returns itself. | |
101 | * | |
102 | * @exception ApplicationRuntimeException | |
103 | * runtime exception thrown if the path does not identify a component. | |
104 | */ | |
105 | ||
106 | public IComponent getNestedComponent(String path); | |
107 | ||
108 | /** | |
109 | * Attaches the page to the {@link IEngine engine}. This method is used when a pooled page is | |
110 | * claimed for use with a particular engine; it will stay attached to the engine until the end | |
111 | * of the current request cycle, then be returned to the pool. | |
112 | * <p> | |
113 | * This method will notify any {@link PageAttachListener}s. | |
114 | * <p> | |
115 | * This method is rarely overriden; to initialize page properties before a render, implement the | |
116 | * {@link PageBeginRenderListener}interface. | |
117 | */ | |
118 | ||
119 | public void attach(IEngine engine, IRequestCycle cycle); | |
120 | ||
121 | /** | |
122 | * Invoked to render the entire page. This should only be invoked by | |
123 | * {@link IRequestCycle#renderPage(IMarkupWriter writer)}. | |
124 | * <p> | |
125 | * The page performs a render using the following steps: | |
126 | * <ul> | |
127 | * <li>Invokes | |
128 | * {@link PageBeginRenderListener#pageBeginRender(org.apache.tapestry.event.PageEvent)} | |
129 | * <li>Invokes {@link #beginResponse(IMarkupWriter, IRequestCycle)} | |
130 | * <li>Invokes {@link IRequestCycle#commitPageChanges()}(if not rewinding) | |
131 | * <li>Invokes {@link #render(IMarkupWriter, IRequestCycle)} | |
132 | * <li>Invokes {@link PageEndRenderListener#pageEndRender(org.apache.tapestry.event.PageEvent)} | |
133 | * (this occurs even if a previous step throws an exception). | |
134 | * </ul> | |
135 | */ | |
136 | ||
137 | public void renderPage(IMarkupWriter writer, IRequestCycle cycle); | |
138 | ||
139 | /** | |
140 | * Invoked before a partial render of the page occurs (this happens when rewinding a | |
141 | * {@link org.apache.tapestry.form.Form}within the page). The page is expected to fire | |
142 | * appopriate events. | |
143 | * | |
144 | * @since 2.2 | |
145 | */ | |
146 | ||
147 | public void beginPageRender(); | |
148 | ||
149 | /** | |
150 | * Invoked after a partial render of the page occurs (this happens when rewinding a | |
151 | * {@link org.apache.tapestry.form.Form}within the page). The page is expected to fire | |
152 | * appropriate events. | |
153 | * | |
154 | * @since 2.2 | |
155 | */ | |
156 | ||
157 | public void endPageRender(); | |
158 | ||
159 | public void setChangeObserver(ChangeObserver value); | |
160 | ||
161 | /** | |
162 | * Method invoked by the page, action and direct services to validate that the user is allowed | |
163 | * to visit the page. | |
164 | * <p> | |
165 | * Most web applications have a concept of 'logging in' and pages that an anonymous (not logged | |
166 | * in) user should not be able to visit directly. This method acts as the first line of defense | |
167 | * against a malicous user hacking URLs. | |
168 | * <p> | |
169 | * Pages that should be protected will typically throw a {@linkPageRedirectException}, to | |
170 | * redirect the user to an appropriate part of the system (such as, a login page). | |
171 | * <p> | |
172 | * Since 3.0, it is easiest to not override this method, but to implement the | |
173 | * {@link PageValidateListener}interface instead. | |
174 | */ | |
175 | ||
176 | public void validate(IRequestCycle cycle); | |
177 | ||
178 | /** | |
179 | * Invoked to obtain the content type to be used for the response. The implementation of this | |
180 | * method is the primary difference between an HTML page and an XML/WML/etc. page. | |
181 | */ | |
182 | ||
183 | public ContentType getResponseContentType(); | |
184 | ||
185 | /** | |
186 | * Invoked just before rendering of the page is initiated. This gives the page a chance to | |
187 | * perform any additional setup. One possible behavior is to set HTTP headers and cookies before | |
188 | * any output is generated. | |
189 | * <p> | |
190 | * The timing of this explicitly <em>before</em> | |
191 | * {@link org.apache.tapestry.engine.IPageRecorder page recorder}changes are committed. | |
192 | * Rendering occurs <em>after</em> the recorders are committed, when it is too late to make | |
193 | * changes to dynamic page properties. | |
194 | */ | |
195 | ||
196 | public void beginResponse(IMarkupWriter writer, IRequestCycle cycle); | |
197 | ||
198 | /** | |
199 | * Returns the current {@link IRequestCycle}. This is set when the page is loaded (or obtained | |
200 | * from the pool) and attached to the {@link IEngine engine}. | |
201 | */ | |
202 | ||
203 | public IRequestCycle getRequestCycle(); | |
204 | ||
205 | /** | |
206 | * Returns the visit object for the application; the visit object contains application-specific | |
207 | * information. | |
208 | * | |
209 | * @deprecated To be removed in 4.1. Inject an application state object instead. <strong>Do not | |
210 | * attempt to inject property visit</strong>. | |
211 | */ | |
212 | ||
213 | public Object getVisit(); | |
214 | ||
215 | /** | |
216 | * Returns the globally shared application object. The global object is stored in the servlet | |
217 | * context. | |
218 | * <p> | |
219 | * Returns the global object, if it exists, or null if not defined. | |
220 | * | |
221 | * @since 2.3 | |
222 | * @deprecated To be removed in 4.1. Inject an application state object instead. <strong>Do not | |
223 | * attempt to inject property global.</strong> | |
224 | */ | |
225 | ||
226 | public Object getGlobal(); | |
227 | ||
228 | /** | |
229 | * @since 1.0.5 | |
230 | * @deprecated To be removed in 4.1 Use | |
231 | * {@link #addPageBeginRenderListener(PageBeginRenderListener)}or | |
232 | * {@link #addPageEndRenderListener(PageEndRenderListener)}. | |
233 | */ | |
234 | ||
235 | public void addPageRenderListener(PageRenderListener listener); | |
236 | ||
237 | /** | |
238 | * @since 2.1 | |
239 | * @deprecated To be removed in 4.1. Use | |
240 | * {@link #removePageBeginRenderListener(PageBeginRenderListener)}or | |
241 | * {@link #removePageEndRenderListener(PageEndRenderListener)}. | |
242 | */ | |
243 | ||
244 | public void removePageRenderListener(PageRenderListener listener); | |
245 | ||
246 | /** @since 4.0 */ | |
247 | public void addPageBeginRenderListener(PageBeginRenderListener listener); | |
248 | ||
249 | /** @since 4.0 */ | |
250 | public void removePageBeginRenderListener(PageBeginRenderListener listener); | |
251 | ||
252 | /** @since 4.0 */ | |
253 | ||
254 | public void addPageEndRenderListener(PageEndRenderListener listener); | |
255 | ||
256 | /** @since 4.0 */ | |
257 | ||
258 | public void removePageEndRenderListener(PageEndRenderListener listener); | |
259 | ||
260 | /** | |
261 | * @since 1.0.5 | |
262 | */ | |
263 | ||
264 | public void addPageDetachListener(PageDetachListener listener); | |
265 | ||
266 | /** | |
267 | * @since 2.1 | |
268 | */ | |
269 | ||
270 | public void removePageDetachListener(PageDetachListener listener); | |
271 | ||
272 | /** | |
273 | * @since 3.0 | |
274 | */ | |
275 | ||
276 | public void addPageValidateListener(PageValidateListener listener); | |
277 | ||
278 | /** | |
279 | * @since 3.0 | |
280 | */ | |
281 | ||
282 | public void removePageValidateListener(PageValidateListener listener); | |
283 | ||
284 | /** @since 4.0 */ | |
285 | ||
286 | public void addPageAttachListener(PageAttachListener listener); | |
287 | ||
288 | /** @since 4.0 */ | |
289 | ||
290 | public void removePageAttachListener(PageAttachListener listener); | |
291 | } |
|