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