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