|
|||||||||||||||||||
30 day Evaluation License registered to hlship@comcast.net Your 30 day evaluation period has expired. Please visit http://www.cenqua.com to obtain a licensed version of Clover | |||||||||||||||||||
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 | * 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 | } |
|