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  ;
20  import java.io.PrintWriter  ;
21  import java.util.Locale  ;
22  import java.util.Map  ;
23  import javax.servlet.ServletConfig  ;
24  import javax.servlet.ServletContext  ;
25  import javax.servlet.http.HttpServletRequest  ;
26  import javax.servlet.http.HttpServletResponse  ;
27  import javax.servlet.http.HttpSession  ;
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   getRequest();
75  
76      /**
77       * Gets the servlet response.
78       *
79       * @return the resposne.
80       */
81      HttpServletResponse   getResponse();
82  
83      /**
84       * Gets the servlet session information.
85       *
86       * @return the session.
87       */
88      HttpSession   getSession();
89  
90      /**
91       * Gets the servlet configuration used during servlet init.
92       *
93       * @return the configuration.
94       */
95      ServletConfig   getServletConfig();
96  
97      /**
98       * Gets the servlet context used during servlet init.
99       *
100      * @return the context.
101      */
102     ServletContext   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   getAction();
149 
150     /**
151      * Sets the action for the request.
152      *
153      * @param action a atring.
154      */
155     void setAction(String   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   getLayout();
170 
171     /**
172      * Set the layout for the request.
173      *
174      * @param layout a string.
175      */
176     void setLayout(String   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   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   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   getScreen();
210 
211     /**
212      * Sets the screen for the request.
213      *
214      * @param screen a string.
215      */
216     void setScreen(String   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   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   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   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   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   getMessage();
271 
272     /**
273      * Sets the message for the request as a string.
274      *
275      * @param msg a string.
276      */
277     void setMessage(String   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   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   getTitle();
336 
337     /**
338      * Sets the title of the page.
339      *
340      * @param title a string.
341      */
342     void setTitle(String   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   getOut()
397             throws IOException  ;
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   getLocale();
417 
418     /**
419      * Sets the locale.
420      *
421      * @param locale the new locale.
422      */
423     void setLocale(Locale   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   getCharSet();
435 
436     /**
437      * Sets the charset.
438      *
439      * @param charset the name of the new charset.
440      */
441     void setCharSet(String   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   getContentType();
455 
456     /**
457      * Sets the HTTP content type to return.
458      *
459      * @param ct the new content type.
460      */
461     void setContentType(String   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   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   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   getJNDIContexts();
513 
514     /**
515      * Sets JNDI Contexts.
516      *
517      * @param contexts a hashtable.
518      */
519     void setJNDIContexts(Map   contexts);
520 
521     /**
522      * Gets the cached server scheme.
523      *
524      * @return a string.
525      */
526     String   getServerScheme();
527 
528     /**
529      * Gets the cached server name.
530      *
531      * @return a string.
532      */
533     String   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   getContextPath();
548 
549     /**
550      * Gets the cached script name.
551      *
552      * @return a string.
553      */
554     String   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   getRemoteAddr();
569 
570     /**
571      * Gets the qualified name of the client that sent the request.
572      *
573      * @return a string.
574      */
575     String   getRemoteHost();
576 
577     /**
578      * Get the user agent for the request.
579      *
580      * @return a string.
581      */
582     String   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   getStackTrace();
601 
602     /**
603      * Gets the stack trace exception if set.
604      *
605      * @return the stack exception.
606      */
607     Throwable   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   trace,
616                        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 }
643
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags