com.google.api.client.googleapis.media

Class MediaHttpUploader

java.lang.Object

com.google.api.client.googleapis.media.MediaHttpUploader

public final class MediaHttpUploader
extends Object

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

For resumable uploads, when the media content length is known, if the provided InputStream has InputStream.markSupported() as false then it is wrapped in an BufferedInputStream to support the InputStream.mark(int) and InputStream.reset() methods required for handling server errors. If the media content length is unknown then each chunk is stored temporarily in memory. This is required to determine when the last chunk is reached.

Implementation is not thread-safe.

Since:

1.9

Author:

[email protected] (Ravi Mistry)

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	MediaHttpUploader.UploadState Upload state associated with the Media HTTP uploader.

Field Summary

Fields

Modifier and Type	Field and Description
static String	CONTENT_LENGTH_HEADER Upload content type header.
static String	CONTENT_TYPE_HEADER Upload content length header.
static int	DEFAULT_CHUNK_SIZE Default maximum number of bytes that will be uploaded to the server in any single HTTP request (set to 10 MB).
static int	MINIMUM_CHUNK_SIZE Minimum number of bytes that can be uploaded to the server (set to 256KB).

Constructor Summary

Constructors

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

Method Summary

Methods

Modifier and Type	Method and Description
int	getChunkSize() Returns the maximum size of individual chunks that will get uploaded by single HTTP requests.
boolean	getDisableGZipContent() Returns whether to disable GZip compression of HTTP content.
com.google.api.client.http.HttpHeaders	getInitiationHeaders() Returns the HTTP headers used for the initiation request.
String	getInitiationRequestMethod() Returns the HTTP method used for the initiation request.
com.google.api.client.http.HttpContent	getMediaContent() Returns the HTTP content of the media to be uploaded.
com.google.api.client.http.HttpContent	getMetadata() Returns HTTP content metadata for the media request or null for none.
long	getNumBytesUploaded() Gets the total number of bytes uploaded by this uploader or 0 for direct uploads when the content length is not known.
double	getProgress() Gets the upload progress denoting the percentage of bytes that have been uploaded, represented between 0.0 (0%) and 1.0 (100%).
MediaHttpUploaderProgressListener	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.
MediaHttpUploader.UploadState	getUploadState() Gets the current upload state of the uploader.
boolean	isBackOffPolicyEnabled() Returns whether the back off policy is enabled or disabled.
boolean	isDirectUploadEnabled() Returns whether direct media upload is enabled or disabled.
void	serverErrorCallback() The call back method that will be invoked by MediaUploadExponentialBackOffPolicy.getNextBackOffMillis() if it encounters a server error.
MediaHttpUploader	setBackOffPolicyEnabled(boolean backOffPolicyEnabled) Sets whether the back off policy is enabled or disabled.
MediaHttpUploader	setChunkSize(int chunkSize) Sets the maximum size of individual chunks that will get uploaded by single HTTP requests.
MediaHttpUploader	setDirectUploadEnabled(boolean directUploadEnabled) Sets whether direct media upload is enabled or disabled.
MediaHttpUploader	setDisableGZipContent(boolean disableGZipContent) Sets whether to disable GZip compression of HTTP content.
MediaHttpUploader	setInitiationHeaders(com.google.api.client.http.HttpHeaders initiationHeaders) Sets the HTTP headers used for the initiation request.
MediaHttpUploader	setInitiationRequestMethod(String initiationRequestMethod) Sets the HTTP method used for the initiation request.
MediaHttpUploader	setMetadata(com.google.api.client.http.HttpContent metadata) Sets HTTP content metadata for the media request or null for none.
MediaHttpUploader	setProgressListener(MediaHttpUploaderProgressListener progressListener) Sets the progress listener to send progress notifications to or null for none.
com.google.api.client.http.HttpResponse	upload(com.google.api.client.http.GenericUrl initiationRequestUrl) Executes a direct media upload or resumable media upload conforming to the specifications listed here.

Methods inherited from class java.lang.Object

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

Field Detail

CONTENT_LENGTH_HEADER

public static final String CONTENT_LENGTH_HEADER

Upload content type header.

Since:

1.13

See Also:

Constant Field Values

CONTENT_TYPE_HEADER

public static final String CONTENT_TYPE_HEADER

Upload content length header.

Since:

1.13

See Also:

Constant Field Values

MINIMUM_CHUNK_SIZE

public static final int MINIMUM_CHUNK_SIZE

Minimum number of bytes that can be uploaded to the server (set to 256KB).

See Also:

Constant Field Values

DEFAULT_CHUNK_SIZE

public static final int DEFAULT_CHUNK_SIZE

Default maximum number of bytes that will be uploaded to the server in any single HTTP request (set to 10 MB).

See Also:

Constant Field Values

Constructor Detail

MediaHttpUploader

public MediaHttpUploader(com.google.api.client.http.AbstractInputStreamContent mediaContent,
                 com.google.api.client.http.HttpTransport transport,
                 com.google.api.client.http.HttpRequestInitializer httpRequestInitializer)

Construct the MediaHttpUploader.

The input stream received by calling AbstractInputStreamContent.getInputStream() is closed when the upload process is successfully completed. For resumable uploads, when the media content length is known, if the input stream has InputStream.markSupported() as false then it is wrapped in an BufferedInputStream to support the InputStream.mark(int) and InputStream.reset() methods required for handling server errors. If the media content length is unknown then each chunk is stored temporarily in memory. This is required to determine when the last chunk is reached.

Parameters:

mediaContent - The Input stream content of the media to be uploaded

transport - The transport to use for requests

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

Method Detail

upload

