1 package org.apache.turbine.util;
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19 import java.io.IOException;
20 import java.io.PrintWriter;
21 import java.util.Locale;
22 import java.util.Map;
23 import javax.servlet.ServletConfig;
24 import javax.servlet.ServletContext;
25 import javax.servlet.http.HttpServletRequest;
26 import javax.servlet.http.HttpServletResponse;
27 import javax.servlet.http.HttpSession;
28
29 import org.apache.ecs.Document;
30 import org.apache.ecs.Element;
31 import org.apache.ecs.StringElement;
32
33 import org.apache.turbine.om.security.User;
34 import org.apache.turbine.util.parser.CookieParser;
35 import org.apache.turbine.util.parser.ParameterParser;
36 import org.apache.turbine.util.security.AccessControlList;
37 import org.apache.turbine.util.template.TemplateInfo;
38
39 /***
40 * RunData is an interface to run-time information that is passed
41 * within Turbine. This provides the threading mechanism for the
42 * entire system because multiple requests can potentially come in
43 * at the same time. Thus, there is only one RunData implementation
44 * for each request that is being serviced.
45 *
46 * @author <a href="mailto:ilkka.priha@simsoft.fi">Ilkka Priha</a>
47 * @author <a href="mailto:jon@clearink.com">Jon S. Stevens</a>
48 * @author <a href="mailto:bhoeneis@ee.ethz.ch">Bernie Hoeneisen</a>
49 * @author <a href="mailto:dlr@finemaltcoding.com">Daniel Rall</a>
50 * @author <a href="mailto:quintonm@bellsouth.net">Quinton McCombs</a>
51 * @version $Id: RunData.java 264148 2005-08-29 14:21:04Z henning $
52 */
53 public interface RunData
54 {
55 /***
56 * Gets the parameters.
57 *
58 * @return a parameter parser.
59 */
60 ParameterParser getParameters();
61
62 /***
63 * Gets the cookies.
64 *
65 * @return a cookie parser.
66 */
67 CookieParser getCookies();
68
69 /***
70 * Gets the servlet request.
71 *
72 * @return the request.
73 */
74 HttpServletRequest getRequest();
75
76 /***
77 * Gets the servlet response.
78 *
79 * @return the resposne.
80 */
81 HttpServletResponse getResponse();
82
83 /***
84 * Gets the servlet session information.
85 *
86 * @return the session.
87 */
88 HttpSession getSession();
89
90 /***
91 * Gets the servlet configuration used during servlet init.
92 *
93 * @return the configuration.
94 */
95 ServletConfig getServletConfig();
96
97 /***
98 * Gets the servlet context used during servlet init.
99 *
100 * @return the context.
101 */
102 ServletContext getServletContext();
103
104 /***
105 * Gets the access control list.
106 *
107 * @return the access control list.
108 */
109 AccessControlList getACL();
110
111 /***
112 * Sets the access control list.
113 *
114 * @param acl an access control list.
115 */
116 void setACL(AccessControlList acl);
117
118 /***
119 * Checks to see if the page is set.
120 *
121 * @return true if the page is set.
122 * @deprecated no replacement planned, ECS is no longer a requirement
123 */
124 boolean isPageSet();
125
126 /***
127 * Gets the page.
128 *
129 * @return a document.
130 * @deprecated no replacement planned, ECS is no longer a requirement
131 */
132 Document getPage();
133
134 /***
135 * Whether or not an action has been defined.
136 *
137 * @return true if an action has been defined.
138 */
139 boolean hasAction();
140
141 /***
142 * Gets the action. It returns an empty string if null so
143 * that it is easy to do conditionals on it based on the
144 * equalsIgnoreCase() method.
145 *
146 * @return a string, "" if null.
147 */
148 String getAction();
149
150 /***
151 * Sets the action for the request.
152 *
153 * @param action a atring.
154 */
155 void setAction(String action);
156
157 /***
158 * If the Layout has not been defined by the screen then set the
159 * layout to be "DefaultLayout". The screen object can also
160 * override this method to provide intelligent determination of
161 * the Layout to execute. You can also define that logic here as
162 * well if you want it to apply on a global scale. For example,
163 * if you wanted to allow someone to define layout "preferences"
164 * where they could dynamicially change the layout for the entire
165 * site.
166 *
167 * @return a string.
168 */
169 String getLayout();
170
171 /***
172 * Set the layout for the request.
173 *
174 * @param layout a string.
175 */
176 void setLayout(String layout);
177
178 /***
179 * Convenience method for a template info that
180 * returns the layout template being used.
181 *
182 * @return a string.
183 */
184 String getLayoutTemplate();
185
186 /***
187 * Modifies the layout template for the screen. This convenience
188 * method allows for a layout to be modified from within a
189 * template. For example;
190 *
191 * $data.setLayoutTemplate("NewLayout.vm")
192 *
193 * @param layout a layout template.
194 */
195 void setLayoutTemplate(String layout);
196
197 /***
198 * Whether or not a screen has been defined.
199 *
200 * @return true if a screen has been defined.
201 */
202 boolean hasScreen();
203
204 /***
205 * Gets the screen to execute.
206 *
207 * @return a string.
208 */
209 String getScreen();
210
211 /***
212 * Sets the screen for the request.
213 *
214 * @param screen a string.
215 */
216 void setScreen(String screen);
217
218 /***
219 * Convenience method for a template info that
220 * returns the name of the template being used.
221 *
222 * @return a string.
223 */
224 String getScreenTemplate();
225
226 /***
227 * Sets the screen template for the request. For
228 * example;
229 *
230 * $data.setScreenTemplate("NewScreen.vm")
231 *
232 * @param screen a screen template.
233 */
234 void setScreenTemplate(String screen);
235
236 /***
237 * Gets the character encoding to use for reading template files.
238 *
239 * @return the template encoding or null if not specified.
240 */
241 String getTemplateEncoding();
242
243 /***
244 * Sets the character encoding to use for reading template files.
245 *
246 * @param encoding the template encoding.
247 */
248 void setTemplateEncoding(String encoding);
249
250 /***
251 * Gets the template info. Creates a new one if needed.
252 *
253 * @return a template info.
254 */
255 TemplateInfo getTemplateInfo();
256
257 /***
258 * Whether or not a message has been defined.
259 *
260 * @return true if a message has been defined.
261 */
262 boolean hasMessage();
263
264 /***
265 * Gets the results of an action or another message
266 * to be displayed as a string.
267 *
268 * @return a string.
269 */
270 String getMessage();
271
272 /***
273 * Sets the message for the request as a string.
274 *
275 * @param msg a string.
276 */
277 void setMessage(String msg);
278
279 /***
280 * Adds the string to message. If message has prior messages from
281 * other actions or screens, this method can be used to chain them.
282 *
283 * @param msg a string.
284 */
285 void addMessage(String msg);
286
287 /***
288 * Gets the results of an action or another message
289 * to be displayed as an ECS string element.
290 *
291 * @return a string element.
292 */
293 StringElement getMessageAsHTML();
294
295 /***
296 * Sets the message for the request as an ECS element.
297 *
298 * @param msg an element.
299 */
300 void setMessage(Element msg);
301
302 /***
303 * Adds the ECS element to message. If message has prior messages from
304 * other actions or screens, this method can be used to chain them.
305 *
306 * @param msg an element.
307 */
308 void addMessage(Element msg);
309
310 /***
311 * Unsets the message for the request.
312 */
313 void unsetMessage();
314
315 /***
316 * Gets a FormMessages object where all the messages to the
317 * user should be stored.
318 *
319 * @return a FormMessages.
320 */
321 FormMessages getMessages();
322
323 /***
324 * Sets the FormMessages object for the request.
325 *
326 * @param msgs A FormMessages.
327 */
328 void setMessages(FormMessages msgs);
329
330 /***
331 * Gets the title of the page.
332 *
333 * @return a string.
334 */
335 String getTitle();
336
337 /***
338 * Sets the title of the page.
339 *
340 * @param title a string.
341 */
342 void setTitle(String title);
343
344 /***
345 * Checks if a user exists in this session.
346 *
347 * @return true if a user exists in this session.
348 */
349 boolean userExists();
350
351 /***
352 * Gets the user.
353 *
354 * @return a user.
355 */
356 User getUser();
357
358 /***
359 * Sets the user.
360 *
361 * @param user a user.
362 */
363 void setUser(User user);
364
365 /***
366 * Attempts to get the user from the session. If it does
367 * not exist, it returns null.
368 *
369 * @return a user.
370 */
371 User getUserFromSession();
372
373 /***
374 * Allows one to invalidate the user in the default session.
375 *
376 * @return true if user was invalidated.
377 */
378 boolean removeUserFromSession();
379
380 /***
381 * Checks to see if out is set.
382 *
383 * @return true if out is set.
384 * @deprecated no replacement planned, response writer will not be cached
385 */
386 boolean isOutSet();
387
388 /***
389 * Gets the print writer. First time calling this
390 * will set the print writer via the response.
391 *
392 * @return a print writer.
393 * @throws IOException
394 * @deprecated no replacement planned, response writer will not be cached
395 */
396 PrintWriter getOut()
397 throws IOException;
398
399 /***
400 * Declares that output will be direct to the response stream,
401 * even though getOut() may never be called. Useful for response
402 * mechanisms that may call res.getWriter() themselves
403 * (such as JSP.)
404 */
405 void declareDirectResponse();
406
407 /***
408 * Gets the locale. If it has not already been defined with
409 * setLocale(), then properties named "locale.default.lang"
410 * and "locale.default.country" are checked from the Resource
411 * Service and the corresponding locale is returned. If these
412 * properties are undefined, JVM's default locale is returned.
413 *
414 * @return the locale.
415 */
416 Locale getLocale();
417
418 /***
419 * Sets the locale.
420 *
421 * @param locale the new locale.
422 */
423 void setLocale(Locale locale);
424
425 /***
426 * Gets the charset. If it has not already been defined with
427 * setCharSet(), then a property named "locale.default.charset"
428 * is checked from the Resource Service and returned. If this
429 * property is undefined, the default charset of the locale
430 * is returned. If the locale is undefined, null is returned.
431 *
432 * @return the name of the charset or null.
433 */
434 String getCharSet();
435
436 /***
437 * Sets the charset.
438 *
439 * @param charset the name of the new charset.
440 */
441 void setCharSet(String charset);
442
443 /***
444 * Gets the HTTP content type to return. If a charset
445 * has been specified, it is included in the content type.
446 * If the charset has not been specified and the main type
447 * of the content type is "text", the default charset is
448 * included. If the default charset is undefined, but the
449 * default locale is defined and it is not the US locale,
450 * a locale specific charset is included.
451 *
452 * @return the content type or an empty string.
453 */
454 String getContentType();
455
456 /***
457 * Sets the HTTP content type to return.
458 *
459 * @param ct the new content type.
460 */
461 void setContentType(String ct);
462
463 /***
464 * Gets the redirect URI. If this is set, also make sure to set
465 * the status code to 302.
466 *
467 * @return a string, "" if null.
468 */
469 String getRedirectURI();
470
471 /***
472 * Sets the redirect uri. If this is set, also make sure to set
473 * the status code to 302.
474 *
475 * @param ruri a string.
476 */
477 void setRedirectURI(String ruri);
478
479 /***
480 * Gets the HTTP status code to return.
481 *
482 * @return the status.
483 */
484 int getStatusCode();
485
486 /***
487 * Sets the HTTP status code to return.
488 *
489 * @param sc the status.
490 */
491 void setStatusCode(int sc);
492
493 /***
494 * Gets an array of system errors.
495 *
496 * @return a SystemError[].
497 */
498 SystemError[] getSystemErrors();
499
500 /***
501 * Adds a critical system error.
502 *
503 * @param err a system error.
504 */
505 void setSystemError(SystemError err);
506
507 /***
508 * Gets JNDI Contexts.
509 *
510 * @return a hashtable.
511 */
512 Map getJNDIContexts();
513
514 /***
515 * Sets JNDI Contexts.
516 *
517 * @param contexts a hashtable.
518 */
519 void setJNDIContexts(Map contexts);
520
521 /***
522 * Gets the cached server scheme.
523 *
524 * @return a string.
525 */
526 String getServerScheme();
527
528 /***
529 * Gets the cached server name.
530 *
531 * @return a string.
532 */
533 String getServerName();
534
535 /***
536 * Gets the cached server port.
537 *
538 * @return an int.
539 */
540 int getServerPort();
541
542 /***
543 * Gets the cached context path.
544 *
545 * @return a string.
546 */
547 String getContextPath();
548
549 /***
550 * Gets the cached script name.
551 *
552 * @return a string.
553 */
554 String getScriptName();
555
556 /***
557 * Gets the server data used by the request.
558 *
559 * @return server data.
560 */
561 ServerData getServerData();
562
563 /***
564 * Gets the IP address of the client that sent the request.
565 *
566 * @return a string.
567 */
568 String getRemoteAddr();
569
570 /***
571 * Gets the qualified name of the client that sent the request.
572 *
573 * @return a string.
574 */
575 String getRemoteHost();
576
577 /***
578 * Get the user agent for the request.
579 *
580 * @return a string.
581 */
582 String getUserAgent();
583
584 /***
585 * Pulls a user object from the session and increments the access
586 * counter and sets the last access date for the object.
587 */
588 void populate();
589
590 /***
591 * Saves a user object into the session.
592 */
593 void save();
594
595 /***
596 * Gets the stack trace if set.
597 *
598 * @return the stack trace.
599 */
600 String getStackTrace();
601
602 /***
603 * Gets the stack trace exception if set.
604 *
605 * @return the stack exception.
606 */
607 Throwable getStackTraceException();
608
609 /***
610 * Sets the stack trace.
611 *
612 * @param trace the stack trace.
613 * @param exp the exception.
614 */
615 void setStackTrace(String trace,
616 Throwable exp);
617
618 /***
619 * Gets a table of debug variables.
620 *
621 * @return a Map of debug variables.
622 * @deprecated use {@link #getDebugVariables} instead
623 */
624 Map getVarDebug();
625
626 /***
627 * Sets a name/value pair in an internal Map that is accessible from the
628 * Error screen. This is a good way to get debugging information
629 * when an exception is thrown.
630 *
631 * @param name name of the variable
632 * @param value value of the variable.
633 */
634 void setDebugVariable(String name, Object value);
635
636 /***
637 * Gets a Map of debug variables.
638 *
639 * @return a Map of debug variables.
640 */
641 Map getDebugVariables();
642 }