StorageReference

public class StorageReference implements Comparable

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)

Summary

Public methods
`@NonNull StorageReference`	`child(@NonNull String pathString)` Returns a new instance of `StorageReference` pointing to a child location of the current reference.
`int`	`compareTo(@NonNull StorageReference other)`
`@NonNull Task<Void>`	`delete()` Deletes the object at this `StorageReference`.
`boolean`	`equals(Object other)`
`@NonNull List<FileDownloadTask>`	`getActiveDownloadTasks()`
`@NonNull List<UploadTask>`	`getActiveUploadTasks()`
`@NonNull String`	`getBucket()` Return the Google Cloud Storage bucket that holds this object.
`@NonNull 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.
`@NonNull Task<Uri>`	`getDownloadUrl()` Asynchronously retrieves a long lived download URL with a revokable token.
`@NonNull FileDownloadTask`	`getFile(@NonNull File destinationFile)` Asynchronously downloads the object at this `StorageReference` to a specified system filepath.
`@NonNull FileDownloadTask`	`getFile(@NonNull Uri destinationUri)` Asynchronously downloads the object at this `StorageReference` to a specified system filepath.
`@NonNull Task<StorageMetadata>`	`getMetadata()` Retrieves metadata associated with an object at this `StorageReference`.
`@NonNull String`	`getName()` Returns the short name of this object.
`@Nullable StorageReference`	`getParent()` Returns a new instance of `StorageReference` pointing to the parent location or null if this instance references the root location.
`@NonNull String`	`getPath()` Returns the full path to this object, not including the Google Cloud Storage bucket.
`@NonNull StorageReference`	`getRoot()` Returns a new instance of `StorageReference` pointing to the root location.
`@NonNull FirebaseStorage`	`getStorage()` Returns the `FirebaseStorage` service which created this reference.
`@NonNull StreamDownloadTask`	`getStream()` Asynchronously downloads the object at this `StorageReference` via a `InputStream`.
`@NonNull StreamDownloadTask`	`getStream(@NonNull StreamDownloadTask.StreamProcessor processor)` Asynchronously downloads the object at this `StorageReference` via a `InputStream`.
`int`	`hashCode()`
`@NonNull Task<ListResult>`	`list(int maxResults)` List up to `maxResults` items (files) and prefixes (folders) under this StorageReference.
`@NonNull Task<ListResult>`	`list(int maxResults, @NonNull String pageToken)` Resumes a previous call to `list`, starting after a pagination token.
`@NonNull Task<ListResult>`	`listAll()` List all items (files) and prefixes (folders) under this StorageReference.
`@NonNull UploadTask`	`putBytes(@NonNull byte[] bytes)` Asynchronously uploads byte data to this `StorageReference`.
`@NonNull UploadTask`	`putBytes(@NonNull byte[] bytes, @NonNull StorageMetadata metadata)` Asynchronously uploads byte data to this `StorageReference`.
`@NonNull UploadTask`	`putFile(@NonNull Uri uri)` Asynchronously uploads from a content URI to this `StorageReference`.
`@NonNull UploadTask`	`putFile(@NonNull Uri uri, @NonNull StorageMetadata metadata)` Asynchronously uploads from a content URI to this `StorageReference`.
`@NonNull UploadTask`	`putFile( @NonNull Uri uri, @Nullable StorageMetadata metadata, @Nullable Uri existingUploadUri )` Asynchronously uploads from a content URI to this `StorageReference`.
`@NonNull UploadTask`	`putStream(@NonNull InputStream stream)` Asynchronously uploads a stream of data to this `StorageReference`.
`@NonNull UploadTask`	`putStream(@NonNull InputStream stream, @NonNull StorageMetadata metadata)` Asynchronously uploads a stream of data to this `StorageReference`.
`String`	`toString()`
`@NonNull Task<StorageMetadata>`	`updateMetadata(@NonNull StorageMetadata metadata)` Updates the metadata associated with this `StorageReference`.

Public methods

child

public @NonNull StorageReference child(@NonNull 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
`@NonNull String pathString`	The relative path from this reference.

Returns
`@NonNull StorageReference`	the child `StorageReference`.

compareTo

public int compareTo(@NonNull StorageReference other)

delete

public @NonNull Task<Void> delete()

Deletes the object at this StorageReference.

Returns
`@NonNull Task<Void>`	A `Task` that indicates whether the operation succeeded or failed.

equals

public boolean equals(Object other)

getActiveDownloadTasks

public @NonNull List<FileDownloadTask> getActiveDownloadTasks()

Returns
`@NonNull List<FileDownloadTask>`	the set of active download tasks currently in progress or recently completed.

getActiveUploadTasks

public @NonNull List<UploadTask> getActiveUploadTasks()

Returns
`@NonNull List<UploadTask>`	the set of active upload tasks currently in progress or recently completed.

getBucket

public @NonNull String getBucket()

Return the Google Cloud Storage bucket that holds this object.

Returns
`@NonNull String`	the bucket.

getBytes

public @NonNull 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 may be a better option.

Parameters
`long 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
`@NonNull Task<byte[]>`	The bytes downloaded.

