com.google.api.client.googleapis.media

Class MediaHttpDownloader

java.lang.Object

com.google.api.client.googleapis.media.MediaHttpDownloader

public final class MediaHttpDownloader
extends Object

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(com.google.api.client.http.HttpUnsuccessfulResponseHandler) with a new HttpBackOffUnsuccessfulResponseHandler instance and HttpRequest.setIOExceptionHandler(com.google.api.client.http.HttpIOExceptionHandler) 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.

Since:

1.9

Author:

rmistry@google.com (Ravi Mistry)

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	MediaHttpDownloader.DownloadState Download state associated with the Media HTTP downloader.

Field Summary

Fields

Modifier and Type	Field and Description
static int	MAXIMUM_CHUNK_SIZE Default maximum number of bytes that will be downloaded from the server in any single HTTP request.

Constructor Summary

Constructors

Constructor and Description
MediaHttpDownloader(com.google.api.client.http.HttpTransport transport, com.google.api.client.http.HttpRequestInitializer httpRequestInitializer) Construct the MediaHttpDownloader.

Method Summary

Modifier and Type	Method and Description
void	download(com.google.api.client.http.GenericUrl requestUrl, com.google.api.client.http.HttpHeaders requestHeaders, OutputStream outputStream) Executes a direct media download or a resumable media download.
void	download(com.google.api.client.http.GenericUrl requestUrl, OutputStream outputStream) Executes a direct media download or a resumable media download.
int	getChunkSize() Returns the maximum size of individual chunks that will get downloaded by single HTTP requests.
MediaHttpDownloader.DownloadState	getDownloadState() Gets the current download state of the downloader.
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.
long	getNumBytesDownloaded() Gets the total number of bytes downloaded by this downloader.
double	getProgress() Gets the download progress denoting the percentage of bytes that have been downloaded, represented between 0.0 (0%) and 1.0 (100%).
MediaHttpDownloaderProgressListener	getProgressListener() Returns the progress listener to send progress notifications to or null for none.
com.google.api.client.http.HttpTransport	getTransport() Returns the transport to use for requests.
boolean	isDirectDownloadEnabled() Returns whether direct media download is enabled or disabled.
MediaHttpDownloader	setBytesDownloaded(long bytesDownloaded) Sets the total number of bytes that have been downloaded of the media resource.
MediaHttpDownloader	setChunkSize(int chunkSize) Sets the maximum size of individual chunks that will get downloaded by single HTTP requests.
MediaHttpDownloader	setContentRange(long firstBytePos, int lastBytePos) Deprecated. Use setContentRange(long, long) instead.
MediaHttpDownloader	setContentRange(long firstBytePos, long lastBytePos) Sets the content range of the next download request.
MediaHttpDownloader	setDirectDownloadEnabled(boolean directDownloadEnabled) Returns whether direct media download is enabled or disabled.
MediaHttpDownloader	setProgressListener(MediaHttpDownloaderProgressListener progressListener) Sets the progress listener to send progress notifications to or null for none.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

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.

See Also:

Constant Field Values

Constructor Detail

MediaHttpDownloader

public MediaHttpDownloader(com.google.api.client.http.HttpTransport transport,
                           com.google.api.client.http.HttpRequestInitializer httpRequestInitializer)

Construct the MediaHttpDownloader.

Parameters:

transport - The transport to use for requests

httpRequestInitializer - The initializer to use when creating an HttpRequest or null for none

Method Detail

download

public void download(com.google.api.client.http.GenericUrl requestUrl,
                     OutputStream outputStream)
              throws IOException

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:

requestUrl - The request URL where the download requests will be sent

outputStream - destination output stream

Throws:

IOException

download

public void download(com.google.api.client.http.GenericUrl requestUrl,
                     com.google.api.client.http.HttpHeaders requestHeaders,
                     OutputStream outputStream)
              throws IOException

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:

requestUrl - request URL where the download requests will be sent

requestHeaders - request headers or null to ignore

outputStream - destination output stream

Throws:

IOException

Since:

1.12

setBytesDownloaded

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(long, long) if you need to specify both the bytes downloaded and the last byte position.

Parameters:

bytesDownloaded - The total number of bytes downloaded

setContentRange

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(long) if you only need to specify the first byte position.

Parameters:

firstBytePos - The first byte position in the content range string

lastBytePos - The last byte position in the content range string.

Since:

1.24

setContentRange

@Deprecated
public MediaHttpDownloader setContentRange(long firstBytePos,
                                                       int lastBytePos)

Deprecated. Use setContentRange(long, long) instead.

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.

setDirectDownloadEnabled

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.

setProgressListener

public MediaHttpDownloader setProgressListener(MediaHttpDownloaderProgressListener progressListener)

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

getProgressListener

public MediaHttpDownloaderProgressListener getProgressListener()

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

getTransport

public com.google.api.client.http.HttpTransport getTransport()

Returns the transport to use for requests.

setChunkSize

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.

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.

getNumBytesDownloaded

public long getNumBytesDownloaded()

Gets the total number of bytes downloaded by this downloader.

Returns:

the number of bytes downloaded

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:

the last byte position

Since:

1.13

getDownloadState

public MediaHttpDownloader.DownloadState getDownloadState()

Gets the current download state of the downloader.

Returns:

the download state

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:

the download progress