Classes in this File | Line Coverage | Branch Coverage | Complexity | ||||
RunData |
|
| 1.0;1 |
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 | } |