getDownloadUrl

public @NonNull 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
`@NonNull Task<Uri>`	The `Uri` representing the download URL. You can feed this URL into a `URL` and download the object via `openStream`.

getFile

public @NonNull FileDownloadTask getFile(@NonNull File destinationFile)

Asynchronously downloads the object at this StorageReference to a specified system filepath.

Parameters
`@NonNull File destinationFile`	A `File` representing the path the object should be downloaded to.

Returns
`@NonNull FileDownloadTask`	A `FileDownloadTask` that can be used to monitor or manage the download.

getFile

public @NonNull FileDownloadTask getFile(@NonNull Uri destinationUri)

Asynchronously downloads the object at this StorageReference to a specified system filepath.

Parameters
`@NonNull Uri destinationUri`	A file system URI representing the path the object should be downloaded to.

Returns
`@NonNull FileDownloadTask`	A `FileDownloadTask` that can be used to monitor or manage the download.

getMetadata

public @NonNull Task<StorageMetadata> getMetadata()

Retrieves metadata associated with an object at this StorageReference.

Returns
`@NonNull Task<StorageMetadata>`	the metadata.

getName

public @NonNull String getName()

Returns the short name of this object.

Returns
`@NonNull String`	the name.

getParent

public @Nullable 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
`@Nullable StorageReference`	the parent `StorageReference`.

getPath

public @NonNull String getPath()

Returns the full path to this object, not including the Google Cloud Storage bucket.

Returns
`@NonNull String`	the path.

getRoot

public @NonNull StorageReference getRoot()

Returns a new instance of StorageReference pointing to the root location.

Returns
`@NonNull StorageReference`	the root `StorageReference`.

getStorage

public @NonNull FirebaseStorage getStorage()

Returns the FirebaseStorage service which created this reference.

Returns
`@NonNull FirebaseStorage`	The `FirebaseStorage` service.

getStream

public @NonNull 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

Returns
`@NonNull StreamDownloadTask`	A `FileDownloadTask` that can be used to monitor or manage the download.

getStream

public @NonNull StreamDownloadTask getStream(@NonNull StreamDownloadTask.StreamProcessor processor)

Asynchronously downloads the object at this StorageReference via a InputStream.

