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}