    001    // Copyright 2006, 2008, 2011 The Apache Software Foundation
    002    //
    003    // Licensed under the Apache License, Version 2.0 (the "License");
    004    // you may not use this file except in compliance with the License.
    005    // You may obtain a copy of the License at
    006    //
    007    //     http://www.apache.org/licenses/LICENSE-2.0
    008    //
    009    // Unless required by applicable law or agreed to in writing, software
    010    // distributed under the License is distributed on an "AS IS" BASIS,
    011    // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    012    // See the License for the specific language governing permissions and
    013    // limitations under the License.
    014
    015    package org.apache.tapestry5.services;
    016
    017    import java.util.NoSuchElementException;
    018
    019    /**
    020     * Provides access to environment objects, which are almost always provided to enclosed components by enclosing
    021     * components. Environmental services are a form of very late binding.
    022     * <p/>
    023     * The Environment acts like a collection of stacks. Each stack contains environmental objects of a given type. Most
    024     * often, a stack has zero or one elements, but on occasion, a particular component will push an override onto the stack
    025     * for the benefit of the components it encloses.
    026     *
    027     * @see org.apache.tapestry5.annotations.Environmental
    028     * @see org.apache.tapestry5.services.EnvironmentalShadowBuilder
    029     */
    030    public interface Environment
    031    {
    032        /**
    033         * Peeks at the current top of the indicated stack.
    034         *
    035         * @param <T>  the type of environmental object
    036         * @param type class used to select the object
    037         * @return the current object of that type, or null if no service of that type has been added
    038         */
    039        <T> T peek(Class<T> type);
    040
    041        /**
    042         * Peeks at the current top of the indicated stack (which must have a non-null value).
    043         *
    044         * @param <T>  the type of environmental object
    045         * @param type class used to select the object
    046         * @return the current object of the specified type
    047         * @throws RuntimeException if no service of that type has been added
    048         */
    049        <T> T peekRequired(Class<T> type);
    050
    051        /**
    052         * Removes and returns the top environmental object of the selected type.
    053         *
    054         * @param <T>  the type of environmental object
    055         * @param type class used to select the object
    056         * @return the object just removed
    057         * @throws NoSuchElementException if the environmental stack (for the specified type) is empty
    058         */
    059        <T> T pop(Class<T> type);
    060
    061        /**
    062         * Pushes a new service onto the stack. The old service at the top of the stack is returned (it may be null).
    063         *
    064         * @param <T>      the type of environmental object
    065         * @param type     class used to select the object
    066         * @param instance the service object
    067         * @return the previous top service
    068         */
    069        <T> T push(Class<T> type, T instance);
    070
    071        /**
    072         * Clears all stacks; no longer used by Tapestry.
    073         *
    074         * @deprecated Deprecated in 5.3 with no replacement.
    075         */
    076        void clear();
    077
    078        /**
    079         * Hides all current environment values, making the Environment object appear empty, until
    080         * a call to {@link #decloak()}} restores the original state.
    081         *
    082         * @since 5.3
    083         */
    084        void cloak();
    085
    086        /**
    087         * Restores state previously hidden by {@link #cloak()}}.
    088         *
    089         * @since 5.3
    090         */
    091        void decloak();
    092    }