MediaHttpUploader (google-api-java-client 2.1.1)

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

Since:

1.9

Author:

rmistry@google.com (Ravi Mistry), peleyal@google.com (Eyal Peled)

Nested Class Summary

Nested Classes
Modifier and Type Class and Description

static class MediaHttpUploader.UploadState
Upload state associated with the Media HTTP uploader.

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(AbstractInputStreamContent mediaContent, HttpTransport transport, HttpRequestInitializer httpRequestInitializer)` Construct the `MediaHttpUploader`.

Method Summary

All Methods Instance Methods Concrete 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.
`HttpHeaders`	`getInitiationHeaders()` Returns the HTTP headers used for the initiation request.
`String`	`getInitiationRequestMethod()` Returns the HTTP method used for the initiation request.
`HttpContent`	`getMediaContent()` Returns the HTTP content of the media to be uploaded.
`HttpContent`	`getMetadata()` Returns HTTP content metadata for the media request or `null` for none.
`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.
`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.
`Sleeper`	`getSleeper()` Returns the sleeper.
`HttpTransport`	`getTransport()` Returns the transport to use for requests.
`MediaHttpUploader.UploadState`	`getUploadState()` Gets the current upload state of the uploader.
`boolean`	`isDirectUploadEnabled()` Returns whether direct media upload 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(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(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.
`MediaHttpUploader`	`setSleeper(Sleeper sleeper)` Sets the sleeper.
`HttpResponse`	`upload(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(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(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 HttpResponse upload(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
  - getMetadata
```
public HttpContent getMetadata()
```
    Returns HTTP content metadata for the media request or null for none.
  - setMetadata
```
public MediaHttpUploader setMetadata(HttpContent metadata)
```
    Sets HTTP content metadata for the media request or null for none.
  - getMediaContent
```
public HttpContent getMediaContent()
```
    Returns the HTTP content of the media to be uploaded.
  - getTransport
```
public HttpTransport getTransport()
```
    Returns the transport to use for requests.
  - 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.
    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.
    
    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.
  - 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.
    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.
    
    Since:
    
    1.13
  - getSleeper
```
public Sleeper getSleeper()
```
    Returns the sleeper.
    
    Since:
    
    1.15
  - setSleeper
```
public MediaHttpUploader setSleeper(Sleeper sleeper)
```
    Sets the sleeper. The default value is Sleeper.DEFAULT.
    
    Since:
    
    1.15
  - 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(HttpHeaders initiationHeaders)
```
    Sets the HTTP headers used for the initiation request.
  - getInitiationHeaders
```
public HttpHeaders getInitiationHeaders()
```
    Returns the HTTP headers used for the initiation request.
  - 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:
    
    the number of bytes the server received so far
  - 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

Class MediaHttpUploader

Nested Class Summary

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

CONTENT_LENGTH_HEADER

CONTENT_TYPE_HEADER

MINIMUM_CHUNK_SIZE

DEFAULT_CHUNK_SIZE

Constructor Detail

MediaHttpUploader

Method Detail

upload

getMetadata

setMetadata

getMediaContent

getTransport

setDirectUploadEnabled

isDirectUploadEnabled

setProgressListener

getProgressListener

setChunkSize

getChunkSize

getDisableGZipContent

setDisableGZipContent

getSleeper

setSleeper

getInitiationRequestMethod

setInitiationRequestMethod

setInitiationHeaders

getInitiationHeaders

getNumBytesUploaded

getUploadState

getProgress