Comment-only change to add documentation for FileObserver (3dc1c7f5) · Commits · e / os / android_frameworks_base

core/java/android/os/FileObserver.java

+67 −13

Original line number	Diff line number	Diff line
		@@ -24,32 +24,51 @@ import java.lang.ref.WeakReference;
		import java.util.ArrayList;
		import java.util.HashMap;

		/**
		* Monitors files (using <a href="http://en.wikipedia.org/wiki/Inotify">inotify</a>)
		* to fire an event after files are accessed or changed by by any process on
		* the device (including this one). FileObserver is an abstract class;
		* subclasses must implement the event handler {@link #onEvent(int, String)}.
		*
		* <p>Each FileObserver instance monitors a single file or directory.
		* If a directory is monitored, events will be triggered for all files and
		* subdirectories (recursively) inside the monitored directory.</p>
		*
		* <p>An event mask is used to specify which changes or actions to report.
		* Event type constants are used to describe the possible changes in the
		* event mask as well as what actually happened in event callbacks.</p>
		*
		* <p class="caution"><b>Warning</b>: If a FileObserver is garbage collected, it
		* will stop sending events. To ensure you keep receiving events, you must
		* keep a reference to the FileObserver instance from some other live object.</p>
		*/
		public abstract class FileObserver {
		/** File was accessed */
		/** Event type: Data was read from a file */
		public static final int ACCESS = 0x00000001;
		/** File was modified */
		/** Event type: Data was written to a file */
		public static final int MODIFY = 0x00000002;
		/** Metadata changed */
		/** Event type: Metadata (permissions, owner, timestamp) was changed explicitly */
		public static final int ATTRIB = 0x00000004;
		/** Writable file was closed */
		/** Event type: Someone had a file or directory open for writing, and closed it */
		public static final int CLOSE_WRITE = 0x00000008;
		/** Unwrittable file closed */
		/** Event type: Someone had a file or directory open read-only, and closed it */
		public static final int CLOSE_NOWRITE = 0x00000010;
		/** File was opened */
		/** Event type: A file or directory was opened */
		public static final int OPEN = 0x00000020;
		/** File was moved from X */
		/** Event type: A file or subdirectory was moved from the monitored directory */
		public static final int MOVED_FROM = 0x00000040;
		/** File was moved to Y */
		/** Event type: A file or subdirectory was moved to the monitored directory */
		public static final int MOVED_TO = 0x00000080;
		/** Subfile was created */
		/** Event type: A new file or subdirectory was created under the monitored directory */
		public static final int CREATE = 0x00000100;
		/** Subfile was deleted */
		/** Event type: A file was deleted from the monitored directory */
		public static final int DELETE = 0x00000200;
		/** Self was deleted */
		/** Event type: The monitored file or directory was deleted; monitoring effectively stops */
		public static final int DELETE_SELF = 0x00000400;
		/** Self was moved */
		/** Event type: The monitored file or directory was moved; monitoring continues */
		public static final int MOVE_SELF = 0x00000800;

		/** Event mask: All valid event types, combined */
		public static final int ALL_EVENTS = ACCESS \| MODIFY \| ATTRIB \| CLOSE_WRITE
		\| CLOSE_NOWRITE \| OPEN \| MOVED_FROM \| MOVED_TO \| DELETE \| CREATE
		\| DELETE_SELF \| MOVE_SELF;
		@@ -128,10 +147,21 @@ public abstract class FileObserver {
		private Integer m_descriptor;
		private int m_mask;

		/**
		* Equivalent to FileObserver(path, FileObserver.ALL_EVENTS).
		*/
		public FileObserver(String path) {
		this(path, ALL_EVENTS);
		}

		/**
		* Create a new file observer for a certain file or directory.
		* Monitoring does not start on creation! You must call
		* {@link #startWatching()} before you will receive events.
		*
		* @param path The file or directory to monitor
		* @param mask The event or events (added together) to watch for
		*/
		public FileObserver(String path, int mask) {
		m_path = path;
		m_mask = mask;
		@@ -142,12 +172,22 @@ public abstract class FileObserver {
		stopWatching();
		}

		/**
		* Start watching for events. The monitored file or directory must exist at
		* this time, or else no events will be reported (even if it appears later).
		* If monitoring is already started, this call has no effect.
		*/
		public void startWatching() {
		if (m_descriptor < 0) {
		m_descriptor = s_observerThread.startWatching(m_path, m_mask, this);
		}
		}

		/**
		* Stop watching for events. Some events may be in process, so events
		* may continue to be reported even after this method completes. If
		* monitoring is already stopped, this call has no effect.
		*/
		public void stopWatching() {
		if (m_descriptor >= 0) {
		s_observerThread.stopWatching(m_descriptor);
		@@ -155,5 +195,19 @@ public abstract class FileObserver {
		}
		}

		/**
		* The event handler, which must be implemented by subclasses.
		*
		* <p class="note">This method is invoked on a special FileObserver thread.
		* It runs independently of any threads, so take care to use appropriate
		* synchronization! Consider using {@link Handler#post(Runnable)} to shift
		* event handling work to the main thread to avoid concurrency problems.</p>
		*
		* <p>Event handlers must not throw exceptions.</p>
		*
		* @param event The type of event which happened
		* @param path The path, relative to the main monitored file or directory,
		* of the file or directory which triggered the event
		*/
		public abstract void onEvent(int event, String path);
		}