Represents a reference to a Google Cloud Storage object. Developers can upload and download objects, get/set object metadata, and delete an object at a specified path. (see Google Cloud Storage)
Public Method Summary
StorageReference |
child(String pathString)
Returns a new instance of
StorageReference
pointing to a child location of the current reference.
|
int |
compareTo(StorageReference
other)
|
Task<Void> |
delete()
Deletes the object at this
StorageReference .
|
boolean | |
List<FileDownloadTask> | |
List<UploadTask> | |
String |
getBucket()
Return the Google Cloud Storage bucket that holds this object.
|
Task<byte[]> |
getBytes(long maxDownloadSizeBytes)
Asynchronously downloads the object from this
StorageReference
A byte array will be allocated large enough to hold the entire file in memory.
|
Task<Uri> |
getDownloadUrl()
Asynchronously retrieves a long lived download URL with a revokable token.
|
FileDownloadTask |
getFile(File destinationFile)
Asynchronously downloads the object at this
StorageReference
to a specified system filepath.
|
FileDownloadTask |
getFile(Uri destinationUri)
Asynchronously downloads the object at this
StorageReference
to a specified system filepath.
|
Task<StorageMetadata> |
getMetadata()
Retrieves metadata associated with an object at this
StorageReference .
|
String |
getName()
Returns the short name of this object.
|
StorageReference |
getParent()
Returns a new instance of
StorageReference
pointing to the parent location or null if this instance references the root
location.
|
String |
getPath()
Returns the full path to this object, not including the Google Cloud Storage
bucket.
|
StorageReference |
getRoot()
Returns a new instance of
StorageReference
pointing to the root location.
|
FirebaseStorage |
getStorage()
Returns the
FirebaseStorage
service which created this reference.
|
StreamDownloadTask |
getStream(StreamDownloadTask.StreamProcessor
processor)
Asynchronously downloads the object at this
StorageReference
via a InputStream .
|
StreamDownloadTask |
getStream()
Asynchronously downloads the object at this
StorageReference
via a InputStream .
|
int |
hashCode()
|
Task<ListResult> | |
Task<ListResult> |
list(int
maxResults)
List up to
maxResults items (files) and prefixes (folders) under
this StorageReference.
|
Task<ListResult> |
listAll()
List all items (files) and prefixes (folders) under this StorageReference.
|
UploadTask |
putBytes(byte[] bytes, StorageMetadata
metadata)
Asynchronously uploads byte data to this
StorageReference .
|
UploadTask |
putBytes(byte[] bytes)
Asynchronously uploads byte data to this
StorageReference .
|
UploadTask |
putFile(Uri uri, StorageMetadata
metadata, Uri
existingUploadUri)
Asynchronously uploads from a content URI to this
StorageReference .
|
UploadTask |
putFile(Uri uri, StorageMetadata
metadata)
Asynchronously uploads from a content URI to this
StorageReference .
|
UploadTask | |
UploadTask |
putStream(InputStream
stream, StorageMetadata
metadata)
Asynchronously uploads a stream of data to this
StorageReference .
|
UploadTask | |
String |
toString()
|
Task<StorageMetadata> |
updateMetadata(StorageMetadata
metadata)
Updates the metadata associated with this
StorageReference .
|
Inherited Method Summary
Public Methods
public StorageReference child (String pathString)
Returns a new instance of StorageReference
pointing to a child location of the current reference. All leading and trailing slashes
will be removed, and consecutive slashes will be compressed to single slashes. For
example:
child = /foo/bar path = foo/bar
child = foo/bar/ path = foo/bar
child = foo///bar path = foo/bar
Parameters
pathString | The relative path from this reference. |
---|
Returns
- the child
StorageReference
.
public int compareTo (StorageReference other)
public Task<Void> delete ()
Deletes the object at this StorageReference
.
Returns
- A
Task
that indicates whether the operation succeeded or failed.
public boolean equals (Object other)
public List<FileDownloadTask> getActiveDownloadTasks ()
Returns
- the set of active download tasks currently in progress or recently completed.
public List<UploadTask> getActiveUploadTasks ()
Returns
- the set of active upload tasks currently in progress or recently completed.
public String getBucket ()
Return the Google Cloud Storage bucket that holds this object.
Returns
- the bucket.
public Task<byte[]> getBytes (long maxDownloadSizeBytes)
Asynchronously downloads the object from this StorageReference
A byte array will be allocated large enough to hold the entire file in memory.
Therefore, using this method will impact memory usage of your process. If you are
downloading many large files,
getStream(StreamDownloadTask.StreamProcessor)
may be a better option.
Parameters
maxDownloadSizeBytes | The maximum allowed size in bytes that will be allocated. Set this parameter to
prevent out of memory conditions from occurring. If the download exceeds this
limit, the task will fail and an IndexOutOfBoundsException
will be returned. |
---|
Returns
- The bytes downloaded.
public Task<Uri> getDownloadUrl ()
Asynchronously retrieves a long lived download URL with a revokable token. This can be used to share the file with others, but can be revoked by a developer in the Firebase Console if desired.
Returns
- The
Uri
representing the download URL. You can feed this URL into aURL
and download the object viaopenStream()
.
public FileDownloadTask getFile (File destinationFile)
Asynchronously downloads the object at this StorageReference
to a specified system filepath.
Parameters
destinationFile | A File representing
the path the object should be downloaded to. |
---|
Returns
- A
FileDownloadTask
that can be used to monitor or manage the download.
public FileDownloadTask getFile (Uri destinationUri)
Asynchronously downloads the object at this StorageReference
to a specified system filepath.
Parameters
destinationUri | A file system URI representing the path the object should be downloaded to. |
---|
Returns
- A
FileDownloadTask
that can be used to monitor or manage the download.
public Task<StorageMetadata> getMetadata ()
Retrieves metadata associated with an object at this StorageReference
.
Returns
- the metadata.
public String getName ()
Returns the short name of this object.
Returns
- the name.
public StorageReference getParent ()
Returns a new instance of StorageReference
pointing to the parent location or null if this instance references the root location.
For example:
path = foo/bar/baz parent = foo/bar
path = foo parent = (root)
path = (root) parent = (null)
Returns
- the parent
StorageReference
.
public String getPath ()
Returns the full path to this object, not including the Google Cloud Storage bucket.
Returns
- the path.
public StorageReference getRoot ()
Returns a new instance of StorageReference
pointing to the root location.
Returns
- the root
StorageReference
.
public FirebaseStorage getStorage ()
Returns the FirebaseStorage
service which created this reference.
Returns
- The
FirebaseStorage
service.
public StreamDownloadTask getStream (StreamDownloadTask.StreamProcessor processor)
Asynchronously downloads the object at this StorageReference
via a InputStream
.
Parameters
processor | A
StreamDownloadTask.StreamProcessor that is responsible for reading data
from the InputStream .
The
StreamDownloadTask.StreamProcessor is called on a background thread and
checked exceptions thrown from this object will be returned as a failure to the
OnFailureListener
registered on the StreamDownloadTask . |
---|
Returns
- A
FileDownloadTask
that can be used to monitor or manage the download.
public StreamDownloadTask getStream ()
Asynchronously downloads the object at this StorageReference
via a InputStream
.
The InputStream should be read on an OnSuccessListener
registered to run on a background thread via
addOnSuccessListener(Executor, OnSuccessListener)
Returns
- A
FileDownloadTask
that can be used to monitor or manage the download.
public int hashCode ()
public Task<ListResult> list (int maxResults, String pageToken)
Resumes a previous call to list(int)
,
starting after a pagination token. Returns the next set of items (files) and prefixes
(folders) under this StorageReference.
"/" is treated as a path delimiter. Cloud Storage for Firebase does not support object paths that end with "/" or contain two consecutive "/"s. All invalid objects in Google Cloud Storage will be filtered.
list()
is only available for projects using Firebase
Rules Version 2.
Parameters
maxResults | The maximum number of results to return in a single page. Must be greater than 0 and at most 1000. |
---|---|
pageToken | A page token from a previous call to list. |
Returns
- A a
Task
that returns the next items and prefixes under the current StorageReference.
public Task<ListResult> list (int maxResults)
List up to maxResults
items (files) and prefixes (folders) under this
StorageReference.
"/" is treated as a path delimiter. Cloud Storage for Firebase does not support object paths that end with "/" or contain two consecutive "/"s. All invalid objects in Google Cloud Storage will be filtered.
list()
is only available for projects using Firebase
Rules Version 2.
Parameters
maxResults | The maximum number of results to return in a single page. Must be greater than 0 and at most 1000. |
---|
Returns
- A a
Task
that returns up to maxResults items and prefixes under the current StorageReference.
public Task<ListResult> listAll ()
List all items (files) and prefixes (folders) under this StorageReference.
This is a helper method for calling list()
repeatedly until there are
no more results. Consistency of the result is not guaranteed if objects are inserted or
removed while this operation is executing.
listAll()
is only available for projects using Firebase
Rules Version 2.
Returns
- A
Task
that returns all items and prefixes under the current StorageReference.
Throws
OutOfMemoryError | If there are too many items at this location. |
---|
public UploadTask putBytes (byte[] bytes, StorageMetadata metadata)
Asynchronously uploads byte data to this StorageReference
.
This is not recommended for large files. Instead upload a file via
putFile(Uri)
or a Stream via
putStream(InputStream)
.
Parameters
bytes | The byte[] to upload. |
---|---|
metadata | StorageMetadata
containing additional information (MIME type, etc.) about the object being
uploaded. |
Returns
- An instance of
UploadTask
which can be used to monitor and manage the upload.
public UploadTask putBytes (byte[] bytes)
Asynchronously uploads byte data to this StorageReference
.
This is not recommended for large files. Instead upload a file via
putFile(Uri)
or an InputStream
via
putStream(InputStream)
.
Parameters
bytes | The byte array to upload. |
---|
Returns
- An instance of
UploadTask
which can be used to monitor and manage the upload.
public UploadTask putFile (Uri uri, StorageMetadata metadata, Uri existingUploadUri)
Asynchronously uploads from a content URI to this StorageReference
.
Parameters
uri | The source of the upload. This can be a file:// scheme or any content URI. A content resolver will be used to load the data. |
---|---|
metadata | StorageMetadata
containing additional information (MIME type, etc.) about the object being
uploaded. |
existingUploadUri | If set, an attempt is made to resume an existing upload session as defined by
getUploadSessionUri() . |
Returns
- An instance of
UploadTask
which can be used to monitor or manage the upload.
public UploadTask putFile (Uri uri, StorageMetadata metadata)
Asynchronously uploads from a content URI to this StorageReference
.
Parameters
uri | The source of the upload. This can be a file:// scheme or any content URI. A content resolver will be used to load the data. |
---|---|
metadata | StorageMetadata
containing additional information (MIME type, etc.) about the object being
uploaded. |
Returns
- An instance of
UploadTask
which can be used to monitor or manage the upload.
public UploadTask putFile (Uri uri)
Asynchronously uploads from a content URI to this StorageReference
.
Parameters
uri | The source of the upload. This can be a file:// scheme or any content URI. A content resolver will be used to load the data. |
---|
Returns
- An instance of
UploadTask
which can be used to monitor or manage the upload.
public UploadTask putStream (InputStream stream, StorageMetadata metadata)
Asynchronously uploads a stream of data to this StorageReference
.
The stream will remain open at the end of the upload.
Parameters
stream | The InputStream
to upload. |
---|---|
metadata | StorageMetadata
containing additional information (MIME type, etc.) about the object being
uploaded. |
Returns
- An instance of
UploadTask
which can be used to monitor and manage the upload.
public UploadTask putStream (InputStream stream)
Asynchronously uploads a stream of data to this StorageReference
.
The stream will remain open at the end of the upload.
Parameters
stream | The InputStream
to upload. |
---|
Returns
- An instance of
UploadTask
which can be used to monitor and manage the upload.
public String toString ()
Returns
- This object in URI form, which can then be shared and passed into
getReferenceFromUrl(String)
.
public Task<StorageMetadata> updateMetadata (StorageMetadata metadata)
Updates the metadata associated with this StorageReference
.
Parameters
metadata | A StorageMetadata
object with the metadata to update. |
---|
Returns
- a
Task
that will return the finalStorageMetadata
once the operation is complete.