    001// Copyright 2006-2014 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
    015package org.apache.tapestry5.services;
    016
    017import 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 */
    030public 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     * Hides all current environment values, making the Environment object appear empty, until
    073     * a call to {@link #decloak()}} restores the original state.
    074     *
    075     * @since 5.3
    076     * @deprecated Deprecated in 5.4 with no replacement; not longer used by Tapestry.
    077     * @see org.apache.tapestry5.TapestryConstants#RESPONSE_RENDERER
    078     */
    079    void cloak();
    080
    081    /**
    082     * Restores state previously hidden by {@link #cloak()}}.
    083     *
    084     * @since 5.3
    085     * @deprecated Deprecated in 5.4 with no replacement; not longer used by Tapestry.
    086     * @see org.apache.tapestry5.TapestryConstants#RESPONSE_RENDERER
    087     */
    088    void decloak();
    089}