1/*
2 * Copyright (C) 2006 The Android Open Source Project
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 *      http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17package android.os;
18
19import android.annotation.Nullable;
20import android.util.Log;
21
22import java.lang.ref.WeakReference;
23import java.util.HashMap;
24
25/**
26 * Monitors files (using <a href="http://en.wikipedia.org/wiki/Inotify">inotify</a>)
27 * to fire an event after files are accessed or changed by by any process on
28 * the device (including this one).  FileObserver is an abstract class;
29 * subclasses must implement the event handler {@link #onEvent(int, String)}.
30 *
31 * <p>Each FileObserver instance monitors a single file or directory.
32 * If a directory is monitored, events will be triggered for all files and
33 * subdirectories inside the monitored directory.</p>
34 *
35 * <p>An event mask is used to specify which changes or actions to report.
36 * Event type constants are used to describe the possible changes in the
37 * event mask as well as what actually happened in event callbacks.</p>
38 *
39 * <p class="caution"><b>Warning</b>: If a FileObserver is garbage collected, it
40 * will stop sending events.  To ensure you keep receiving events, you must
41 * keep a reference to the FileObserver instance from some other live object.</p>
42 */
43public abstract class FileObserver {
44    /** Event type: Data was read from a file */
45    public static final int ACCESS = 0x00000001;
46    /** Event type: Data was written to a file */
47    public static final int MODIFY = 0x00000002;
48    /** Event type: Metadata (permissions, owner, timestamp) was changed explicitly */
49    public static final int ATTRIB = 0x00000004;
50    /** Event type: Someone had a file or directory open for writing, and closed it */
51    public static final int CLOSE_WRITE = 0x00000008;
52    /** Event type: Someone had a file or directory open read-only, and closed it */
53    public static final int CLOSE_NOWRITE = 0x00000010;
54    /** Event type: A file or directory was opened */
55    public static final int OPEN = 0x00000020;
56    /** Event type: A file or subdirectory was moved from the monitored directory */
57    public static final int MOVED_FROM = 0x00000040;
58    /** Event type: A file or subdirectory was moved to the monitored directory */
59    public static final int MOVED_TO = 0x00000080;
60    /** Event type: A new file or subdirectory was created under the monitored directory */
61    public static final int CREATE = 0x00000100;
62    /** Event type: A file was deleted from the monitored directory */
63    public static final int DELETE = 0x00000200;
64    /** Event type: The monitored file or directory was deleted; monitoring effectively stops */
65    public static final int DELETE_SELF = 0x00000400;
66    /** Event type: The monitored file or directory was moved; monitoring continues */
67    public static final int MOVE_SELF = 0x00000800;
68
69    /** Event mask: All valid event types, combined */
70    public static final int ALL_EVENTS = ACCESS | MODIFY | ATTRIB | CLOSE_WRITE
71            | CLOSE_NOWRITE | OPEN | MOVED_FROM | MOVED_TO | DELETE | CREATE
72            | DELETE_SELF | MOVE_SELF;
73
74    private static final String LOG_TAG = "FileObserver";
75
76    private static class ObserverThread extends Thread {
77        private HashMap<Integer, WeakReference> m_observers = new HashMap<Integer, WeakReference>();
78        private int m_fd;
79
80        public ObserverThread() {
81            super("FileObserver");
82            m_fd = init();
83        }
84
85        public void run() {
86            observe(m_fd);
87        }
88
89        public int startWatching(String path, int mask, FileObserver observer) {
90            int wfd = startWatching(m_fd, path, mask);
91
92            Integer i = new Integer(wfd);
93            if (wfd >= 0) {
94                synchronized (m_observers) {
95                    m_observers.put(i, new WeakReference(observer));
96                }
97            }
98
99            return i;
100        }
101
102        public void stopWatching(int descriptor) {
103            stopWatching(m_fd, descriptor);
104        }
105
106        public void onEvent(int wfd, int mask, String path) {
107            // look up our observer, fixing up the map if necessary...
108            FileObserver observer = null;
109
110            synchronized (m_observers) {
111                WeakReference weak = m_observers.get(wfd);
112                if (weak != null) {  // can happen with lots of events from a dead wfd
113                    observer = (FileObserver) weak.get();
114                    if (observer == null) {
115                        m_observers.remove(wfd);
116                    }
117                }
118            }
119
120            // ...then call out to the observer without the sync lock held
121            if (observer != null) {
122                try {
123                    observer.onEvent(mask, path);
124                } catch (Throwable throwable) {
125                    Log.wtf(LOG_TAG, "Unhandled exception in FileObserver " + observer, throwable);
126                }
127            }
128        }
129
130        private native int init();
131        private native void observe(int fd);
132        private native int startWatching(int fd, String path, int mask);
133        private native void stopWatching(int fd, int wfd);
134    }
135
136    private static ObserverThread s_observerThread;
137
138    static {
139        s_observerThread = new ObserverThread();
140        s_observerThread.start();
141    }
142
143    // instance
144    private String m_path;
145    private Integer m_descriptor;
146    private int m_mask;
147
148    /**
149     * Equivalent to FileObserver(path, FileObserver.ALL_EVENTS).
150     */
151    public FileObserver(String path) {
152        this(path, ALL_EVENTS);
153    }
154
155    /**
156     * Create a new file observer for a certain file or directory.
157     * Monitoring does not start on creation!  You must call
158     * {@link #startWatching()} before you will receive events.
159     *
160     * @param path The file or directory to monitor
161     * @param mask The event or events (added together) to watch for
162     */
163    public FileObserver(String path, int mask) {
164        m_path = path;
165        m_mask = mask;
166        m_descriptor = -1;
167    }
168
169    protected void finalize() {
170        stopWatching();
171    }
172
173    /**
174     * Start watching for events.  The monitored file or directory must exist at
175     * this time, or else no events will be reported (even if it appears later).
176     * If monitoring is already started, this call has no effect.
177     */
178    public void startWatching() {
179        if (m_descriptor < 0) {
180            m_descriptor = s_observerThread.startWatching(m_path, m_mask, this);
181        }
182    }
183
184    /**
185     * Stop watching for events.  Some events may be in process, so events
186     * may continue to be reported even after this method completes.  If
187     * monitoring is already stopped, this call has no effect.
188     */
189    public void stopWatching() {
190        if (m_descriptor >= 0) {
191            s_observerThread.stopWatching(m_descriptor);
192            m_descriptor = -1;
193        }
194    }
195
196    /**
197     * The event handler, which must be implemented by subclasses.
198     *
199     * <p class="note">This method is invoked on a special FileObserver thread.
200     * It runs independently of any threads, so take care to use appropriate
201     * synchronization!  Consider using {@link Handler#post(Runnable)} to shift
202     * event handling work to the main thread to avoid concurrency problems.</p>
203     *
204     * <p>Event handlers must not throw exceptions.</p>
205     *
206     * @param event The type of event which happened
207     * @param path The path, relative to the main monitored file or directory,
208     *     of the file or directory which triggered the event.  This value can
209     *     be {@code null} for certain events, such as {@link #MOVE_SELF}.
210     */
211    public abstract void onEvent(int event, @Nullable String path);
212}
213