Android/frameworks_base
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

am a80331c4: Merge "Comment-only change to add documentation for FileObserver" into froyo

Browse Source 
Merge commit 'a80331c4d75cb8a7122e31315bc1e2950131659c' into froyo-plus-aosp

* commit 'a80331c4d75cb8a7122e31315bc1e2950131659c':
  Comment-only change to add documentation for FileObserver
This commit is contained in:
Dan Egnor
2010-06-01 14:28:46 -07:00
committed by Android Git Automerger
parent bce5edaf46 a80331c4d7
commit 1f5e847350
1 changed files with 67 additions and 13 deletions
Download Patch File Download Diff File Expand all files Collapse all files

80
core/java/android/os/FileObserver.java
View File

@@ -24,33 +24,52 @@ 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;
public static final int ALL_EVENTS = ACCESS | MODIFY | ATTRIB | CLOSE_WRITE
/** 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);
}