public class DbxFile
extends java.lang.Object
DbxFileSystem.create(DbxPath)
or DbxFileSystem.open(DbxPath)
.
A DbxFile
represents a specific version of a file in Dropbox. You can use
it to read or write the file's contents, or get info about the file. You can
also check the file's sync status, and see when there's a newer version
available.
Use DbxFile.addListener(com.dropbox.sync.android.DbxFile.Listener)
, DbxFile.getNewerStatus()
, and DbxFile.update()
to
update this file to a newer version when updates are available. If you don't,
you can continue to read a stale cached version indefinitely, but writes
will create a conflict.
Note that open files will cause the Sync API to perform more frequent updates in the background to ensure new file versions are available. To avoid consuming extra power, you shouldn't keep files open when your app isn't in use.
Modifier and Type | Class and Description |
---|---|
static interface |
DbxFile.Listener
A listener that will be called when there's a change to the sync
status, file info, or contents of this file.
|
static class |
DbxFile.StreamExclusionException
Thrown when attempt was made to read or write this DbxFile when an existing
stream is already open.
|
Modifier and Type | Method and Description |
---|---|
void |
addListener(DbxFile.Listener l)
Adds a listener that will be called when there's a change to the sync
status, file info, or contents of this file or other versions of the same
file.
|
void |
appendString(java.lang.String data)
Appends the given string encoded in UTF-8 to the file.
|
void |
close()
Closes this file, as well as any open read or write streams, and
finalizes any outstanding writes.
|
java.io.FileOutputStream |
getAppendStream()
Returns a stream that can be used to append data to this file.
|
DbxFileInfo |
getInfo()
Returns info about this file.
|
DbxFileStatus |
getNewerStatus()
Checks for newer versions of this file, and returns the synchronization
status of a newer version, if any.
|
DbxPath |
getPath()
Gets the path used to open or create this file.
|
java.io.FileInputStream |
getReadStream()
Returns a stream that can be used to read data from this file.
|
DbxFileStatus |
getSyncStatus()
Returns the current status of synchronizing this version
of this file.
|
java.io.FileOutputStream |
getWriteStream()
Returns a stream that can be used to write data to this file.
|
boolean |
isThumb()
Determines whether this instance represents a thumbnail, as opposed to file contents.
|
java.lang.String |
readString()
Reads the full contents of this file as a String in UTF-8 encoding.
|
void |
removeListener(DbxFile.Listener l)
Removes a listener previously registered with
DbxFile.addListener(com.dropbox.sync.android.DbxFile.Listener) . |
boolean |
update()
Updates this DbxFile to a newer cached version of the same file,
as reflected by
DbxFile.getNewerStatus() . |
void |
writeFromExistingFile(java.io.File file,
boolean shouldSteal)
Replaces the contents of this file with the contents of a
given file.
|
void |
writeString(java.lang.String data)
Replaces the contents of this file with the given string,
encoded in UTF-8.
|
public void close()
If there is a failure finalizing writes, it will be logged as a
warning but will not result in an exception. Calling this method
again on a closed file will have no effect. Other methods will
throw IllegalStateException
after a file is closed.
public DbxPath getPath()
public boolean isThumb()
public java.io.FileInputStream getReadStream() throws DbxException
Once a read stream has been opened on this file, no writes can be made to this file until this stream is closed, or the file is closed. Multiple read streams can be open at once. Read streams aren't thread-safe, so each should be used on only one thread, or synchronized externally.
Callers can use the file-descriptor backing this stream if they need direct access to the file. The file-descriptor represents a file in the cache, and shouldn't be written, but can be freely read until this stream is closed.
DbxException
- on a failure downloading or reading the file.java.io.IOException
- on an I/O error in the local cache.DbxFile.StreamExclusionException
- if there's already a write stream open.public java.lang.String readString()
DbxException
- on a failure downloading or reading the file.java.io.IOException
- on an I/O error in the local cache.DbxFile.StreamExclusionException
- if there's already a write stream open.public java.io.FileOutputStream getWriteStream()
No other reads or writes (including appends) can be made to this file while a write stream is open. Write streams aren't thread-safe, so each should be used on only one thread, or synchronized externally.
Callers can use the file-descriptor backing this stream if they need direct access to the file. The file-descriptor represents a new empty file, which will become the new file version when this stream is closed.
DbxException
- on a failure writing the file.java.io.IOException
- on an I/O error in the local cache.DbxFile.StreamExclusionException
- if there's already a read or write
stream open.public java.io.FileOutputStream getAppendStream()
No other reads or writes (including appends) can be made to this file while an append stream is open. Append streams aren't thread-safe, so each should be used on only one thread, or synchronized externally.
Callers can use the file-descriptor backing this stream if they need direct access to the file. The file-descriptor represents a temporary file containing the contents of the previous version of the file, which will become the new file version when this append stream is closed.
DbxException
- on a failure appending to the file.java.io.IOException
- on an I/O error in the local cache.DbxFile.StreamExclusionException
- if there's already a read or write
stream open.public void writeFromExistingFile(java.io.File file, boolean shouldSteal)
Optionally, the API can "steal" the given file, moving it into the private cache to avoid the need for copying data. If stealing is allowed, no future attempts should be made to access the file.
file
- The file containing the new contents.shouldSteal
- whether the API should steal the file, moving it into the
private cache rather than copying its contents.DbxException
- on a failure writing the file.java.io.IOException
- on an I/O error in the local cache or the
given file.DbxFile.StreamExclusionException
- if there's already a read or write
stream open.public void writeString(java.lang.String data)
data
- The String to write into the file.DbxException
- on a failure writing the file.java.io.IOException
- on an I/O error in the local cache.DbxFile.StreamExclusionException
- if there's already a read or write
stream open.public void appendString(java.lang.String data)
data
- The String to append to the file.DbxException
- on a failure appending to the file.java.io.IOException
- on an I/O error in the local cache.DbxFile.StreamExclusionException
- if there's already a read or write
stream open.public DbxFileInfo getInfo() throws DbxException
DbxFile
represents a
thumbnail, the returned info still reflects the full file contents.DbxException
- on a failure getting file info.public boolean update() throws DbxException
DbxFile.getNewerStatus()
. This method will have
no effect if there's no newer version, or the newer version isn't
yet cached. This operation is equivalent to closing the file and
reopening it, except that it will properly follow the file across
local rename and move operations.DbxException
- if the update fails.DbxFile.StreamExclusionException
- if any read or write streams
are open.public DbxFileStatus getSyncStatus() throws DbxException
DbxFile
represents a thumbnail,
the result reflects the sync status of the thumbnail, not the full
file contents.DbxException
- if status can't be retrieved.public DbxFileStatus getNewerStatus() throws DbxException
DbxFile.update()
.
A return value of null
indicates that this file version is the newest
known version.
DbxException.NotFound
- if this file was deleted after the
version that was opened.DbxException
- if status can't be retrieved.public void addListener(DbxFile.Listener l)
Adding the same listener multiple times will have no additional effect. A
single call to DbxFile.removeListener(com.dropbox.sync.android.DbxFile.Listener)
will still remove it. This method
will be ignored, and listeners won't be called if the file is closed or
the file system has been shut down.
Listeners are called on the main UI thread. To keep your UI responsive, you shouldn't do anything slow in your listener.
public void removeListener(DbxFile.Listener l)
DbxFile.addListener(com.dropbox.sync.android.DbxFile.Listener)
.