1 package org.apache.turbine.util;
2
3
4 /*
5 * Licensed to the Apache Software Foundation (ASF) under one
6 * or more contributor license agreements. See the NOTICE file
7 * distributed with this work for additional information
8 * regarding copyright ownership. The ASF licenses this file
9 * to you under the Apache License, Version 2.0 (the
10 * "License"); you may not use this file except in compliance
11 * with the License. You may obtain a copy of the License at
12 *
13 * http://www.apache.org/licenses/LICENSE-2.0
14 *
15 * Unless required by applicable law or agreed to in writing,
16 * software distributed under the License is distributed on an
17 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
18 * KIND, either express or implied. See the License for the
19 * specific language governing permissions and limitations
20 * under the License.
21 */
22
23
24 import java.io.IOException;
25 import java.io.PrintWriter;
26 import java.nio.charset.Charset;
27 import java.util.Locale;
28 import java.util.Map;
29
30 import javax.naming.Context;
31 import javax.servlet.ServletConfig;
32 import javax.servlet.ServletContext;
33 import javax.servlet.http.HttpServletRequest;
34 import javax.servlet.http.HttpServletResponse;
35 import javax.servlet.http.HttpSession;
36
37 import org.apache.fulcrum.parser.CookieParser;
38 import org.apache.fulcrum.parser.ParameterParser;
39 import org.apache.fulcrum.security.acl.AccessControlList;
40 import org.apache.turbine.om.security.User;
41 import org.apache.turbine.pipeline.PipelineData;
42 import org.apache.turbine.util.template.TemplateInfo;
43
44 /**
45 * RunData is an interface to run-time information that is passed
46 * within Turbine. This provides the threading mechanism for the
47 * entire system because multiple requests can potentially come in
48 * at the same time. Thus, there is only one RunData instance
49 * for each request that is being serviced.
50 *
51 * @author <a href="mailto:ilkka.priha@simsoft.fi">Ilkka Priha</a>
52 * @author <a href="mailto:jon@clearink.com">Jon S. Stevens</a>
53 * @author <a href="mailto:bhoeneis@ee.ethz.ch">Bernie Hoeneisen</a>
54 * @author <a href="mailto:dlr@finemaltcoding.com">Daniel Rall</a>
55 * @author <a href="mailto:quintonm@bellsouth.net">Quinton McCombs</a>
56 * @version $Id$
57 */
58 public interface RunData extends PipelineData
59 {
60 /**
61 * Gets the parameters.
62 *
63 * @return a parameter parser.
64 */
65 ParameterParser getParameters();
66
67 /**
68 * Gets the cookies.
69 *
70 * @return a cookie parser.
71 */
72 CookieParser getCookies();
73
74 /**
75 * Gets the servlet request.
76 *
77 * @return the request.
78 */
79 HttpServletRequest getRequest();
80
81 /**
82 * Gets the servlet response.
83 *
84 * @return the resposne.
85 */
86 HttpServletResponse getResponse();
87
88 /**
89 * Gets the servlet session information.
90 *
91 * @return the session.
92 */
93 HttpSession getSession();
94
95 /**
96 * Gets the servlet configuration used during servlet init.
97 *
98 * @return the configuration.
99 */
100 ServletConfig getServletConfig();
101
102 /**
103 * Gets the servlet context used during servlet init.
104 *
105 * @return the context.
106 */
107 ServletContext getServletContext();
108
109 /**
110 * Gets the access control list.
111 *
112 * @return the access control list.
113 *
114 * @param <A> a type extending {@link AccessControlList}
115 */
116 <A extends AccessControlList> A getACL();
117
118 /**
119 * Sets the access control list.
120 *
121 * @param <A> ACL type
122 * @param acl an access control list.
123 */
124 <A extends AccessControlList> void setACL(A acl);
125
126 /**
127 * Whether or not an action has been defined.
128 *
129 * @return true if an action has been defined.
130 */
131 boolean hasAction();
132
133 /**
134 * Gets the action. It returns an empty string if null so
135 * that it is easy to do conditionals on it based on the
136 * equalsIgnoreCase() method.
137 *
138 * @return a string, "" if null.
139 */
140 String getAction();
141
142 /**
143 * Sets the action for the request.
144 *
145 * @param action a string.
146 */
147 void setAction(String action);
148
149 /**
150 * If the Layout has not been defined by the screen then set the
151 * layout to be "DefaultLayout". The screen object can also
152 * override this method to provide intelligent determination of
153 * the Layout to execute. You can also define that logic here as
154 * well if you want it to apply on a global scale. For example,
155 * if you wanted to allow someone to define layout "preferences"
156 * where they could dynamically change the layout for the entire
157 * site.
158 *
159 * @return a string.
160 */
161 String getLayout();
162
163 /**
164 * Set the layout for the request.
165 *
166 * @param layout a string.
167 */
168 void setLayout(String layout);
169
170 /**
171 * Convenience method for a template info that
172 * returns the layout template being used.
173 *
174 * @return a string.
175 */
176 String getLayoutTemplate();
177
178 /**
179 * Modifies the layout template for the screen. This convenience
180 * method allows for a layout to be modified from within a
181 * template. For example;
182 *
183 * $data.setLayoutTemplate("NewLayout.vm")
184 *
185 * @param layout a layout template.
186 */
187 void setLayoutTemplate(String layout);
188
189 /**
190 * Whether or not a screen has been defined.
191 *
192 * @return true if a screen has been defined.
193 */
194 boolean hasScreen();
195
196 /**
197 * Gets the screen to execute.
198 *
199 * @return a string.
200 */
201 String getScreen();
202
203 /**
204 * Sets the screen for the request.
205 *
206 * @param screen a string.
207 */
208 void setScreen(String screen);
209
210 /**
211 * Convenience method for a template info that
212 * returns the name of the template being used.
213 *
214 * @return a string.
215 */
216 String getScreenTemplate();
217
218 /**
219 * Sets the screen template for the request. For
220 * example;
221 *
222 * $data.setScreenTemplate("NewScreen.vm")
223 *
224 * @param screen a screen template.
225 */
226 void setScreenTemplate(String screen);
227
228 /**
229 * Gets the character encoding to use for reading template files.
230 *
231 * @return the template encoding or null if not specified.
232 */
233 String getTemplateEncoding();
234
235 /**
236 * Sets the character encoding to use for reading template files.
237 *
238 * @param encoding the template encoding.
239 */
240 void setTemplateEncoding(String encoding);
241
242 /**
243 * Gets the template info. Creates a new one if needed.
244 *
245 * @return a template info.
246 */
247 TemplateInfo getTemplateInfo();
248
249 /**
250 * Whether or not a message has been defined.
251 *
252 * @return true if a message has been defined.
253 */
254 boolean hasMessage();
255
256 /**
257 * Gets the results of an action or another message
258 * to be displayed as a string.
259 *
260 * @return a string.
261 */
262 String getMessage();
263
264 /**
265 * Sets the message for the request as a string.
266 *
267 * @param msg a string.
268 */
269 void setMessage(String msg);
270
271 /**
272 * Adds the string to message. If message has prior messages from
273 * other actions or screens, this method can be used to chain them.
274 *
275 * @param msg a string.
276 */
277 void addMessage(String msg);
278
279 /**
280 * Gets the results of an action or another message
281 * to be displayed as a string.
282 *
283 * @return a string.
284 */
285 String getMessageAsHTML();
286
287 /**
288 * Unsets the message for the request.
289 */
290 void unsetMessage();
291
292 /**
293 * Gets a FormMessages object where all the messages to the
294 * user should be stored.
295 *
296 * @return a FormMessages.
297 */
298 FormMessages getMessages();
299
300 /**
301 * Sets the FormMessages object for the request.
302 *
303 * @param msgs A FormMessages.
304 */
305 void setMessages(FormMessages msgs);
306
307 /**
308 * Gets the title of the page.
309 *
310 * @return a string.
311 */
312 String getTitle();
313
314 /**
315 * Sets the title of the page.
316 *
317 * @param title a string.
318 */
319 void setTitle(String title);
320
321 /**
322 * Checks if a user exists in this session.
323 *
324 * @return true if a user exists in this session.
325 */
326 boolean userExists();
327
328 /**
329 * Gets the user.
330 *
331 * @param <T> a type extending {@link User}
332 *
333 * @return a user.
334 */
335 <T extends User> T getUser();
336
337 /**
338 * Sets the user.
339 *
340 * @param user a user.
341 *
342 * @param <T> a type extending {@link User}
343 */
344 <T extends User> void setUser(T user);
345
346 /**
347 * Attempts to get the user from the session. If it does
348 * not exist, it returns null.
349 *
350 * @return a user.
351 *
352 * @param <T> a type extending {@link User}
353 */
354 <T extends User> T getUserFromSession();
355
356 /**
357 * Allows one to invalidate the user in the default session.
358 *
359 * @return true if user was invalidated.
360 */
361 boolean removeUserFromSession();
362
363 /**
364 * Checks to see if out is set.
365 *
366 * @return true if out is set.
367 * @deprecated no replacement planned, response writer will not be cached
368 */
369 @Deprecated
370 boolean isOutSet();
371
372 /**
373 * Gets the print writer. First time calling this
374 * will set the print writer via the response.
375 *
376 * @return a print writer.
377 * @throws IOException on failure getting the PrintWriter
378 */
379 PrintWriter getOut()
380 throws IOException;
381
382 /**
383 * Declares that output will be direct to the response stream,
384 * even though getOut() may never be called. Useful for response
385 * mechanisms that may call res.getWriter() themselves
386 * (such as JSP.)
387 */
388 void declareDirectResponse();
389
390 /**
391 * Gets the locale. If it has not already been defined with
392 * setLocale(), then properties named "locale.default.lang"
393 * and "locale.default.country" are checked from the Resource
394 * Service and the corresponding locale is returned. If these
395 * properties are undefined, JVM's default locale is returned.
396 *
397 * @return the locale.
398 */
399 Locale getLocale();
400
401 /**
402 * Sets the locale.
403 *
404 * @param locale the new locale.
405 */
406 void setLocale(Locale locale);
407
408 /**
409 * Gets the charset. If it has not already been defined with
410 * setCharSet(), then a property named "locale.default.charset"
411 * is checked from the Resource Service and returned. If this
412 * property is undefined, the default charset of the locale
413 * is returned. If the locale is undefined, null is returned.
414 *
415 * @return the name of the charset or null.
416 */
417 @Deprecated
418 String getCharSet();
419
420 /**
421 * Sets the charset.
422 *
423 * @param charset the name of the new charset.
424 */
425 @Deprecated
426 void setCharSet(String charset);
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 charset or null.
436 */
437 Charset getCharset();
438
439 /**
440 * Sets the charset.
441 *
442 * @param charset the new charset.
443 */
444 void setCharset(Charset 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<String, Context> getJNDIContexts();
516
517 /**
518 * Sets JNDI Contexts.
519 *
520 * @param contexts a hashtable.
521 */
522 void setJNDIContexts(Map<String, Context> 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 * Sets a name/value pair in an internal Map that is accessible from the
623 * Error screen. This is a good way to get debugging information
624 * when an exception is thrown.
625 *
626 * @param name name of the variable
627 * @param value value of the variable.
628 */
629 void setDebugVariable(String name, Object value);
630
631 /**
632 * Gets a Map of debug variables.
633 *
634 * @return a Map of debug variables.
635 */
636 Map<String, Object> getDebugVariables();
637 }