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