001 // Copyright 2004, 2005 The Apache Software Foundation
002 //
003 // Licensed under the Apache License, Version 2.0 (the "License");
004 // you may not use this file except in compliance with the License.
005 // You may obtain a copy of the License at
006 //
007 // http://www.apache.org/licenses/LICENSE-2.0
008 //
009 // Unless required by applicable law or agreed to in writing, software
010 // distributed under the License is distributed on an "AS IS" BASIS,
011 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
012 // See the License for the specific language governing permissions and
013 // limitations under the License.
014
015 package org.apache.tapestry;
016
017 import java.util.Locale;
018
019 import org.apache.hivemind.ApplicationRuntimeException;
020 import org.apache.tapestry.event.ChangeObserver;
021 import org.apache.tapestry.event.PageAttachListener;
022 import org.apache.tapestry.event.PageBeginRenderListener;
023 import org.apache.tapestry.event.PageDetachListener;
024 import org.apache.tapestry.event.PageEndRenderListener;
025 import org.apache.tapestry.event.PageRenderListener;
026 import org.apache.tapestry.event.PageValidateListener;
027 import org.apache.tapestry.util.ContentType;
028
029 /**
030 * A root level component responsible for generating an entire a page within the application.
031 * <p>
032 * Pages are created dynamically from thier class names (part of the
033 * {@link org.apache.tapestry.spec.IComponentSpecification}).
034 *
035 * @see org.apache.tapestry.engine.IPageSource
036 * @see org.apache.tapestry.engine.IPageLoader
037 * @author Howard Lewis Ship
038 */
039
040 public interface IPage extends IComponent
041 {
042 /**
043 * Invoked on a page when it is no longer needed by the engine, just before is is returned to
044 * the pool. The page is expected to null the engine, visit and changeObserver properties.
045 * <p>
046 * Classes should also reset any properties to default values (as if the instance was freshly
047 * instantiated).
048 *
049 * @see org.apache.tapestry.engine.IPageSource#releasePage(IPage)
050 */
051
052 public void detach();
053
054 /**
055 * Returns the {@link IEngine}that the page is currently attached to.
056 */
057
058 public IEngine getEngine();
059
060 /**
061 * Returns the object (effectively, an {@link org.apache.tapestry.engine.IPageRecorder}) that
062 * is notified of any changes to persistant properties of the page.
063 */
064
065 public ChangeObserver getChangeObserver();
066
067 /**
068 * Returns the <code>Locale</code> of the page. The locale may be used to determine what
069 * template is used by the page and the components contained by the page.
070 */
071
072 public Locale getLocale();
073
074 /**
075 * Updates the page's locale. This is write-once, a subsequent attempt will throw an
076 * {@link ApplicationRuntimeException}.
077 */
078
079 public void setLocale(Locale value);
080
081 /**
082 * Returns the fully qualified name of the page, including its namespace prefix, if any.
083 *
084 * @since 2.3
085 */
086
087 public String getPageName();
088
089 /**
090 * Sets the name of the page.
091 *
092 * @param pageName
093 * fully qualified page name (including namespace prefix, if any)
094 * @since 3.0
095 */
096
097 public void setPageName(String pageName);
098
099 /**
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 }