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