Class MediaHttpDownloader (2.5.0)

Version 2.5.0

• 2.7.0 (latest)
• 2.6.0
• 2.5.1
• 2.4.1
• 2.1.2
• 2.0.1
• 1.35.2
• 1.34.1
• 1.33.4

public final class MediaHttpDownloader

Media HTTP Downloader, with support for both direct and resumable media downloads. Documentation is available here.

Implementation is not thread-safe.

Back-off is disabled by default. To enable it for an abnormal HTTP response and an I/O exception you should call HttpRequest#setUnsuccessfulResponseHandler with a new HttpBackOffUnsuccessfulResponseHandler instance and HttpRequest#setIOExceptionHandler with HttpBackOffIOExceptionHandler.

Upgrade warning: in prior version 1.14 exponential back-off was enabled by default for an abnormal HTTP response. Starting with version 1.15 it's disabled by default.

Inheritance

java.lang.Object > MediaHttpDownloader

Inherited Members

Object.clone()

Object.equals(Object)

Object.finalize()

Object.getClass()

Object.hashCode()

Object.notify()

Object.notifyAll()

Object.toString()

Object.wait()

Object.wait(long)

Object.wait(long,int)

Static Fields

MAXIMUM_CHUNK_SIZE

public static final int MAXIMUM_CHUNK_SIZE

Default maximum number of bytes that will be downloaded from the server in any single HTTP request. Set to 32MB because that is the maximum App Engine request size.

Field Value
Type	Description
int

Constructors

MediaHttpDownloader(HttpTransport transport, HttpRequestInitializer httpRequestInitializer)

public MediaHttpDownloader(HttpTransport transport, HttpRequestInitializer httpRequestInitializer)

Construct the MediaHttpDownloader.

Parameters
Name	Description
transport	com.google.api.client.http.HttpTransport The transport to use for requests
httpRequestInitializer	com.google.api.client.http.HttpRequestInitializer The initializer to use when creating an HttpRequest or null for none

Methods

download(GenericUrl requestUrl, HttpHeaders requestHeaders, OutputStream outputStream)

public void download(GenericUrl requestUrl, HttpHeaders requestHeaders, OutputStream outputStream)

Executes a direct media download or a resumable media download.

This method does not close the given output stream.

This method is not reentrant. A new instance of MediaHttpDownloader must be instantiated before download called be called again.

Parameters
Name	Description
requestUrl	com.google.api.client.http.GenericUrl request URL where the download requests will be sent
requestHeaders	com.google.api.client.http.HttpHeaders request headers or null to ignore
outputStream	OutputStream destination output stream

Exceptions
Type	Description
IOException

download(GenericUrl requestUrl, OutputStream outputStream)

public void download(GenericUrl requestUrl, OutputStream outputStream)

Executes a direct media download or a resumable media download.

This method does not close the given output stream.

This method is not reentrant. A new instance of MediaHttpDownloader must be instantiated before download called be called again.

Parameters
Name	Description
requestUrl	com.google.api.client.http.GenericUrl The request URL where the download requests will be sent
outputStream	OutputStream destination output stream

Exceptions
Type	Description
IOException

getChunkSize()

public int getChunkSize()

Returns the maximum size of individual chunks that will get downloaded by single HTTP requests. The default value is #MAXIMUM_CHUNK_SIZE.

Returns
Type	Description
int

getDownloadState()

public MediaHttpDownloader.DownloadState getDownloadState()

Gets the current download state of the downloader.

Returns
Type	Description
MediaHttpDownloader.DownloadState	the download state

getLastBytePosition()

public long getLastBytePosition()

Gets the last byte position of the media file we want to download or -1 if there is no upper limit on the byte position.

Returns
Type	Description
long	the last byte position

getNumBytesDownloaded()

public long getNumBytesDownloaded()

Gets the total number of bytes downloaded by this downloader.

Returns
Type	Description
long	the number of bytes downloaded

getProgress()

public double getProgress()

Gets the download progress denoting the percentage of bytes that have been downloaded, represented between 0.0 (0%) and 1.0 (100%).

Returns
Type	Description
double	the download progress

getProgressListener()

public MediaHttpDownloaderProgressListener getProgressListener()

Returns the progress listener to send progress notifications to or null for none.

Returns
Type	Description
MediaHttpDownloaderProgressListener

getTransport()

public HttpTransport getTransport()

Returns the transport to use for requests.

Returns
Type	Description
com.google.api.client.http.HttpTransport

isDirectDownloadEnabled()

public boolean isDirectDownloadEnabled()

Returns whether direct media download is enabled or disabled. If value is set to true then a direct download will be done where the whole media content is downloaded in a single request. If value is set to false then the download uses the resumable media download protocol to download in data chunks. Defaults to false.

Returns
Type	Description
boolean

setBytesDownloaded(long bytesDownloaded)

public MediaHttpDownloader setBytesDownloaded(long bytesDownloaded)

Sets the total number of bytes that have been downloaded of the media resource.

If a download was aborted mid-way due to a connection failure then users can resume the download from the point where it left off.

Use #setContentRange if you need to specify both the bytes downloaded and the last byte position.

Parameter
Name	Description
bytesDownloaded	long The total number of bytes downloaded

Returns
Type	Description
MediaHttpDownloader

setChunkSize(int chunkSize)

public MediaHttpDownloader setChunkSize(int chunkSize)

Sets the maximum size of individual chunks that will get downloaded by single HTTP requests. The default value is #MAXIMUM_CHUNK_SIZE.

The maximum allowable value is #MAXIMUM_CHUNK_SIZE.

Parameter
Name	Description
chunkSize	int

Returns
Type	Description
MediaHttpDownloader

setContentRange(long firstBytePos, int lastBytePos) (deprecated)

public MediaHttpDownloader setContentRange(long firstBytePos, int lastBytePos)

Deprecated. Use #setContentRange(long, long) instead.

Parameters
Name	Description
firstBytePos	long
lastBytePos	int

Returns
Type	Description
MediaHttpDownloader

setContentRange(long firstBytePos, long lastBytePos)

public MediaHttpDownloader setContentRange(long firstBytePos, long lastBytePos)

Sets the content range of the next download request. Eg: bytes=firstBytePos-lastBytePos.

If a download was aborted mid-way due to a connection failure then users can resume the download from the point where it left off.

Use #setBytesDownloaded if you only need to specify the first byte position.

Parameters
Name	Description
firstBytePos	long The first byte position in the content range string
lastBytePos	long The last byte position in the content range string.

Returns
Type	Description
MediaHttpDownloader

setDirectDownloadEnabled(boolean directDownloadEnabled)

public MediaHttpDownloader setDirectDownloadEnabled(boolean directDownloadEnabled)

Returns whether direct media download is enabled or disabled. If value is set to true then a direct download will be done where the whole media content is downloaded in a single request. If value is set to false then the download uses the resumable media download protocol to download in data chunks. Defaults to false.

Parameter
Name	Description
directDownloadEnabled	boolean

Returns
Type	Description
MediaHttpDownloader

setProgressListener(MediaHttpDownloaderProgressListener progressListener)

public MediaHttpDownloader setProgressListener(MediaHttpDownloaderProgressListener progressListener)

Sets the progress listener to send progress notifications to or null for none.

Parameter
Name	Description
progressListener	MediaHttpDownloaderProgressListener

Returns
Type	Description
MediaHttpDownloader