Class MediaHttpUploader (2.1.2)

public final class MediaHttpUploader

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 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.

See #setDisableGZipContent(boolean) for information on when content is gzipped and how to control that behavior.

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 and there was a regular retry (without back-off) when I/O exception was thrown. Starting with version 1.15 back-off is disabled and there is no retry on I/O exception by default.

Upgrade warning: in prior version 1.16 #serverErrorCallback was public but starting with version 1.17 it has been removed from the public API, and changed to be package private.

Implementation is not thread-safe.

Inheritance

java.lang.Object > MediaHttpUploader

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

CONTENT_LENGTH_HEADER

public static final String CONTENT_LENGTH_HEADER

Upload content type header.

Field Value
Type	Description
`String`

CONTENT_TYPE_HEADER

public static final String CONTENT_TYPE_HEADER

Upload content length header.

Field Value
Type	Description
`String`

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).

Field Value
Type	Description
`int`

MINIMUM_CHUNK_SIZE

public static final int MINIMUM_CHUNK_SIZE

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

Field Value
Type	Description
`int`

Constructors

MediaHttpUploader(AbstractInputStreamContent mediaContent, HttpTransport transport, HttpRequestInitializer httpRequestInitializer)

public MediaHttpUploader(AbstractInputStreamContent mediaContent, HttpTransport transport, 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 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
Name	Description
`mediaContent`	`com.google.api.client.http.AbstractInputStreamContent` The Input stream content of the media to be uploaded
`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

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.

Returns
Type	Description
`int`

getDisableGZipContent()

public boolean getDisableGZipContent()

Returns whether to disable GZip compression of HTTP content.

Returns
Type	Description
`boolean`

getInitiationHeaders()

public HttpHeaders getInitiationHeaders()

Returns the HTTP headers used for the initiation request.

Returns
Type	Description
`com.google.api.client.http.HttpHeaders`

getInitiationRequestMethod()

public String getInitiationRequestMethod()

Returns the HTTP method used for the initiation request.

The default value is HttpMethods#POST.

Returns
Type	Description
`String`

getMediaContent()

public HttpContent getMediaContent()

Returns the HTTP content of the media to be uploaded.

Returns
Type	Description
`com.google.api.client.http.HttpContent`

getMetadata()

public HttpContent getMetadata()

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

Returns
Type	Description
`com.google.api.client.http.HttpContent`

getNumBytesUploaded()

public long getNumBytesUploaded()

Gets the total number of bytes the server received so far or 0 for direct uploads when the content length is not known.

Returns
Type	Description
`long`	the number of bytes the server received so far

getProgress()

public double getProgress()

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
Type	Description
`double`	the upload progress

Exceptions
Type	Description
`IOException`	if the specified AbstractInputStreamContent has no content length

getProgressListener()

public MediaHttpUploaderProgressListener getProgressListener()

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

Returns
Type	Description
`MediaHttpUploaderProgressListener`

getSleeper()

public Sleeper getSleeper()

Returns the sleeper.

Returns
Type	Description
`com.google.api.client.util.Sleeper`

getTransport()

public HttpTransport getTransport()

Returns the transport to use for requests.

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

getUploadState()

public MediaHttpUploader.UploadState getUploadState()

Gets the current upload state of the uploader.

Returns
Type	Description
`MediaHttpUploader.UploadState`	the upload state

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.

Returns
Type	Description
`boolean`

setChunkSize(int chunkSize)

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.

Parameter
Name	Description
`chunkSize`	`int`

Returns
Type	Description
`MediaHttpUploader`

setDirectUploadEnabled(boolean directUploadEnabled)

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.

Direct upload is recommended if the content size falls below a certain minimum limit. This is because there's minimum block write size for some Google APIs, so if the resumable request fails in the space of that first block, the client will have to restart from the beginning anyway.

Defaults to false.

Parameter
Name	Description
`directUploadEnabled`	`boolean`

Returns
Type	Description
`MediaHttpUploader`

setDisableGZipContent(boolean disableGZipContent)

public MediaHttpUploader setDisableGZipContent(boolean disableGZipContent)

Sets whether to disable GZip compression of HTTP content.

By default it is false.

If #setDisableGZipContent(boolean) is set to false (the default value) then content is gzipped for direct media upload and resumable media uploads when content length is not known. Due to a current limitation, content is not gzipped for resumable media uploads when content length is known; this limitation will be removed in the future.

Parameter
Name	Description
`disableGZipContent`	`boolean`

Returns
Type	Description
`MediaHttpUploader`

setInitiationHeaders(HttpHeaders initiationHeaders)

public MediaHttpUploader setInitiationHeaders(HttpHeaders initiationHeaders)

Sets the HTTP headers used for the initiation request.

Parameter
Name	Description
`initiationHeaders`	`com.google.api.client.http.HttpHeaders`

Returns
Type	Description
`MediaHttpUploader`

setInitiationRequestMethod(String initiationRequestMethod)

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.

Parameter
Name	Description
`initiationRequestMethod`	`String`

Returns
Type	Description
`MediaHttpUploader`

setMetadata(HttpContent metadata)

public MediaHttpUploader setMetadata(HttpContent metadata)

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

Parameter
Name	Description
`metadata`	`com.google.api.client.http.HttpContent`

Returns
Type	Description
`MediaHttpUploader`

setProgressListener(MediaHttpUploaderProgressListener progressListener)

public MediaHttpUploader setProgressListener(MediaHttpUploaderProgressListener progressListener)

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

Parameter
Name	Description
`progressListener`	`MediaHttpUploaderProgressListener`

Returns
Type	Description
`MediaHttpUploader`

setSleeper(Sleeper sleeper)

public MediaHttpUploader setSleeper(Sleeper sleeper)

Sets the sleeper. The default value is Sleeper#DEFAULT.

Parameter
Name	Description
`sleeper`	`com.google.api.client.util.Sleeper`

Returns
Type	Description
`MediaHttpUploader`

upload(GenericUrl initiationRequestUrl)

public HttpResponse upload(GenericUrl initiationRequestUrl)

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();
 }

Parameter
Name	Description
`initiationRequestUrl`	`com.google.api.client.http.GenericUrl` The request URL where the initiation request will be sent

Returns
Type	Description
`com.google.api.client.http.HttpResponse`	HTTP response

Exceptions
Type	Description
`IOException`