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