StorageReference

public classStorageReference implementsComparable

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. (seeGoogle Cloud Storage)

Summary

Public methods

@NonNullStorageReference
child(@NonNullString pathString)

Returns a new instance ofStorageReference pointing to a child location of the current reference.

int
@NonNullTask<Void>

Deletes the object at thisStorageReference.

boolean
equals(Object other)
@NonNullList<FileDownloadTask>
@NonNullList<UploadTask>
@NonNullString

Return the Google Cloud Storage bucket that holds this object.

@NonNullTask<byte[]>
getBytes(long maxDownloadSizeBytes)

Asynchronously downloads the object from thisStorageReference A byte array will be allocated large enough to hold the entire file in memory.

@NonNullTask<Uri>

Asynchronously retrieves a long lived download URL with a revokable token.

@NonNullFileDownloadTask
getFile(@NonNullFile destinationFile)

Asynchronously downloads the object at thisStorageReference to a specified system filepath.

@NonNullFileDownloadTask
getFile(@NonNullUri destinationUri)

Asynchronously downloads the object at thisStorageReference to a specified system filepath.

@NonNullTask<StorageMetadata>

Retrieves metadata associated with an object at thisStorageReference.

@NonNullString

Returns the short name of this object.

@NullableStorageReference

Returns a new instance ofStorageReference pointing to the parent location or null if this instance references the root location.

@NonNullString

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

@NonNullStorageReference

Returns a new instance ofStorageReference pointing to the root location.

@NonNullFirebaseStorage

Returns theFirebaseStorage service which created this reference.

@NonNullStreamDownloadTask

Asynchronously downloads the object at thisStorageReference via aInputStream.

@NonNullStreamDownloadTask

Asynchronously downloads the object at thisStorageReference via aInputStream.

int
@NonNullTask<ListResult>
list(int maxResults)

List up tomaxResults items (files) and prefixes (folders) under this StorageReference.

@NonNullTask<ListResult>
list(int maxResults, @NonNullString pageToken)

Resumes a previous call tolist, starting after a pagination token.

@NonNullTask<ListResult>

List all items (files) and prefixes (folders) under this StorageReference.

@NonNullUploadTask
putBytes(@NonNull byte[] bytes)

Asynchronously uploads byte data to thisStorageReference.

@NonNullUploadTask
putBytes(@NonNull byte[] bytes, @NonNullStorageMetadata metadata)

Asynchronously uploads byte data to thisStorageReference.

@NonNullUploadTask

Asynchronously uploads from a content URI to thisStorageReference.

@NonNullUploadTask

Asynchronously uploads from a content URI to thisStorageReference.

@NonNullUploadTask
putFile(
    @NonNullUri uri,
    @NullableStorageMetadata metadata,
    @NullableUri existingUploadUri
)

Asynchronously uploads from a content URI to thisStorageReference.

@NonNullUploadTask

Asynchronously uploads a stream of data to thisStorageReference.

@NonNullUploadTask

Asynchronously uploads a stream of data to thisStorageReference.

String
@NonNullTask<StorageMetadata>

Updates the metadata associated with thisStorageReference.

Public methods

child

public @NonNullStorageReference child(@NonNullString pathString)

Returns a new instance ofStorageReference 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/barchild = foo/bar/     path = foo/barchild = foo///bar    path = foo/bar
Parameters
@NonNullString pathString

The relative path from this reference.

compareTo

public int compareTo(@NonNullStorageReference other)

delete

public @NonNullTask<Void> delete()

Deletes the object at thisStorageReference.

Returns
@NonNullTask<Void>

ATask that indicates whether the operation succeeded or failed.

equals

public boolean equals(Object other)

getActiveDownloadTasks

public @NonNullList<FileDownloadTask> getActiveDownloadTasks()
Returns
@NonNullList<FileDownloadTask>

the set of active download tasks currently in progress or recently completed.

getActiveUploadTasks

public @NonNullList<UploadTask> getActiveUploadTasks()
Returns
@NonNullList<UploadTask>

the set of active upload tasks currently in progress or recently completed.

getBucket

public @NonNullString getBucket()

Return the Google Cloud Storage bucket that holds this object.

Returns
@NonNullString

the bucket.

getBytes

public @NonNullTask<byte[]> getBytes(long maxDownloadSizeBytes)

Asynchronously downloads the object from thisStorageReference 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 anIndexOutOfBoundsException will be returned.

Returns
@NonNullTask<byte[]>

The bytes downloaded.

getDownloadUrl

public @NonNullTask<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
@NonNullTask<Uri>

TheUri representing the download URL. You can feed this URL into aURL and download the object viaopenStream.

getFile

public @NonNullFileDownloadTask getFile(@NonNullFile destinationFile)

Asynchronously downloads the object at thisStorageReference to a specified system filepath.

Parameters
@NonNullFile destinationFile

AFile representing the path the object should be downloaded to.

Returns
@NonNullFileDownloadTask

AFileDownloadTask that can be used to monitor or manage the download.

getFile

public @NonNullFileDownloadTask getFile(@NonNullUri destinationUri)

Asynchronously downloads the object at thisStorageReference to a specified system filepath.

Parameters
@NonNullUri destinationUri

A file system URI representing the path the object should be downloaded to.

Returns
@NonNullFileDownloadTask

AFileDownloadTask that can be used to monitor or manage the download.

getMetadata

public @NonNullTask<StorageMetadata> getMetadata()

Retrieves metadata associated with an object at thisStorageReference.

Returns
@NonNullTask<StorageMetadata>

the metadata.

getName

public @NonNullString getName()

Returns the short name of this object.

Returns
@NonNullString

the name.

getParent

