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.commons.io.monitor;
018
019import java.io.File;
020import java.io.FileFilter;
021import java.io.Serializable;
022import java.util.Arrays;
023import java.util.Comparator;
024import java.util.List;
025import java.util.concurrent.CopyOnWriteArrayList;
026
027import org.apache.commons.io.FileUtils;
028import org.apache.commons.io.IOCase;
029import org.apache.commons.io.comparator.NameFileComparator;
030
031/**
032 * FileAlterationObserver represents the state of files below a root directory,
033 * checking the file system and notifying listeners of create, change or
034 * delete events.
035 * <p>
036 * To use this implementation:
037 * <ul>
038 *   <li>Create {@link FileAlterationListener} implementation(s) that process
039 *      the file/directory create, change and delete events</li>
040 *   <li>Register the listener(s) with a {@link FileAlterationObserver} for
041 *       the appropriate directory.</li>
042 *   <li>Either register the observer(s) with a {@link FileAlterationMonitor} or
043 *       run manually.</li>
044 * </ul>
045 *
046 * <h2>Basic Usage</h2>
047 * Create a {@link FileAlterationObserver} for the directory and register the listeners:
048 * <pre>
049 *      File directory = new File(new File("."), "src");
050 *      FileAlterationObserver observer = new FileAlterationObserver(directory);
051 *      observer.addListener(...);
052 *      observer.addListener(...);
053 * </pre>
054 * To manually observe a directory, initialize the observer and invoked the
055 * {@link #checkAndNotify()} method as required:
056 * <pre>
057 *      // initialize
058 *      observer.init();
059 *      ...
060 *      // invoke as required
061 *      observer.checkAndNotify();
062 *      ...
063 *      observer.checkAndNotify();
064 *      ...
065 *      // finished
066 *      observer.finish();
067 * </pre>
068 * Alternatively, register the observer(s) with a {@link FileAlterationMonitor},
069 * which creates a new thread, invoking the observer at the specified interval:
070 * <pre>
071 *      long interval = ...
072 *      FileAlterationMonitor monitor = new FileAlterationMonitor(interval);
073 *      monitor.addObserver(observer);
074 *      monitor.start();
075 *      ...
076 *      monitor.stop();
077 * </pre>
078 *
079 * <h2>File Filters</h2>
080 * This implementation can monitor portions of the file system
081 * by using {@link FileFilter}s to observe only the files and/or directories
082 * that are of interest. This makes it more efficient and reduces the
083 * noise from <i>unwanted</i> file system events.
084 * <p>
085 * <a href="https://commons.apache.org/io/">Commons IO</a> has a good range of
086 * useful, ready made
087 * <a href="../filefilter/package-summary.html">File Filter</a>
088 * implementations for this purpose.
089 * <p>
090 * For example, to only observe 1) visible directories and 2) files with a ".java" suffix
091 * in a root directory called "src" you could set up a {@link FileAlterationObserver} in the following
092 * way:
093 * <pre>
094 *      // Create a FileFilter
095 *      IOFileFilter directories = FileFilterUtils.and(
096 *                                      FileFilterUtils.directoryFileFilter(),
097 *                                      HiddenFileFilter.VISIBLE);
098 *      IOFileFilter files       = FileFilterUtils.and(
099 *                                      FileFilterUtils.fileFileFilter(),
100 *                                      FileFilterUtils.suffixFileFilter(".java"));
101 *      IOFileFilter filter = FileFilterUtils.or(directories, files);
102 *
103 *      // Create the File system observer and register File Listeners
104 *      FileAlterationObserver observer = new FileAlterationObserver(new File("src"), filter);
105 *      observer.addListener(...);
106 *      observer.addListener(...);
107 * </pre>
108 *
109 * <h2>FileEntry</h2>
110 * {@link FileEntry} represents the state of a file or directory, capturing
111 * {@link File} attributes at a point in time. Custom implementations of
112 * {@link FileEntry} can be used to capture additional properties that the
113 * basic implementation does not support. The {@link FileEntry#refresh(File)}
114 * method is used to determine if a file or directory has changed since the last
115 * check and stores the current state of the {@link File}'s properties.
116 *
117 * @see FileAlterationListener
118 * @see FileAlterationMonitor
119 *
120 * @since 2.0
121 */
122public class FileAlterationObserver implements Serializable {
123
124    private static final long serialVersionUID = 1185122225658782848L;
125    private final List<FileAlterationListener> listeners = new CopyOnWriteArrayList<>();
126    private final FileEntry rootEntry;
127    private final FileFilter fileFilter;
128    private final Comparator<File> comparator;
129
130    /**
131     * Constructs an observer for the specified directory.
132     *
133     * @param directoryName the name of the directory to observe
134     */
135    public FileAlterationObserver(final String directoryName) {
136        this(new File(directoryName));
137    }
138
139    /**
140     * Constructs an observer for the specified directory and file filter.
141     *
142     * @param directoryName the name of the directory to observe
143     * @param fileFilter The file filter or null if none
144     */
145    public FileAlterationObserver(final String directoryName, final FileFilter fileFilter) {
146        this(new File(directoryName), fileFilter);
147    }
148
149    /**
150     * Construct an observer for the specified directory, file filter and
151     * file comparator.
152     *
153     * @param directoryName the name of the directory to observe
154     * @param fileFilter The file filter or null if none
155     * @param caseSensitivity  what case sensitivity to use comparing file names, null means system sensitive
156     */
157    public FileAlterationObserver(final String directoryName, final FileFilter fileFilter,
158                                  final IOCase caseSensitivity) {
159        this(new File(directoryName), fileFilter, caseSensitivity);
160    }
161
162    /**
163     * Constructs an observer for the specified directory.
164     *
165     * @param directory the directory to observe
166     */
167    public FileAlterationObserver(final File directory) {
168        this(directory, null);
169    }
170
171    /**
172     * Constructs an observer for the specified directory and file filter.
173     *
174     * @param directory the directory to observe
175     * @param fileFilter The file filter or null if none
176     */
177    public FileAlterationObserver(final File directory, final FileFilter fileFilter) {
178        this(directory, fileFilter, null);
179    }
180
181    /**
182     * Constructs an observer for the specified directory, file filter and
183     * file comparator.
184     *
185     * @param directory the directory to observe
186     * @param fileFilter The file filter or null if none
187     * @param caseSensitivity  what case sensitivity to use comparing file names, null means system sensitive
188     */
189    public FileAlterationObserver(final File directory, final FileFilter fileFilter, final IOCase caseSensitivity) {
190        this(new FileEntry(directory), fileFilter, caseSensitivity);
191    }
192
193    /**
194     * Constructs an observer for the specified directory, file filter and
195     * file comparator.
196     *
197     * @param rootEntry the root directory to observe
198     * @param fileFilter The file filter or null if none
199     * @param caseSensitivity  what case sensitivity to use comparing file names, null means system sensitive
200     */
201    protected FileAlterationObserver(final FileEntry rootEntry, final FileFilter fileFilter,
202                                     final IOCase caseSensitivity) {
203        if (rootEntry == null) {
204            throw new IllegalArgumentException("Root entry is missing");
205        }
206        if (rootEntry.getFile() == null) {
207            throw new IllegalArgumentException("Root directory is missing");
208        }
209        this.rootEntry = rootEntry;
210        this.fileFilter = fileFilter;
211        if (caseSensitivity == null || caseSensitivity.equals(IOCase.SYSTEM)) {
212            this.comparator = NameFileComparator.NAME_SYSTEM_COMPARATOR;
213        } else if (caseSensitivity.equals(IOCase.INSENSITIVE)) {
214            this.comparator = NameFileComparator.NAME_INSENSITIVE_COMPARATOR;
215        } else {
216            this.comparator = NameFileComparator.NAME_COMPARATOR;
217        }
218    }
219
220    /**
221     * Returns the directory being observed.
222     *
223     * @return the directory being observed
224     */
225    public File getDirectory() {
226        return rootEntry.getFile();
227    }
228
229    /**
230     * Returns the fileFilter.
231     *
232     * @return the fileFilter
233     * @since 2.1
234     */
235    public FileFilter getFileFilter() {
236        return fileFilter;
237    }
238
239    /**
240     * Adds a file system listener.
241     *
242     * @param listener The file system listener
243     */
244    public void addListener(final FileAlterationListener listener) {
245        if (listener != null) {
246            listeners.add(listener);
247        }
248    }
249
250    /**
251     * Removes a file system listener.
252     *
253     * @param listener The file system listener
254     */
255    public void removeListener(final FileAlterationListener listener) {
256        if (listener != null) {
257            while (listeners.remove(listener)) {
258                // empty
259            }
260        }
261    }
262
263    /**
264     * Returns the set of registered file system listeners.
265     *
266     * @return The file system listeners
267     */
268    public Iterable<FileAlterationListener> getListeners() {
269        return listeners;
270    }
271
272    /**
273     * Initializes the observer.
274     *
275     * @throws Exception if an error occurs
276     */
277    public void initialize() throws Exception {
278        rootEntry.refresh(rootEntry.getFile());
279        final FileEntry[] children = doListFiles(rootEntry.getFile(), rootEntry);
280        rootEntry.setChildren(children);
281    }
282
283    /**
284     * Final processing.
285     *
286     * @throws Exception if an error occurs
287     */
288    public void destroy() throws Exception {
289        // noop
290    }
291
292    /**
293     * Checks whether the file and its children have been created, modified or deleted.
294     */
295    public void checkAndNotify() {
296
297        /* fire onStart() */
298        for (final FileAlterationListener listener : listeners) {
299            listener.onStart(this);
300        }
301
302        /* fire directory/file events */
303        final File rootFile = rootEntry.getFile();
304        if (rootFile.exists()) {
305            checkAndNotify(rootEntry, rootEntry.getChildren(), listFiles(rootFile));
306        } else if (rootEntry.isExists()) {
307            checkAndNotify(rootEntry, rootEntry.getChildren(), FileUtils.EMPTY_FILE_ARRAY);
308        } else {
309            // Didn't exist and still doesn't
310        }
311
312        /* fire onStop() */
313        for (final FileAlterationListener listener : listeners) {
314            listener.onStop(this);
315        }
316    }
317
318    /**
319     * Compares two file lists for files which have been created, modified or deleted.
320     *
321     * @param parent The parent entry
322     * @param previous The original list of files
323     * @param files  The current list of files
324     */
325    private void checkAndNotify(final FileEntry parent, final FileEntry[] previous, final File[] files) {
326        int c = 0;
327        final FileEntry[] current = files.length > 0 ? new FileEntry[files.length] : FileEntry.EMPTY_ENTRIES;
328        for (final FileEntry entry : previous) {
329            while (c < files.length && comparator.compare(entry.getFile(), files[c]) > 0) {
330                current[c] = createFileEntry(parent, files[c]);
331                doCreate(current[c]);
332                c++;
333            }
334            if (c < files.length && comparator.compare(entry.getFile(), files[c]) == 0) {
335                doMatch(entry, files[c]);
336                checkAndNotify(entry, entry.getChildren(), listFiles(files[c]));
337                current[c] = entry;
338                c++;
339            } else {
340                checkAndNotify(entry, entry.getChildren(), FileUtils.EMPTY_FILE_ARRAY);
341                doDelete(entry);
342            }
343        }
344        for (; c < files.length; c++) {
345            current[c] = createFileEntry(parent, files[c]);
346            doCreate(current[c]);
347        }
348        parent.setChildren(current);
349    }
350
351    /**
352     * Creates a new file entry for the specified file.
353     *
354     * @param parent The parent file entry
355     * @param file The file to create an entry for
356     * @return A new file entry
357     */
358    private FileEntry createFileEntry(final FileEntry parent, final File file) {
359        final FileEntry entry = parent.newChildInstance(file);
360        entry.refresh(file);
361        final FileEntry[] children = doListFiles(file, entry);
362        entry.setChildren(children);
363        return entry;
364    }
365
366    /**
367     * Lists the files
368     * @param file The file to list files for
369     * @param entry the parent entry
370     * @return The child files
371     */
372    private FileEntry[] doListFiles(final File file, final FileEntry entry) {
373        final File[] files = listFiles(file);
374        final FileEntry[] children = files.length > 0 ? new FileEntry[files.length] : FileEntry.EMPTY_ENTRIES;
375        for (int i = 0; i < files.length; i++) {
376            children[i] = createFileEntry(entry, files[i]);
377        }
378        return children;
379    }
380
381    /**
382     * Fires directory/file created events to the registered listeners.
383     *
384     * @param entry The file entry
385     */
386    private void doCreate(final FileEntry entry) {
387        for (final FileAlterationListener listener : listeners) {
388            if (entry.isDirectory()) {
389                listener.onDirectoryCreate(entry.getFile());
390            } else {
391                listener.onFileCreate(entry.getFile());
392            }
393        }
394        final FileEntry[] children = entry.getChildren();
395        for (final FileEntry aChildren : children) {
396            doCreate(aChildren);
397        }
398    }
399
400    /**
401     * Fires directory/file change events to the registered listeners.
402     *
403     * @param entry The previous file system entry
404     * @param file The current file
405     */
406    private void doMatch(final FileEntry entry, final File file) {
407        if (entry.refresh(file)) {
408            for (final FileAlterationListener listener : listeners) {
409                if (entry.isDirectory()) {
410                    listener.onDirectoryChange(file);
411                } else {
412                    listener.onFileChange(file);
413                }
414            }
415        }
416    }
417
418    /**
419     * Fires directory/file delete events to the registered listeners.
420     *
421     * @param entry The file entry
422     */
423    private void doDelete(final FileEntry entry) {
424        for (final FileAlterationListener listener : listeners) {
425            if (entry.isDirectory()) {
426                listener.onDirectoryDelete(entry.getFile());
427            } else {
428                listener.onFileDelete(entry.getFile());
429            }
430        }
431    }
432
433    /**
434     * Lists the contents of a directory
435     *
436     * @param file The file to list the contents of
437     * @return the directory contents or a zero length array if
438     * the empty or the file is not a directory
439     */
440    private File[] listFiles(final File file) {
441        File[] children = null;
442        if (file.isDirectory()) {
443            children = fileFilter == null ? file.listFiles() : file.listFiles(fileFilter);
444        }
445        if (children == null) {
446            children = FileUtils.EMPTY_FILE_ARRAY;
447        }
448        if (comparator != null && children.length > 1) {
449            Arrays.sort(children, comparator);
450        }
451        return children;
452    }
453
454    /**
455     * Returns a String representation of this observer.
456     *
457     * @return a String representation of this observer
458     */
459    @Override
460    public String toString() {
461        final StringBuilder builder = new StringBuilder();
462        builder.append(getClass().getSimpleName());
463        builder.append("[file='");
464        builder.append(getDirectory().getPath());
465        builder.append('\'');
466        if (fileFilter != null) {
467            builder.append(", ");
468            builder.append(fileFilter.toString());
469        }
470        builder.append(", listeners=");
471        builder.append(listeners.size());
472        builder.append("]");
473        return builder.toString();
474    }
475
476}