    001// Copyright 2006, 2007, 2008, 2011, 2012 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.Map;
    018
    019/**
    020 * An object which manages a list of {@link org.apache.tapestry5.services.InvalidationListener}s. There are multiple
    021 * event hub services implementing this interface, each with a specific marker annotation; each can register listeners
    022 * and fire events; these are based on the type of resource that has been invalidated. Tapestry has built-in support
    023 * for:
    024 * <dl>
    025 * <dt>message catalog resources
    026 * <dd>{@link org.apache.tapestry5.services.ComponentMessages} marker annotation
    027 * <dt>component templates
    028 * <dd>{@link org.apache.tapestry5.services.ComponentTemplates} marker annotation
    029 * <dt>component classes
    030 * <dd>{@link org.apache.tapestry5.services.ComponentClasses} marker annotation
    031 * </dl>
    032 * <p/>
    033 * Starting in Tapestry 5.3, these services are disabled in production (it does nothing).
    034 *
    035 * @since 5.1.0.0
    036 */
    037public interface InvalidationEventHub
    038{
    039    /**
    040     * Adds a listener, who needs to know when an underlying resource of a given category has changed (so that the
    041     * receiver may discard any cached data that may have been invalidated). Does nothing in production mode.
    042     *
    043     * @deprecated in 5.4, use {@link #addInvalidationCallback(Runnable)} instead}
    044     */
    045    void addInvalidationListener(InvalidationListener listener);
    046
    047    /**
    048     * Adds a callback that is invoked when an underlying tracked resource has changed. Does nothing in production mode.
    049     *
    050     * @since  5.4
    051     */
    052    void addInvalidationCallback(Runnable callback);
    053
    054    /**
    055     * Adds a callback that clears the map.
    056     *
    057     * @since 5.4
    058     */
    059    void clearOnInvalidation(Map<?,?> map);
    060}