public @NullableStorageReference getParent()

Returns a new instance ofStorageReference pointing to the parent location or null if this instance references the root location. For example:

path = foo/bar/baz   parent = foo/barpath = foo           parent = (root)path = (root)        parent = (null)

getPath

public @NonNullString getPath()

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

Returns
@NonNullString

the path.

getRoot

public @NonNullStorageReference getRoot()

Returns a new instance ofStorageReference pointing to the root location.

getStorage

public @NonNullFirebaseStorage getStorage()

Returns theFirebaseStorage service which created this reference.

getStream

public @NonNullStreamDownloadTask getStream()

Asynchronously downloads the object at thisStorageReference via aInputStream. The InputStream should be read on anOnSuccessListener registered to run on a background thread viaaddOnSuccessListener

Returns
@NonNullStreamDownloadTask

AFileDownloadTask that can be used to monitor or manage the download.

getStream

public @NonNullStreamDownloadTask getStream(@NonNullStreamDownloadTask.StreamProcessor processor)

Asynchronously downloads the object at thisStorageReference via aInputStream.

Parameters
@NonNullStreamDownloadTask.StreamProcessor processor

AStreamDownloadTask.StreamProcessor that is responsible for reading data from theInputStream. TheStreamDownloadTask.StreamProcessor is called on a background thread and checked exceptions thrown from this object will be returned as a failure to theOnFailureListener registered on theStreamDownloadTask.

Returns
@NonNullStreamDownloadTask

AFileDownloadTask that can be used to monitor or manage the download.

hashCode

public int hashCode()

list

public @NonNullTask<ListResult> list(int maxResults)

List up tomaxResults 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 usingFirebase 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
@NonNullTask<ListResult>

A aTask that returns up to maxResults items and prefixes under the current StorageReference.

list

public @NonNullTask<ListResult> list(int maxResults, @NonNullString pageToken)

Resumes a previous call tolist, 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 usingFirebase 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.

@NonNullString pageToken

A page token from a previous call to list.

Returns
@NonNullTask<ListResult>

A aTask that returns the next items and prefixes under the current StorageReference.

listAll

public @NonNullTask<ListResult> listAll()

List all items (files) and prefixes (folders) under this StorageReference.

This is a helper method for callinglist() 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 usingFirebase Rules Version 2.

Returns
@NonNullTask<ListResult>

ATask 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 @NonNullUploadTask putBytes(@NonNull byte[] bytes)

Asynchronously uploads byte data to thisStorageReference. This is not recommended for large files. Instead upload a file viaputFile or anInputStream viaputStream.

Parameters
@NonNull byte[] bytes

The byte array to upload.

Returns
@NonNullUploadTask

An instance ofUploadTask which can be used to monitor and manage the upload.

putBytes

public @NonNullUploadTask putBytes(@NonNull byte[] bytes, @NonNullStorageMetadata metadata)

Asynchronously uploads byte data to thisStorageReference. This is not recommended for large files. Instead upload a file viaputFile or a Stream viaputStream.

Parameters
@NonNull byte[] bytes

The byte[] to upload.

@NonNullStorageMetadata metadata

StorageMetadata containing additional information (MIME type, etc.) about the object being uploaded.

Returns
@NonNullUploadTask

An instance ofUploadTask which can be used to monitor and manage the upload.

putFile

public @NonNullUploadTask putFile(@NonNullUri uri)

Asynchronously uploads from a content URI to thisStorageReference.

Parameters
@NonNullUri 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
@NonNullUploadTask

An instance ofUploadTask which can be used to monitor or manage the upload.

putFile

public @NonNullUploadTask putFile(@NonNullUri uri, @NonNullStorageMetadata metadata)

Asynchronously uploads from a content URI to thisStorageReference.

Parameters
@NonNullUri 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.

@NonNullStorageMetadata metadata

StorageMetadata containing additional information (MIME type, etc.) about the object being uploaded.

Returns
@NonNullUploadTask

An instance ofUploadTask which can be used to monitor or manage the upload.

putFile

public @NonNullUploadTask putFile(
    @NonNullUri uri,
    @NullableStorageMetadata metadata,
    @NullableUri existingUploadUri
)

Asynchronously uploads from a content URI to thisStorageReference.

Parameters
@NonNullUri 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.

@NullableStorageMetadata metadata

StorageMetadata containing additional information (MIME type, etc.) about the object being uploaded.

@NullableUri existingUploadUri

If set, an attempt is made to resume an existing upload session as defined bygetUploadSessionUri.

Returns
@NonNullUploadTask

An instance ofUploadTask which can be used to monitor or manage the upload.

putStream

public @NonNullUploadTask putStream(@NonNullInputStream stream)

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

Parameters
@NonNullInputStream stream

TheInputStream to upload.

Returns
@NonNullUploadTask

An instance ofUploadTask which can be used to monitor and manage the upload.

putStream

public @NonNullUploadTask putStream(@NonNullInputStream stream, @NonNullStorageMetadata metadata)

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

Parameters
@NonNullInputStream stream

TheInputStream to upload.

@NonNullStorageMetadata metadata

StorageMetadata containing additional information (MIME type, etc.) about the object being uploaded.

Returns
@NonNullUploadTask

An instance ofUploadTask 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 intogetReferenceFromUrl.

updateMetadata

public @NonNullTask<StorageMetadata> updateMetadata(@NonNullStorageMetadata metadata)

Updates the metadata associated with thisStorageReference.

Parameters
@NonNullStorageMetadata metadata

AStorageMetadata object with the metadata to update.

Returns
@NonNullTask<StorageMetadata>

aTask that will return the finalStorageMetadata once the operation is complete.

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2025-07-21 UTC.