    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    }