    001    package org.apache.turbine.services.pull;
    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 org.apache.turbine.pipeline.PipelineData;
    025    import org.apache.turbine.services.Service;
    026    import org.apache.turbine.util.RunData;
    027    import org.apache.velocity.context.Context;
    028
    029    /**
    030     * The Pull Service manages the creation of application
    031     * tools that are available to all templates in a
    032     * Turbine application. By using the Pull Service you
    033     * can avoid having to make Screens to populate a
    034     * context for use in a particular template. The Pull
    035     * Service creates a set of tools, as specified in
    036     * the TR.props file.
    037     *
    038     * These tools can have global scope, request scope,
    039     * authorized or session scope (i.e. stored in user temp hashmap)
    040     * or persistent scope (i.e. stored in user perm hashmap)
    041     *
    042     * The standard way of referencing these global
    043     * tools is through the toolbox handle. This handle
    044     * is typically $toolbox, but can be specified in the
    045     * TR.props file.
    046     *
    047     * So, for example, if you had a UI Manager tool
    048     * which created a set of UI attributes from a
    049     * properties file, and one of the properties
    050     * was 'bgcolor', then you could access this
    051     * UI attribute with $ui.bgcolor. The identifier
    052     * that is given to the tool, in this case 'ui', can
    053     * be specified as well.
    054     *
    055     * @author <a href="mailto:jvanzyl@periapt.com">Jason van Zyl</a>
    056     * @author <a href="mailto:hps@intermeta.de">Henning P. Schmiedehausen</a>
    057     * @author <a href="mailto:peter@courcoux.biz">Peter Courcoux</a>
    058     * @version $Id: PullService.java 957284 2010-06-23 17:53:31Z tv $
    059     */
    060    public interface PullService
    061            extends Service
    062    {
    063        /** The key under which this service is stored in TurbineServices. */
    064        String SERVICE_NAME = "PullService";
    065
    066        /** Property Key for the global tools */
    067        String GLOBAL_TOOL = "tool.global";
    068
    069        /** Property Key for the request tools */
    070        String REQUEST_TOOL = "tool.request";
    071
    072        /** Property Key for the session tools */
    073        String SESSION_TOOL = "tool.session";
    074
    075        /** Property Key for the authorized tools */
    076        String AUTHORIZED_TOOL = "tool.authorized";
    077
    078        /** Property Key for the persistent tools */
    079        String PERSISTENT_TOOL = "tool.persistent";
    080
    081        /** Property tag for application tool resources directory */
    082        String TOOL_RESOURCES_DIR_KEY = "tools.resources.dir";
    083
    084        /**
    085         * Default value for the application tool resources. This is relative
    086         * to the webapp root
    087         */
    088        String TOOL_RESOURCES_DIR_DEFAULT = "resources";
    089
    090        /**
    091         * Property tag for per request tool refreshing (for obvious reasons
    092         * has no effect for per-request tools)
    093         */
    094        String TOOLS_PER_REQUEST_REFRESH_KEY = "tools.per.request.refresh";
    095
    096        /** Default value for per request tool refreshing */
    097        boolean TOOLS_PER_REQUEST_REFRESH_DEFAULT = false;
    098
    099        /** prefix for key used in the session to store session scope pull tools */
    100        String SESSION_TOOLS_ATTRIBUTE_PREFIX = "turbine.sessiontools.";
    101
    102        /**
    103         * Get the context containing global tools that will be
    104         * use as part of the Turbine Pull Model.
    105         *
    106         * @return A Context object which contains the
    107         *         Global Tool instances.
    108         */
    109        Context getGlobalContext();
    110
    111        /**
    112         * Populate the given context with all request, session, authorized
    113         * and persistent scope tools (it is assumed that the context
    114         * already wraps the global context, and thus already contains
    115         * the global tools).
    116         *
    117         * @param context a Velocity Context to populate
    118         * @param data a RunData object for request specific data
    119         */
    120         void populateContext(Context context, PipelineData pipelineData);
    121
    122         /**
    123          * Populate the given context with all request, session, authorized
    124          * and persistent scope tools (it is assumed that the context
    125          * already wraps the global context, and thus already contains
    126          * the global tools).
    127          *
    128          * @param context a Velocity Context to populate
    129          * @param data a RunData object for request specific data
    130          */
    131          void populateContext(Context context, RunData data);
    132
    133        /**
    134         * Return the absolute path of the resources directory
    135         * used by application tools.
    136         *
    137         * @return A directory path in the file system or null.
    138         */
    139        String getAbsolutePathToResourcesDirectory();
    140
    141        /**
    142         * Return the resources directory. This is relative
    143         * to the webapp context.
    144         *
    145         * @return A directory path to the resources directory relative to the webapp root or null.
    146         */
    147        String getResourcesDirectory();
    148
    149        /**
    150         * Release tool instances from the given context to the
    151         * object pool
    152         *
    153         * @param context a Velocity Context to release tools from
    154         */
    155        void releaseTools(Context context);
    156    }