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    }