001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 *
009 *      http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017package org.apache.wicket.util.watch;
018
019import java.util.Set;
020
021import org.apache.wicket.util.listener.IChangeListener;
022import java.time.Duration;
023
024
025/**
026 * Monitors one or more <code>IModifiable</code> objects, calling a {@link IChangeListener
027 * IChangeListener} when a given object's modification time changes.
028 * 
029 * @author Juergen Donnerstag
030 */
031public interface IModificationWatcher
032{
033        /**
034         * Adds an <code>IModifiable</code> object and an <code>IChangeListener</code> object to call
035         * when the modifiable object is modified.
036         * 
037         * @param modifiable
038         *            an <code>IModifiable</code> object to monitor
039         * @param listener
040         *            an <code>IChangeListener</code> to call if the <code>IModifiable</code> object is
041         *            modified
042         * @return <code>true</code> if the set did not already contain the specified element
043         */
044        boolean add(final IModifiable modifiable, final IChangeListener<IModifiable> listener);
045
046        /**
047         * Removes all entries associated with an <code>IModifiable</code> object.
048         * 
049         * @param modifiable
050         *            an <code>IModifiable</code> object
051         * @return the <code>IModifiable</code> object that was removed, else <code>null</code>
052         */
053        IModifiable remove(final IModifiable modifiable);
054
055        /**
056         * Starts watching at a given <code>Duration</code> polling rate.
057         * 
058         * @param pollFrequency
059         *            the polling rate <code>Duration</code>
060         */
061        void start(final Duration pollFrequency);
062
063        /**
064         * Stops this <code>ModificationWatcher</code>.
065         */
066        void destroy();
067
068        /**
069         * Retrieves a key set of all <code>IModifiable</code> objects currently being monitored.
070         * 
071         * @return a <code>Set</code> of all <code>IModifiable</code> entries currently maintained
072         */
073        Set<IModifiable> getEntries();
074}