001: package org.apache.turbine.util;
002:
003: /*
004: * Licensed to the Apache Software Foundation (ASF) under one
005: * or more contributor license agreements. See the NOTICE file
006: * distributed with this work for additional information
007: * regarding copyright ownership. The ASF licenses this file
008: * to you under the Apache License, Version 2.0 (the
009: * "License"); you may not use this file except in compliance
010: * with the License. You may obtain a copy of the License at
011: *
012: * http://www.apache.org/licenses/LICENSE-2.0
013: *
014: * Unless required by applicable law or agreed to in writing,
015: * software distributed under the License is distributed on an
016: * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
017: * KIND, either express or implied. See the License for the
018: * specific language governing permissions and limitations
019: * under the License.
020: */
021:
022: import java.io.IOException;
023: import java.io.PrintWriter;
024: import java.util.Locale;
025: import java.util.Map;
026: import javax.servlet.ServletConfig;
027: import javax.servlet.ServletContext;
028: import javax.servlet.http.HttpServletRequest;
029: import javax.servlet.http.HttpServletResponse;
030: import javax.servlet.http.HttpSession;
031:
032: import org.apache.ecs.Document;
033: import org.apache.ecs.Element;
034: import org.apache.ecs.StringElement;
035:
036: import org.apache.turbine.om.security.User;
037: import org.apache.turbine.util.parser.CookieParser;
038: import org.apache.turbine.util.parser.ParameterParser;
039: import org.apache.turbine.util.security.AccessControlList;
040: import org.apache.turbine.util.template.TemplateInfo;
041:
042: /**
043: * RunData is an interface to run-time information that is passed
044: * within Turbine. This provides the threading mechanism for the
045: * entire system because multiple requests can potentially come in
046: * at the same time. Thus, there is only one RunData implementation
047: * for each request that is being serviced.
048: *
049: * @author <a href="mailto:ilkka.priha@simsoft.fi">Ilkka Priha</a>
050: * @author <a href="mailto:jon@clearink.com">Jon S. Stevens</a>
051: * @author <a href="mailto:bhoeneis@ee.ethz.ch">Bernie Hoeneisen</a>
052: * @author <a href="mailto:dlr@finemaltcoding.com">Daniel Rall</a>
053: * @author <a href="mailto:quintonm@bellsouth.net">Quinton McCombs</a>
054: * @version $Id: RunData.java 534527 2007-05-02 16:10:59Z tv $
055: */
056: public interface RunData {
057: /**
058: * Gets the parameters.
059: *
060: * @return a parameter parser.
061: */
062: ParameterParser getParameters();
063:
064: /**
065: * Gets the cookies.
066: *
067: * @return a cookie parser.
068: */
069: CookieParser getCookies();
070:
071: /**
072: * Gets the servlet request.
073: *
074: * @return the request.
075: */
076: HttpServletRequest getRequest();
077:
078: /**
079: * Gets the servlet response.
080: *
081: * @return the resposne.
082: */
083: HttpServletResponse getResponse();
084:
085: /**
086: * Gets the servlet session information.
087: *
088: * @return the session.
089: */
090: HttpSession getSession();
091:
092: /**
093: * Gets the servlet configuration used during servlet init.
094: *
095: * @return the configuration.
096: */
097: ServletConfig getServletConfig();
098:
099: /**
100: * Gets the servlet context used during servlet init.
101: *
102: * @return the context.
103: */
104: ServletContext getServletContext();
105:
106: /**
107: * Gets the access control list.
108: *
109: * @return the access control list.
110: */
111: AccessControlList getACL();
112:
113: /**
114: * Sets the access control list.
115: *
116: * @param acl an access control list.
117: */
118: void setACL(AccessControlList acl);
119:
120: /**
121: * Checks to see if the page is set.
122: *
123: * @return true if the page is set.
124: * @deprecated no replacement planned, ECS is no longer a requirement
125: */
126: boolean isPageSet();
127:
128: /**
129: * Gets the page.
130: *
131: * @return a document.
132: * @deprecated no replacement planned, ECS is no longer a requirement
133: */
134: Document getPage();
135:
136: /**
137: * Whether or not an action has been defined.
138: *
139: * @return true if an action has been defined.
140: */
141: boolean hasAction();
142:
143: /**
144: * Gets the action. It returns an empty string if null so
145: * that it is easy to do conditionals on it based on the
146: * equalsIgnoreCase() method.
147: *
148: * @return a string, "" if null.
149: */
150: String getAction();
151:
152: /**
153: * Sets the action for the request.
154: *
155: * @param action a atring.
156: */
157: void setAction(String action);
158:
159: /**
160: * If the Layout has not been defined by the screen then set the
161: * layout to be "DefaultLayout". The screen object can also
162: * override this method to provide intelligent determination of
163: * the Layout to execute. You can also define that logic here as
164: * well if you want it to apply on a global scale. For example,
165: * if you wanted to allow someone to define layout "preferences"
166: * where they could dynamicially change the layout for the entire
167: * site.
168: *
169: * @return a string.
170: */
171: String getLayout();
172:
173: /**
174: * Set the layout for the request.
175: *
176: * @param layout a string.
177: */
178: void setLayout(String layout);
179:
180: /**
181: * Convenience method for a template info that
182: * returns the layout template being used.
183: *
184: * @return a string.
185: */
186: String getLayoutTemplate();
187:
188: /**
189: * Modifies the layout template for the screen. This convenience
190: * method allows for a layout to be modified from within a
191: * template. For example;
192: *
193: * $data.setLayoutTemplate("NewLayout.vm")
194: *
195: * @param layout a layout template.
196: */
197: void setLayoutTemplate(String layout);
198:
199: /**
200: * Whether or not a screen has been defined.
201: *
202: * @return true if a screen has been defined.
203: */
204: boolean hasScreen();
205:
206: /**
207: * Gets the screen to execute.
208: *
209: * @return a string.
210: */
211: String getScreen();
212:
213: /**
214: * Sets the screen for the request.
215: *
216: * @param screen a string.
217: */
218: void setScreen(String screen);
219:
220: /**
221: * Convenience method for a template info that
222: * returns the name of the template being used.
223: *
224: * @return a string.
225: */
226: String getScreenTemplate();
227:
228: /**
229: * Sets the screen template for the request. For
230: * example;
231: *
232: * $data.setScreenTemplate("NewScreen.vm")
233: *
234: * @param screen a screen template.
235: */
236: void setScreenTemplate(String screen);
237:
238: /**
239: * Gets the character encoding to use for reading template files.
240: *
241: * @return the template encoding or null if not specified.
242: */
243: String getTemplateEncoding();
244:
245: /**
246: * Sets the character encoding to use for reading template files.
247: *
248: * @param encoding the template encoding.
249: */
250: void setTemplateEncoding(String encoding);
251:
252: /**
253: * Gets the template info. Creates a new one if needed.
254: *
255: * @return a template info.
256: */
257: TemplateInfo getTemplateInfo();
258:
259: /**
260: * Whether or not a message has been defined.
261: *
262: * @return true if a message has been defined.
263: */
264: boolean hasMessage();
265:
266: /**
267: * Gets the results of an action or another message
268: * to be displayed as a string.
269: *
270: * @return a string.
271: */
272: String getMessage();
273:
274: /**
275: * Sets the message for the request as a string.
276: *
277: * @param msg a string.
278: */
279: void setMessage(String msg);
280:
281: /**
282: * Adds the string to message. If message has prior messages from
283: * other actions or screens, this method can be used to chain them.
284: *
285: * @param msg a string.
286: */
287: void addMessage(String msg);
288:
289: /**
290: * Gets the results of an action or another message
291: * to be displayed as an ECS string element.
292: *
293: * @return a string element.
294: */
295: StringElement getMessageAsHTML();
296:
297: /**
298: * Sets the message for the request as an ECS element.
299: *
300: * @param msg an element.
301: */
302: void setMessage(Element msg);
303:
304: /**
305: * Adds the ECS element to message. If message has prior messages from
306: * other actions or screens, this method can be used to chain them.
307: *
308: * @param msg an element.
309: */
310: void addMessage(Element msg);
311:
312: /**
313: * Unsets the message for the request.
314: */
315: void unsetMessage();
316:
317: /**
318: * Gets a FormMessages object where all the messages to the
319: * user should be stored.
320: *
321: * @return a FormMessages.
322: */
323: FormMessages getMessages();
324:
325: /**
326: * Sets the FormMessages object for the request.
327: *
328: * @param msgs A FormMessages.
329: */
330: void setMessages(FormMessages msgs);
331:
332: /**
333: * Gets the title of the page.
334: *
335: * @return a string.
336: */
337: String getTitle();
338:
339: /**
340: * Sets the title of the page.
341: *
342: * @param title a string.
343: */
344: void setTitle(String title);
345:
346: /**
347: * Checks if a user exists in this session.
348: *
349: * @return true if a user exists in this session.
350: */
351: boolean userExists();
352:
353: /**
354: * Gets the user.
355: *
356: * @return a user.
357: */
358: User getUser();
359:
360: /**
361: * Sets the user.
362: *
363: * @param user a user.
364: */
365: void setUser(User user);
366:
367: /**
368: * Attempts to get the user from the session. If it does
369: * not exist, it returns null.
370: *
371: * @return a user.
372: */
373: User getUserFromSession();
374:
375: /**
376: * Allows one to invalidate the user in the default session.
377: *
378: * @return true if user was invalidated.
379: */
380: boolean removeUserFromSession();
381:
382: /**
383: * Checks to see if out is set.
384: *
385: * @return true if out is set.
386: * @deprecated no replacement planned, response writer will not be cached
387: */
388: boolean isOutSet();
389:
390: /**
391: * Gets the print writer. First time calling this
392: * will set the print writer via the response.
393: *
394: * @return a print writer.
395: * @throws IOException
396: * @deprecated no replacement planned, response writer will not be cached
397: */
398: PrintWriter getOut() throws IOException;
399:
400: /**
401: * Declares that output will be direct to the response stream,
402: * even though getOut() may never be called. Useful for response
403: * mechanisms that may call res.getWriter() themselves
404: * (such as JSP.)
405: */
406: void declareDirectResponse();
407:
408: /**
409: * Gets the locale. If it has not already been defined with
410: * setLocale(), then properties named "locale.default.lang"
411: * and "locale.default.country" are checked from the Resource
412: * Service and the corresponding locale is returned. If these
413: * properties are undefined, JVM's default locale is returned.
414: *
415: * @return the locale.
416: */
417: Locale getLocale();
418:
419: /**
420: * Sets the locale.
421: *
422: * @param locale the new locale.
423: */
424: void setLocale(Locale locale);
425:
426: /**
427: * Gets the charset. If it has not already been defined with
428: * setCharSet(), then a property named "locale.default.charset"
429: * is checked from the Resource Service and returned. If this
430: * property is undefined, the default charset of the locale
431: * is returned. If the locale is undefined, null is returned.
432: *
433: * @return the name of the charset or null.
434: */
435: String getCharSet();
436:
437: /**
438: * Sets the charset.
439: *
440: * @param charset the name of the new charset.
441: */
442: void setCharSet(String charset);
443:
444: /**
445: * Gets the HTTP content type to return. If a charset
446: * has been specified, it is included in the content type.
447: * If the charset has not been specified and the main type
448: * of the content type is "text", the default charset is
449: * included. If the default charset is undefined, but the
450: * default locale is defined and it is not the US locale,
451: * a locale specific charset is included.
452: *
453: * @return the content type or an empty string.
454: */
455: String getContentType();
456:
457: /**
458: * Sets the HTTP content type to return.
459: *
460: * @param ct the new content type.
461: */
462: void setContentType(String ct);
463:
464: /**
465: * Gets the redirect URI. If this is set, also make sure to set
466: * the status code to 302.
467: *
468: * @return a string, "" if null.
469: */
470: String getRedirectURI();
471:
472: /**
473: * Sets the redirect uri. If this is set, also make sure to set
474: * the status code to 302.
475: *
476: * @param ruri a string.
477: */
478: void setRedirectURI(String ruri);
479:
480: /**
481: * Gets the HTTP status code to return.
482: *
483: * @return the status.
484: */
485: int getStatusCode();
486:
487: /**
488: * Sets the HTTP status code to return.
489: *
490: * @param sc the status.
491: */
492: void setStatusCode(int sc);
493:
494: /**
495: * Gets an array of system errors.
496: *
497: * @return a SystemError[].
498: */
499: SystemError[] getSystemErrors();
500:
501: /**
502: * Adds a critical system error.
503: *
504: * @param err a system error.
505: */
506: void setSystemError(SystemError err);
507:
508: /**
509: * Gets JNDI Contexts.
510: *
511: * @return a hashtable.
512: */
513: Map getJNDIContexts();
514:
515: /**
516: * Sets JNDI Contexts.
517: *
518: * @param contexts a hashtable.
519: */
520: void setJNDIContexts(Map contexts);
521:
522: /**
523: * Gets the cached server scheme.
524: *
525: * @return a string.
526: */
527: String getServerScheme();
528:
529: /**
530: * Gets the cached server name.
531: *
532: * @return a string.
533: */
534: String getServerName();
535:
536: /**
537: * Gets the cached server port.
538: *
539: * @return an int.
540: */
541: int getServerPort();
542:
543: /**
544: * Gets the cached context path.
545: *
546: * @return a string.
547: */
548: String getContextPath();
549:
550: /**
551: * Gets the cached script name.
552: *
553: * @return a string.
554: */
555: String getScriptName();
556:
557: /**
558: * Gets the server data used by the request.
559: *
560: * @return server data.
561: */
562: ServerData getServerData();
563:
564: /**
565: * Gets the IP address of the client that sent the request.
566: *
567: * @return a string.
568: */
569: String getRemoteAddr();
570:
571: /**
572: * Gets the qualified name of the client that sent the request.
573: *
574: * @return a string.
575: */
576: String getRemoteHost();
577:
578: /**
579: * Get the user agent for the request.
580: *
581: * @return a string.
582: */
583: String getUserAgent();
584:
585: /**
586: * Pulls a user object from the session and increments the access
587: * counter and sets the last access date for the object.
588: */
589: void populate();
590:
591: /**
592: * Saves a user object into the session.
593: */
594: void save();
595:
596: /**
597: * Gets the stack trace if set.
598: *
599: * @return the stack trace.
600: */
601: String getStackTrace();
602:
603: /**
604: * Gets the stack trace exception if set.
605: *
606: * @return the stack exception.
607: */
608: Throwable getStackTraceException();
609:
610: /**
611: * Sets the stack trace.
612: *
613: * @param trace the stack trace.
614: * @param exp the exception.
615: */
616: void setStackTrace(String trace, Throwable exp);
617:
618: /**
619: * Gets a table of debug variables.
620: *
621: * @return a Map of debug variables.
622: * @deprecated use {@link #getDebugVariables} instead
623: */
624: Map getVarDebug();
625:
626: /**
627: * Sets a name/value pair in an internal Map that is accessible from the
628: * Error screen. This is a good way to get debugging information
629: * when an exception is thrown.
630: *
631: * @param name name of the variable
632: * @param value value of the variable.
633: */
634: void setDebugVariable(String name, Object value);
635:
636: /**
637: * Gets a Map of debug variables.
638: *
639: * @return a Map of debug variables.
640: */
641: Map getDebugVariables();
642: }
|