public com.google.api.client.http.HttpResponse upload(com.google.api.client.http.GenericUrl initiationRequestUrl)
                                               throws IOException

Executes a direct media upload or resumable media upload conforming to the specifications listed here.

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

If an error is encountered during the request execution the caller is responsible for parsing the response correctly. For example for JSON errors:

    if (!response.isSuccessStatusCode()) {
      throw GoogleJsonResponseException.from(jsonFactory, response);
    }
 

Callers should call HttpResponse.disconnect() when the returned HTTP response object is no longer needed. However, HttpResponse.disconnect() does not have to be called if the response stream is properly closed. Example usage:

     HttpResponse response = batch.upload(initiationRequestUrl);
     try {
       // process the HTTP response object
     } finally {
       response.disconnect();
     }
 

Parameters:

initiationRequestUrl - The request URL where the initiation request will be sent

Returns:

HTTP response

Throws:

IOException

serverErrorCallback

public void serverErrorCallback()
                         throws IOException

The call back method that will be invoked by MediaUploadExponentialBackOffPolicy.getNextBackOffMillis() if it encounters a server error. This method should only be used as a call back method after upload(com.google.api.client.http.GenericUrl) is invoked.

This method will query the current status of the upload to find how many bytes were successfully uploaded before the server error occurred. It will then adjust the HTTP Request object used by the BackOffPolicy to contain the correct range header and media content chunk.

Throws:

IOException

getMetadata

public com.google.api.client.http.HttpContent getMetadata()

Returns HTTP content metadata for the media request or null for none.

setMetadata

public MediaHttpUploader setMetadata(com.google.api.client.http.HttpContent metadata)

Sets HTTP content metadata for the media request or null for none.

getMediaContent

public com.google.api.client.http.HttpContent getMediaContent()

Returns the HTTP content of the media to be uploaded.

getTransport

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

Returns the transport to use for requests.

setBackOffPolicyEnabled

public MediaHttpUploader setBackOffPolicyEnabled(boolean backOffPolicyEnabled)

Sets whether the back off policy is enabled or disabled. If value is set to false then server errors are not handled and the upload process will fail if a server error is encountered. Defaults to true.

isBackOffPolicyEnabled

public boolean isBackOffPolicyEnabled()

Returns whether the back off policy is enabled or disabled. If value is set to false then server errors are not handled and the upload process will fail if a server error is encountered. Defaults to true.

setDirectUploadEnabled

public MediaHttpUploader setDirectUploadEnabled(boolean directUploadEnabled)

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

Since:

1.9

isDirectUploadEnabled

public boolean isDirectUploadEnabled()

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

Since:

1.9

setProgressListener

public MediaHttpUploader setProgressListener(MediaHttpUploaderProgressListener progressListener)

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

getProgressListener

public MediaHttpUploaderProgressListener getProgressListener()

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

setChunkSize

public MediaHttpUploader setChunkSize(int chunkSize)

Sets the maximum size of individual chunks that will get uploaded by single HTTP requests. The default value is DEFAULT_CHUNK_SIZE.

The minimum allowable value is MINIMUM_CHUNK_SIZE and the specified chunk size must be a multiple of MINIMUM_CHUNK_SIZE.

Upgrade warning: Prior to version 1.13.0-beta setChunkSize(int) accepted any chunk size above MINIMUM_CHUNK_SIZE, it now accepts only multiples of MINIMUM_CHUNK_SIZE.

getChunkSize

public int getChunkSize()

Returns the maximum size of individual chunks that will get uploaded by single HTTP requests. The default value is DEFAULT_CHUNK_SIZE.

getDisableGZipContent

public boolean getDisableGZipContent()

Returns whether to disable GZip compression of HTTP content.

Since:

1.13

setDisableGZipContent

public MediaHttpUploader setDisableGZipContent(boolean disableGZipContent)

Sets whether to disable GZip compression of HTTP content.

By default it is false.

Since:

1.13

getInitiationRequestMethod

public String getInitiationRequestMethod()

Returns the HTTP method used for the initiation request.

The default value is HttpMethods.POST.

Since:

1.12

setInitiationRequestMethod

public MediaHttpUploader setInitiationRequestMethod(String initiationRequestMethod)

Sets the HTTP method used for the initiation request.

Can only be HttpMethods.POST (for media upload) or HttpMethods.PUT (for media update). The default value is HttpMethods.POST.

Since:

1.12

setInitiationHeaders

public MediaHttpUploader setInitiationHeaders(com.google.api.client.http.HttpHeaders initiationHeaders)

Sets the HTTP headers used for the initiation request.

Upgrade warning: in prior version 1.12 the initiation headers were of type GoogleHeaders, but as of version 1.13 that type is deprecated, so we now use type HttpHeaders.

getInitiationHeaders

public com.google.api.client.http.HttpHeaders getInitiationHeaders()

Returns the HTTP headers used for the initiation request.

Upgrade warning: in prior version 1.12 the initiation headers were of type GoogleHeaders, but as of version 1.13 that type is deprecated, so we now use type HttpHeaders.

getNumBytesUploaded

public long getNumBytesUploaded()

Gets the total number of bytes uploaded by this uploader or 0 for direct uploads when the content length is not known.

Returns:

the number of bytes uploaded

getUploadState

public MediaHttpUploader.UploadState getUploadState()

Gets the current upload state of the uploader.

Returns:

the upload state

getProgress

public double getProgress()
                   throws IOException

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

Do not use if the specified AbstractInputStreamContent has no content length specified. Instead, consider using getNumBytesUploaded() to denote progress.

Returns:

the upload progress

Throws:

IllegalArgumentException - if the specified AbstractInputStreamContent has no content length

IOException