Parameters
`@NonNull StreamDownloadTask.StreamProcessor 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
`@NonNull StreamDownloadTask`	A `FileDownloadTask` that can be used to monitor or manage the download.

hashCode

public int hashCode()

list

public @NonNull 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
`int maxResults`	The maximum number of results to return in a single page. Must be greater than 0 and at most 1000.

Returns
`@NonNull Task<ListResult>`	A a `Task` that returns up to maxResults items and prefixes under the current StorageReference.

list

public @NonNull Task<ListResult> list(int maxResults, @NonNull String pageToken)

Resumes a previous call to list, starting after a pagination token. Returns the next set of items (files) and prefixes (folders) under this StorageReference.

list() is only available for projects using Firebase Rules Version 2.

Parameters
`int maxResults`	The maximum number of results to return in a single page. Must be greater than 0 and at most 1000.
`@NonNull String pageToken`	A page token from a previous call to list.

Returns
`@NonNull Task<ListResult>`	A a `Task` that returns the next items and prefixes under the current StorageReference.

listAll

public @NonNull 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
`@NonNull Task<ListResult>`	A `Task` that returns all items and prefixes under the current StorageReference.

Throws
`java.lang.OutOfMemoryError java.lang.OutOfMemoryError`	If there are too many items at this location.

putBytes

public @NonNull UploadTask putBytes(@NonNull byte[] bytes)

Asynchronously uploads byte data to this StorageReference. This is not recommended for large files. Instead upload a file via putFile or an InputStream via putStream.

Parameters
`@NonNull byte[] bytes`	The byte array to upload.

Returns
`@NonNull UploadTask`	An instance of `UploadTask` which can be used to monitor and manage the upload.

putBytes

public @NonNull UploadTask putBytes(@NonNull byte[] bytes, @NonNull StorageMetadata metadata)

Asynchronously uploads byte data to this StorageReference. This is not recommended for large files. Instead upload a file via putFile or a Stream via putStream.

Parameters
`@NonNull byte[] bytes`	The byte[] to upload.
`@NonNull StorageMetadata metadata`	`StorageMetadata` containing additional information (MIME type, etc.) about the object being uploaded.

Returns
`@NonNull UploadTask`	An instance of `UploadTask` which can be used to monitor and manage the upload.

putFile

public @NonNull UploadTask putFile(@NonNull Uri uri)

Asynchronously uploads from a content URI to this StorageReference.

Parameters
`@NonNull Uri 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
`@NonNull UploadTask`	An instance of `UploadTask` which can be used to monitor or manage the upload.

putFile

public @NonNull UploadTask putFile(@NonNull Uri uri, @NonNull StorageMetadata metadata)

Asynchronously uploads from a content URI to this StorageReference.

Parameters
`@NonNull Uri 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.
`@NonNull StorageMetadata metadata`	`StorageMetadata` containing additional information (MIME type, etc.) about the object being uploaded.

Returns
`@NonNull UploadTask`	An instance of `UploadTask` which can be used to monitor or manage the upload.

putFile

public @NonNull UploadTask putFile(
    @NonNull Uri uri,
    @Nullable StorageMetadata metadata,
    @Nullable Uri existingUploadUri
)

Asynchronously uploads from a content URI to this StorageReference.

Parameters
`@NonNull Uri 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.
`@Nullable StorageMetadata metadata`	`StorageMetadata` containing additional information (MIME type, etc.) about the object being uploaded.
`@Nullable Uri existingUploadUri`	If set, an attempt is made to resume an existing upload session as defined by `getUploadSessionUri`.

Returns
`@NonNull UploadTask`	An instance of `UploadTask` which can be used to monitor or manage the upload.

putStream

public @NonNull UploadTask putStream(@NonNull InputStream stream)

Asynchronously uploads a stream of data to this StorageReference. The stream will remain open at the end of the upload.

Parameters
`@NonNull InputStream stream`	The `InputStream` to upload.

Returns
`@NonNull UploadTask`	An instance of `UploadTask` which can be used to monitor and manage the upload.

putStream

public @NonNull UploadTask putStream(@NonNull InputStream stream, @NonNull StorageMetadata metadata)

Asynchronously uploads a stream of data to this StorageReference. The stream will remain open at the end of the upload.

Parameters
`@NonNull InputStream stream`	The `InputStream` to upload.
`@NonNull StorageMetadata metadata`	`StorageMetadata` containing additional information (MIME type, etc.) about the object being uploaded.

Returns
`@NonNull UploadTask`	An instance of `UploadTask` which can be used to monitor and manage the upload.

toString

public String toString()

Returns
`String`	This object in URI form, which can then be shared and passed into `getReferenceFromUrl`.

updateMetadata

public @NonNull Task<StorageMetadata> updateMetadata(@NonNull StorageMetadata metadata)

Updates the metadata associated with this StorageReference.

Parameters
`@NonNull StorageMetadata metadata`	A `StorageMetadata` object with the metadata to update.

Returns
`@NonNull Task<StorageMetadata>`	a `Task` that will return the final `StorageMetadata` once the operation is complete.