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     */
017    package org.apache.commons.io.monitor;
018    
019    import java.io.File;
020    import java.io.Serializable;
021    
022    /**
023     * {@link FileEntry} represents the state of a file or directory, capturing
024     * the following {@link File} attributes at a point in time.
025     * <ul>
026     *   <li>File Name (see {@link File#getName()})</li>
027     *   <li>Exists - whether the file exists or not (see {@link File#exists()})</li>
028     *   <li>Directory - whether the file is a directory or not (see {@link File#isDirectory()})</li>
029     *   <li>Last Modified Date/Time (see {@link File#lastModified()})</li>
030     *   <li>Length (see {@link File#length()}) - directories treated as zero</li>
031     *   <li>Children - contents of a directory (see {@link File#listFiles(java.io.FileFilter)})</li>
032     * </ul>
033     * <p>
034     * <h3>Custom Implementations</h3>
035     * If the state of additional {@link File} attributes is required then create a custom
036     * {@link FileEntry} with properties for those attributes. Override the
037     * {@link #newChildInstance(File)} to return a new instance of the appropriate type.
038     * You may also want to override the {@link #refresh(File)} method.
039     * @see FileAlterationObserver
040     * @since 2.0
041     */
042    public class FileEntry implements Serializable {
043    
044        static final FileEntry[] EMPTY_ENTRIES = new FileEntry[0];
045    
046        private final FileEntry parent;
047        private FileEntry[] children;
048        private final File file;
049        private String name;
050        private boolean exists;
051        private boolean directory;
052        private long lastModified;
053        private long length;
054    
055        /**
056         * Construct a new monitor for a specified {@link File}.
057         *
058         * @param file The file being monitored
059         */
060        public FileEntry(File file) {
061            this((FileEntry)null, file);
062        }
063    
064        /**
065         * Construct a new monitor for a specified {@link File}.
066         *
067         * @param parent The parent
068         * @param file The file being monitored
069         */
070        public FileEntry(FileEntry parent, File file) {
071            if (file == null) {
072                throw new IllegalArgumentException("File is missing");
073            }
074            this.file = file;
075            this.parent = parent;
076            this.name = file.getName();
077        }
078    
079        /**
080         * Refresh the attributes from the {@link File}, indicating
081         * whether the file has changed.
082         * <p>
083         * This implementation refreshes the <code>name</code>, <code>exists</code>,
084         * <code>directory</code>, <code>lastModified</code> and <code>length</code>
085         * properties.
086         * <p>
087         * The <code>exists</code>, <code>directory</code>, <code>lastModified</code>
088         * and <code>length</code> properties are compared for changes
089         *
090         * @param file the file instance to compare to
091         * @return <code>true</code> if the file has changed, otherwise <code>false</code>
092         */
093        public boolean refresh(File file) {
094    
095            // cache original values
096            boolean origExists       = exists;
097            long    origLastModified = lastModified;
098            boolean origDirectory    = directory;
099            long    origLength       = length;
100    
101            // refresh the values
102            name         = file.getName();
103            exists       = file.exists();
104            directory    = exists ? file.isDirectory() : false;
105            lastModified = exists ? file.lastModified() : 0;
106            length       = exists && !directory ? file.length() : 0;
107    
108            // Return if there are changes
109            return exists != origExists ||
110                    lastModified != origLastModified ||
111                    directory != origDirectory ||
112                    length != origLength;
113        }
114    
115        /**
116         * Create a new child instance.
117         * <p>
118         * Custom implementations should override this method to return
119         * a new instance of the appropriate type.
120         *
121         * @param file The child file
122         * @return a new child instance
123         */
124        public FileEntry newChildInstance(File file) {
125            return new FileEntry(this, file);
126        }
127    
128        /**
129         * Return the parent entry.
130         *
131         * @return the parent entry
132         */
133        public FileEntry getParent() {
134            return parent;
135        }
136    
137        /**
138         * Return the level
139         *
140         * @return the level
141         */
142        public int getLevel() {
143            return parent == null ? 0 : parent.getLevel() + 1;
144        }
145    
146        /**
147         * Return the directory's files.
148         *
149         * @return This directory's files or an empty
150         * array if the file is not a directory or the
151         * directory is empty
152         */
153        public FileEntry[] getChildren() {
154            return children != null ? children : EMPTY_ENTRIES;
155        }
156    
157        /**
158         * Set the directory's files.
159         *
160         * @param children This directory's files, may be null
161         */
162        public void setChildren(FileEntry[] children) {
163            this.children = children;
164        }
165    
166        /**
167         * Return the file being monitored.
168         *
169         * @return the file being monitored
170         */
171        public File getFile() {
172            return file;
173        }
174    
175        /**
176         * Return the file name.
177         *
178         * @return the file name
179         */
180        public String getName() {
181            return name;
182        }
183    
184        /**
185         * Set the file name.
186         *
187         * @param name the file name
188         */
189        public void setName(String name) {
190            this.name = name;
191        }
192    
193        /**
194         * Return the last modified time from the last time it
195         * was checked.
196         *
197         * @return the last modified time
198         */
199        public long getLastModified() {
200            return lastModified;
201        }
202    
203        /**
204         * Return the last modified time from the last time it
205         * was checked.
206         *
207         * @param lastModified The last modified time
208         */
209        public void setLastModified(long lastModified) {
210            this.lastModified = lastModified;
211        }
212    
213        /**
214         * Return the length.
215         *
216         * @return the length
217         */
218        public long getLength() {
219            return length;
220        }
221    
222        /**
223         * Set the length.
224         *
225         * @param length the length
226         */
227        public void setLength(long length) {
228            this.length = length;
229        }
230    
231        /**
232         * Indicate whether the file existed the last time it
233         * was checked.
234         *
235         * @return whether the file existed
236         */
237        public boolean isExists() {
238            return exists;
239        }
240    
241        /**
242         * Set whether the file existed the last time it
243         * was checked.
244         *
245         * @param exists whether the file exists or not
246         */
247        public void setExists(boolean exists) {
248            this.exists = exists;
249        }
250    
251        /**
252         * Indicate whether the file is a directory or not.
253         *
254         * @return whether the file is a directory or not
255         */
256        public boolean isDirectory() {
257            return directory;
258        }
259    
260        /**
261         * Set whether the file is a directory or not.
262         *
263         * @param directory whether the file is a directory or not
264         */
265        public void setDirectory(boolean directory) {
266            this.directory = directory;
267        }
268    }