001 package org.apache.turbine.util;
002
003
004 /*
005 * Licensed to the Apache Software Foundation (ASF) under one
006 * or more contributor license agreements. See the NOTICE file
007 * distributed with this work for additional information
008 * regarding copyright ownership. The ASF licenses this file
009 * to you under the Apache License, Version 2.0 (the
010 * "License"); you may not use this file except in compliance
011 * with the License. You may obtain a copy of the License at
012 *
013 * http://www.apache.org/licenses/LICENSE-2.0
014 *
015 * Unless required by applicable law or agreed to in writing,
016 * software distributed under the License is distributed on an
017 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
018 * KIND, either express or implied. See the License for the
019 * specific language governing permissions and limitations
020 * under the License.
021 */
022
023
024 import java.io.IOException;
025 import java.io.PrintWriter;
026 import java.util.Locale;
027 import java.util.Map;
028
029 import javax.naming.Context;
030 import javax.servlet.ServletConfig;
031 import javax.servlet.ServletContext;
032 import javax.servlet.http.HttpServletRequest;
033 import javax.servlet.http.HttpServletResponse;
034 import javax.servlet.http.HttpSession;
035
036 import org.apache.ecs.Document;
037 import org.apache.ecs.Element;
038 import org.apache.ecs.StringElement;
039 import org.apache.fulcrum.parser.CookieParser;
040 import org.apache.fulcrum.parser.ParameterParser;
041 import org.apache.turbine.om.security.User;
042 import org.apache.turbine.pipeline.PipelineData;
043 import org.apache.turbine.util.security.AccessControlList;
044 import org.apache.turbine.util.template.TemplateInfo;
045
046 /**
047 * RunData is an interface to run-time information that is passed
048 * within Turbine. This provides the threading mechanism for the
049 * entire system because multiple requests can potentially come in
050 * at the same time. Thus, there is only one RunData implementation
051 * for each request that is being serviced.
052 *
053 * @author <a href="mailto:ilkka.priha@simsoft.fi">Ilkka Priha</a>
054 * @author <a href="mailto:jon@clearink.com">Jon S. Stevens</a>
055 * @author <a href="mailto:bhoeneis@ee.ethz.ch">Bernie Hoeneisen</a>
056 * @author <a href="mailto:dlr@finemaltcoding.com">Daniel Rall</a>
057 * @author <a href="mailto:quintonm@bellsouth.net">Quinton McCombs</a>
058 * @version $Id: RunData.java 1066938 2011-02-03 20:14:53Z ludwig $
059 */
060 public interface RunData extends PipelineData
061 {
062 /**
063 * Gets the parameters.
064 *
065 * @return a parameter parser.
066 */
067 ParameterParser getParameters();
068
069 /**
070 * Gets the cookies.
071 *
072 * @return a cookie parser.
073 */
074 CookieParser getCookies();
075
076 /**
077 * Gets the servlet request.
078 *
079 * @return the request.
080 */
081 HttpServletRequest getRequest();
082
083 /**
084 * Gets the servlet response.
085 *
086 * @return the resposne.
087 */
088 HttpServletResponse getResponse();
089
090 /**
091 * Gets the servlet session information.
092 *
093 * @return the session.
094 */
095 HttpSession getSession();
096
097 /**
098 * Gets the servlet configuration used during servlet init.
099 *
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 AccessControlList 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 atring.
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 dynamicially 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 User getUser();
366
367 /**
368 * Sets the user.
369 *
370 * @param user a user.
371 */
372 void setUser(User 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 User 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 * @deprecated no replacement planned, response writer will not be cached
405 */
406 @Deprecated
407 PrintWriter getOut()
408 throws IOException;
409
410 /**
411 * Declares that output will be direct to the response stream,
412 * even though getOut() may never be called. Useful for response
413 * mechanisms that may call res.getWriter() themselves
414 * (such as JSP.)
415 */
416 void declareDirectResponse();
417
418 /**
419 * Gets the locale. If it has not already been defined with
420 * setLocale(), then properties named "locale.default.lang"
421 * and "locale.default.country" are checked from the Resource
422 * Service and the corresponding locale is returned. If these
423 * properties are undefined, JVM's default locale is returned.
424 *
425 * @return the locale.
426 */
427 Locale getLocale();
428
429 /**
430 * Sets the locale.
431 *
432 * @param locale the new locale.
433 */
434 void setLocale(Locale locale);
435
436 /**
437 * Gets the charset. If it has not already been defined with
438 * setCharSet(), then a property named "locale.default.charset"
439 * is checked from the Resource Service and returned. If this
440 * property is undefined, the default charset of the locale
441 * is returned. If the locale is undefined, null is returned.
442 *
443 * @return the name of the charset or null.
444 */
445 String getCharSet();
446
447 /**
448 * Sets the charset.
449 *
450 * @param charset the name of the new charset.
451 */
452 void setCharSet(String charset);
453
454 /**
455 * Gets the HTTP content type to return. If a charset
456 * has been specified, it is included in the content type.
457 * If the charset has not been specified and the main type
458 * of the content type is "text", the default charset is
459 * included. If the default charset is undefined, but the
460 * default locale is defined and it is not the US locale,
461 * a locale specific charset is included.
462 *
463 * @return the content type or an empty string.
464 */
465 String getContentType();
466
467 /**
468 * Sets the HTTP content type to return.
469 *
470 * @param ct the new content type.
471 */
472 void setContentType(String ct);
473
474 /**
475 * Gets the redirect URI. If this is set, also make sure to set
476 * the status code to 302.
477 *
478 * @return a string, "" if null.
479 */
480 String getRedirectURI();
481
482 /**
483 * Sets the redirect uri. If this is set, also make sure to set
484 * the status code to 302.
485 *
486 * @param ruri a string.
487 */
488 void setRedirectURI(String ruri);
489
490 /**
491 * Gets the HTTP status code to return.
492 *
493 * @return the status.
494 */
495 int getStatusCode();
496
497 /**
498 * Sets the HTTP status code to return.
499 *
500 * @param sc the status.
501 */
502 void setStatusCode(int sc);
503
504 /**
505 * Gets an array of system errors.
506 *
507 * @return a SystemError[].
508 */
509 SystemError[] getSystemErrors();
510
511 /**
512 * Adds a critical system error.
513 *
514 * @param err a system error.
515 */
516 void setSystemError(SystemError err);
517
518 /**
519 * Gets JNDI Contexts.
520 *
521 * @return a hashtable.
522 */
523 Map<String, Context> getJNDIContexts();
524
525 /**
526 * Sets JNDI Contexts.
527 *
528 * @param contexts a hashtable.
529 */
530 void setJNDIContexts(Map<String, Context> contexts);
531
532 /**
533 * Gets the cached server scheme.
534 *
535 * @return a string.
536 */
537 String getServerScheme();
538
539 /**
540 * Gets the cached server name.
541 *
542 * @return a string.
543 */
544 String getServerName();
545
546 /**
547 * Gets the cached server port.
548 *
549 * @return an int.
550 */
551 int getServerPort();
552
553 /**
554 * Gets the cached context path.
555 *
556 * @return a string.
557 */
558 String getContextPath();
559
560 /**
561 * Gets the cached script name.
562 *
563 * @return a string.
564 */
565 String getScriptName();
566
567 /**
568 * Gets the server data used by the request.
569 *
570 * @return server data.
571 */
572 ServerData getServerData();
573
574 /**
575 * Gets the IP address of the client that sent the request.
576 *
577 * @return a string.
578 */
579 String getRemoteAddr();
580
581 /**
582 * Gets the qualified name of the client that sent the request.
583 *
584 * @return a string.
585 */
586 String getRemoteHost();
587
588 /**
589 * Get the user agent for the request.
590 *
591 * @return a string.
592 */
593 String getUserAgent();
594
595 /**
596 * Pulls a user object from the session and increments the access
597 * counter and sets the last access date for the object.
598 */
599 void populate();
600
601 /**
602 * Saves a user object into the session.
603 */
604 void save();
605
606 /**
607 * Gets the stack trace if set.
608 *
609 * @return the stack trace.
610 */
611 String getStackTrace();
612
613 /**
614 * Gets the stack trace exception if set.
615 *
616 * @return the stack exception.
617 */
618 Throwable getStackTraceException();
619
620 /**
621 * Sets the stack trace.
622 *
623 * @param trace the stack trace.
624 * @param exp the exception.
625 */
626 void setStackTrace(String trace,
627 Throwable exp);
628
629 /**
630 * Gets a table of debug variables.
631 *
632 * @return a Map of debug variables.
633 * @deprecated use {@link #getDebugVariables} instead
634 */
635 @Deprecated
636 Map<String, Object> getVarDebug();
637
638 /**
639 * Sets a name/value pair in an internal Map that is accessible from the
640 * Error screen. This is a good way to get debugging information
641 * when an exception is thrown.
642 *
643 * @param name name of the variable
644 * @param value value of the variable.
645 */
646 void setDebugVariable(String name, Object value);
647
648 /**
649 * Gets a Map of debug variables.
650 *
651 * @return a Map of debug variables.
652 */
653 Map<String, Object> getDebugVariables();
654 }