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