001package 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
024import java.io.IOException;
025import java.io.PrintWriter;
026import java.util.Locale;
027import java.util.Map;
028
029import javax.naming.Context;
030import javax.servlet.ServletConfig;
031import javax.servlet.ServletContext;
032import javax.servlet.http.HttpServletRequest;
033import javax.servlet.http.HttpServletResponse;
034import javax.servlet.http.HttpSession;
035
036import org.apache.fulcrum.parser.CookieParser;
037import org.apache.fulcrum.parser.ParameterParser;
038import org.apache.fulcrum.security.acl.AccessControlList;
039import org.apache.turbine.om.security.User;
040import org.apache.turbine.pipeline.PipelineData;
041import org.apache.turbine.util.template.TemplateInfo;
042
043/**
044 * RunData is an interface to run-time information that is passed
045 * within Turbine. This provides the threading mechanism for the
046 * entire system because multiple requests can potentially come in
047 * at the same time.  Thus, there is only one RunData instance
048 * for each request that is being serviced.
049 *
050 * @author <a href="mailto:ilkka.priha@simsoft.fi">Ilkka Priha</a>
051 * @author <a href="mailto:jon@clearink.com">Jon S. Stevens</a>
052 * @author <a href="mailto:bhoeneis@ee.ethz.ch">Bernie Hoeneisen</a>
053 * @author <a href="mailto:dlr@finemaltcoding.com">Daniel Rall</a>
054 * @author <a href="mailto:quintonm@bellsouth.net">Quinton McCombs</a>
055 * @version $Id: RunData.java 1792901 2017-04-27 14:08:57Z gk $
056 */
057public interface RunData extends PipelineData
058{
059    /**
060     * Gets the parameters.
061     *
062     * @return a parameter parser.
063     */
064    ParameterParser getParameters();
065
066    /**
067     * Gets the cookies.
068     *
069     * @return a cookie parser.
070     */
071    CookieParser getCookies();
072
073    /**
074     * Gets the servlet request.
075     *
076     * @return the request.
077     */
078    HttpServletRequest getRequest();
079
080    /**
081     * Gets the servlet response.
082     *
083     * @return the resposne.
084     */
085    HttpServletResponse getResponse();
086
087    /**
088     * Gets the servlet session information.
089     *
090     * @return the session.
091     */
092    HttpSession getSession();
093
094    /**
095     * Gets the servlet configuration used during servlet init.
096     *
097     * @return the configuration.
098     */
099    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}