KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > apache > turbine > util > RunData


1 package org.apache.turbine.util;
2
3 /*
4  * Copyright 2001-2004 The Apache Software Foundation.
5  *
6  * Licensed under the Apache License, Version 2.0 (the "License")
7  * you may not use this file except in compliance with the License.
8  * You may obtain a copy of the License at
9  *
10  * http://www.apache.org/licenses/LICENSE-2.0
11  *
12  * Unless required by applicable law or agreed to in writing, software
13  * distributed under the License is distributed on an "AS IS" BASIS,
14  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15  * See the License for the specific language governing permissions and
16  * limitations under the License.
17  */

18
19 import java.io.IOException JavaDoc;
20 import java.io.PrintWriter JavaDoc;
21 import java.util.Locale JavaDoc;
22 import java.util.Map JavaDoc;
23 import javax.servlet.ServletConfig JavaDoc;
24 import javax.servlet.ServletContext JavaDoc;
25 import javax.servlet.http.HttpServletRequest JavaDoc;
26 import javax.servlet.http.HttpServletResponse JavaDoc;
27 import javax.servlet.http.HttpSession JavaDoc;
28
29 import org.apache.ecs.Document;
30 import org.apache.ecs.Element;
31 import org.apache.ecs.StringElement;
32
33 import org.apache.turbine.om.security.User;
34 import org.apache.turbine.util.parser.CookieParser;
35 import org.apache.turbine.util.parser.ParameterParser;
36 import org.apache.turbine.util.security.AccessControlList;
37 import org.apache.turbine.util.template.TemplateInfo;
38
39 /**
40  * RunData is an interface to run-time information that is passed
41  * within Turbine. This provides the threading mechanism for the
42  * entire system because multiple requests can potentially come in
43  * at the same time. Thus, there is only one RunData implementation
44  * for each request that is being serviced.
45  *
46  * @author <a HREF="mailto:ilkka.priha@simsoft.fi">Ilkka Priha</a>
47  * @author <a HREF="mailto:jon@clearink.com">Jon S. Stevens</a>
48  * @author <a HREF="mailto:bhoeneis@ee.ethz.ch">Bernie Hoeneisen</a>
49  * @author <a HREF="mailto:dlr@finemaltcoding.com">Daniel Rall</a>
50  * @author <a HREF="mailto:quintonm@bellsouth.net">Quinton McCombs</a>
51  * @version $Id: RunData.java,v 1.9.2.2 2004/05/20 03:16:38 seade Exp $
52  */

53 public interface RunData
54 {
55     /**
56      * Gets the parameters.
57      *
58      * @return a parameter parser.
59      */

60     ParameterParser getParameters();
61
62     /**
63      * Gets the cookies.
64      *
65      * @return a cookie parser.
66      */

67     CookieParser getCookies();
68
69     /**
70      * Gets the servlet request.
71      *
72      * @return the request.
73      */

74     HttpServletRequest JavaDoc getRequest();
75
76     /**
77      * Gets the servlet response.
78      *
79      * @return the resposne.
80      */

81     HttpServletResponse JavaDoc getResponse();
82
83     /**
84      * Gets the servlet session information.
85      *
86      * @return the session.
87      */

88     HttpSession JavaDoc getSession();
89
90     /**
91      * Gets the servlet configuration used during servlet init.
92      *
93      * @return the configuration.
94      */

95     ServletConfig JavaDoc getServletConfig();
96
97     /**
98      * Gets the servlet context used during servlet init.
99      *
100      * @return the context.
101      */

102     ServletContext JavaDoc getServletContext();
103
104     /**
105      * Gets the access control list.
106      *
107      * @return the access control list.
108      */

109     AccessControlList getACL();
110
111     /**
112      * Sets the access control list.
113      *
114      * @param acl an access control list.
115      */

116     void setACL(AccessControlList acl);
117
118     /**
119      * Checks to see if the page is set.
120      *
121      * @return true if the page is set.
122      * @deprecated no replacement planned, ECS is no longer a requirement
123      */

124     boolean isPageSet();
125
126     /**
127      * Gets the page.
128      *
129      * @return a document.
130      * @deprecated no replacement planned, ECS is no longer a requirement
131      */

132     Document getPage();
133
134     /**
135      * Whether or not an action has been defined.
136      *
137      * @return true if an action has been defined.
138      */

139     boolean hasAction();
140
141     /**
142      * Gets the action. It returns an empty string if null so
143      * that it is easy to do conditionals on it based on the
144      * equalsIgnoreCase() method.
145      *
146      * @return a string, "" if null.
147      */

148     String JavaDoc getAction();
149
150     /**
151      * Sets the action for the request.
152      *
153      * @param action a atring.
154      */

155     void setAction(String JavaDoc action);
156
157     /**
158      * If the Layout has not been defined by the screen then set the
159      * layout to be "DefaultLayout". The screen object can also
160      * override this method to provide intelligent determination of
161      * the Layout to execute. You can also define that logic here as
162      * well if you want it to apply on a global scale. For example,
163      * if you wanted to allow someone to define layout "preferences"
164      * where they could dynamicially change the layout for the entire
165      * site.
166      *
167      * @return a string.
168      */

169     String JavaDoc getLayout();
170
171     /**
172      * Set the layout for the request.
173      *
174      * @param layout a string.
175      */

176     void setLayout(String JavaDoc layout);
177
178     /**
179      * Convenience method for a template info that
180      * returns the layout template being used.
181      *
182      * @return a string.
183      */

184     String JavaDoc getLayoutTemplate();
185
186     /**
187      * Modifies the layout template for the screen. This convenience
188      * method allows for a layout to be modified from within a
189      * template. For example;
190      *
191      * $data.setLayoutTemplate("NewLayout.vm")
192      *
193      * @param layout a layout template.
194      */

195     void setLayoutTemplate(String JavaDoc layout);
196
197     /**
198      * Whether or not a screen has been defined.
199      *
200      * @return true if a screen has been defined.
201      */

202     boolean hasScreen();
203
204     /**
205      * Gets the screen to execute.
206      *
207      * @return a string.
208      */

209     String JavaDoc getScreen();
210
211     /**
212      * Sets the screen for the request.
213      *
214      * @param screen a string.
215      */

216     void setScreen(String JavaDoc screen);
217
218     /**
219      * Convenience method for a template info that
220      * returns the name of the template being used.
221      *
222      * @return a string.
223      */

224     String JavaDoc getScreenTemplate();
225
226     /**
227      * Sets the screen template for the request. For
228      * example;
229      *
230      * $data.setScreenTemplate("NewScreen.vm")
231      *
232      * @param screen a screen template.
233      */

234     void setScreenTemplate(String JavaDoc screen);
235
236     /**
237      * Gets the character encoding to use for reading template files.
238      *
239      * @return the template encoding or null if not specified.
240      */

241     String JavaDoc getTemplateEncoding();
242
243     /**
244      * Sets the character encoding to use for reading template files.
245      *
246      * @param encoding the template encoding.
247      */

248     void setTemplateEncoding(String JavaDoc encoding);
249
250     /**
251      * Gets the template info. Creates a new one if needed.
252      *
253      * @return a template info.
254      */

255     TemplateInfo getTemplateInfo();
256
257     /**
258      * Whether or not a message has been defined.
259      *
260      * @return true if a message has been defined.
261      */

262     boolean hasMessage();
263
264     /**
265      * Gets the results of an action or another message
266      * to be displayed as a string.
267      *
268      * @return a string.
269      */

270     String JavaDoc getMessage();
271
272     /**
273      * Sets the message for the request as a string.
274      *
275      * @param msg a string.
276      */

277     void setMessage(String JavaDoc msg);
278
279     /**
280      * Adds the string to message. If message has prior messages from
281      * other actions or screens, this method can be used to chain them.
282      *
283      * @param msg a string.
284      */

285     void addMessage(String JavaDoc msg);
286
287     /**
288      * Gets the results of an action or another message
289      * to be displayed as an ECS string element.
290      *
291      * @return a string element.
292      */

293     StringElement getMessageAsHTML();
294
295     /**
296      * Sets the message for the request as an ECS element.
297      *
298      * @param msg an element.
299      */

300     void setMessage(Element msg);
301
302     /**
303      * Adds the ECS element to message. If message has prior messages from
304      * other actions or screens, this method can be used to chain them.
305      *
306      * @param msg an element.
307      */

308     void addMessage(Element msg);
309
310     /**
311      * Unsets the message for the request.
312      */

313     void unsetMessage();
314
315     /**
316      * Gets a FormMessages object where all the messages to the
317      * user should be stored.
318      *
319      * @return a FormMessages.
320      */

321     FormMessages getMessages();
322
323     /**
324      * Sets the FormMessages object for the request.
325      *
326      * @param msgs A FormMessages.
327      */

328     void setMessages(FormMessages msgs);
329
330     /**
331      * Gets the title of the page.
332      *
333      * @return a string.
334      */

335     String JavaDoc getTitle();
336
337     /**
338      * Sets the title of the page.
339      *
340      * @param title a string.
341      */

342     void setTitle(String JavaDoc title);
343
344     /**
345      * Checks if a user exists in this session.
346      *
347      * @return true if a user exists in this session.
348      */

349     boolean userExists();
350
351     /**
352      * Gets the user.
353      *
354      * @return a user.
355      */

356     User getUser();
357
358     /**
359      * Sets the user.
360      *
361      * @param user a user.
362      */

363     void setUser(User user);
364
365     /**
366      * Attempts to get the user from the session. If it does
367      * not exist, it returns null.
368      *
369      * @return a user.
370      */

371     User getUserFromSession();
372
373     /**
374      * Allows one to invalidate the user in the default session.
375      *
376      * @return true if user was invalidated.
377      */

378     boolean removeUserFromSession();
379
380     /**
381      * Checks to see if out is set.
382      *
383      * @return true if out is set.
384      * @deprecated no replacement planned, response writer will not be cached
385      */

386     boolean isOutSet();
387
388     /**
389      * Gets the print writer. First time calling this
390      * will set the print writer via the response.
391      *
392      * @return a print writer.
393      * @throws IOException
394      * @deprecated no replacement planned, response writer will not be cached
395      */

396     PrintWriter JavaDoc getOut()
397             throws IOException JavaDoc;
398
399     /**
400      * Declares that output will be direct to the response stream,
401      * even though getOut() may never be called. Useful for response
402      * mechanisms that may call res.getWriter() themselves
403      * (such as JSP.)
404      */

405     void declareDirectResponse();
406
407     /**
408      * Gets the locale. If it has not already been defined with
409      * setLocale(), then properties named "locale.default.lang"
410      * and "locale.default.country" are checked from the Resource
411      * Service and the corresponding locale is returned. If these
412      * properties are undefined, JVM's default locale is returned.
413      *
414      * @return the locale.
415      */

416     Locale JavaDoc getLocale();
417
418     /**
419      * Sets the locale.
420      *
421      * @param locale the new locale.
422      */

423     void setLocale(Locale JavaDoc locale);
424
425     /**
426      * Gets the charset. If it has not already been defined with
427      * setCharSet(), then a property named "locale.default.charset"
428      * is checked from the Resource Service and returned. If this
429      * property is undefined, the default charset of the locale
430      * is returned. If the locale is undefined, null is returned.
431      *
432      * @return the name of the charset or null.
433      */

434     String JavaDoc getCharSet();
435
436     /**
437      * Sets the charset.
438      *
439      * @param charset the name of the new charset.
440      */

441     void setCharSet(String JavaDoc charset);
442
443     /**
444      * Gets the HTTP content type to return. If a charset
445      * has been specified, it is included in the content type.
446      * If the charset has not been specified and the main type
447      * of the content type is "text", the default charset is
448      * included. If the default charset is undefined, but the
449      * default locale is defined and it is not the US locale,
450      * a locale specific charset is included.
451      *
452      * @return the content type or an empty string.
453      */

454     String JavaDoc getContentType();
455
456     /**
457      * Sets the HTTP content type to return.
458      *
459      * @param ct the new content type.
460      */

461     void setContentType(String JavaDoc ct);
462
463     /**
464      * Gets the redirect URI. If this is set, also make sure to set
465      * the status code to 302.
466      *
467      * @return a string, "" if null.
468      */

469     String JavaDoc getRedirectURI();
470
471     /**
472      * Sets the redirect uri. If this is set, also make sure to set
473      * the status code to 302.
474      *
475      * @param ruri a string.
476      */

477     void setRedirectURI(String JavaDoc ruri);
478
479     /**
480      * Gets the HTTP status code to return.
481      *
482      * @return the status.
483      */

484     int getStatusCode();
485
486     /**
487      * Sets the HTTP status code to return.
488      *
489      * @param sc the status.
490      */

491     void setStatusCode(int sc);
492
493     /**
494      * Gets an array of system errors.
495      *
496      * @return a SystemError[].
497      */

498     SystemError[] getSystemErrors();
499
500     /**
501      * Adds a critical system error.
502      *
503      * @param err a system error.
504      */

505     void setSystemError(SystemError err);
506
507     /**
508      * Gets JNDI Contexts.
509      *
510      * @return a hashtable.
511      */

512     Map JavaDoc getJNDIContexts();
513
514     /**
515      * Sets JNDI Contexts.
516      *
517      * @param contexts a hashtable.
518      */

519     void setJNDIContexts(Map JavaDoc contexts);
520
521     /**
522      * Gets the cached server scheme.
523      *
524      * @return a string.
525      */

526     String JavaDoc getServerScheme();
527
528     /**
529      * Gets the cached server name.
530      *
531      * @return a string.
532      */

533     String JavaDoc getServerName();
534
535     /**
536      * Gets the cached server port.
537      *
538      * @return an int.
539      */

540     int getServerPort();
541
542     /**
543      * Gets the cached context path.
544      *
545      * @return a string.
546      */

547     String JavaDoc getContextPath();
548
549     /**
550      * Gets the cached script name.
551      *
552      * @return a string.
553      */

554     String JavaDoc getScriptName();
555
556     /**
557      * Gets the server data used by the request.
558      *
559      * @return server data.
560      */

561     ServerData getServerData();
562
563     /**
564      * Gets the IP address of the client that sent the request.
565      *
566      * @return a string.
567      */

568     String JavaDoc getRemoteAddr();
569
570     /**
571      * Gets the qualified name of the client that sent the request.
572      *
573      * @return a string.
574      */

575     String JavaDoc getRemoteHost();
576
577     /**
578      * Get the user agent for the request.
579      *
580      * @return a string.
581      */

582     String JavaDoc getUserAgent();
583
584     /**
585      * Pulls a user object from the session and increments the access
586      * counter and sets the last access date for the object.
587      */

588     void populate();
589
590     /**
591      * Saves a user object into the session.
592      */

593     void save();
594
595     /**
596      * Gets the stack trace if set.
597      *
598      * @return the stack trace.
599      */

600     String JavaDoc getStackTrace();
601
602     /**
603      * Gets the stack trace exception if set.
604      *
605      * @return the stack exception.
606      */

607     Throwable JavaDoc getStackTraceException();
608
609     /**
610      * Sets the stack trace.
611      *
612      * @param trace the stack trace.
613      * @param exp the exception.
614      */

615     void setStackTrace(String JavaDoc trace,
616                        Throwable JavaDoc 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 JavaDoc 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 JavaDoc name, Object JavaDoc value);
635
636     /**
637      * Gets a Map of debug variables.
638      *
639      * @return a Map of debug variables.
640      */

641     Map JavaDoc getDebugVariables();
642 }
643
Popular Tags