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.

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.

Implementation is not thread-safe.

Since:

1.9

Author:

rmistry@google.com (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 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

Methods

Modifier and Type	Method and Description
int	getChunkSize() Returns the maximum size of individual chunks that will get uploaded by single HTTP requests.
GoogleHeaders	getInitiationHeaders() Returns the HTTP headers used for the initiation request.
HttpMethod	getInitiationMethod() Deprecated. (scheduled to be removed in 1.13) Use getInitiationRequestMethod() instead
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 uploaded by this uploader.
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.
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	setInitiationHeaders(GoogleHeaders initiationHeaders) Sets the HTTP headers used for the initiation request.
MediaHttpUploader	setInitiationMethod(HttpMethod initiationMethod) Deprecated. (scheduled to be removed in 1.13) Use setInitiationRequestMethod(java.lang.String) instead
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.
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

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.

Parameters:

mediaContent - The Input stream content of the media to be uploaded. The input stream received by calling AbstractInputStreamContent.getInputStream() is closed when the upload process is successfully completed. 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.

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

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

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.

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.

setInitiationMethod

@Deprecated
public MediaHttpUploader setInitiationMethod(HttpMethod initiationMethod)

Deprecated. (scheduled to be removed in 1.13) Use setInitiationRequestMethod(java.lang.String) instead

Sets the HTTP method used for the initiation request. Can only be HttpMethod.POST (for media upload) or HttpMethod.PUT (for media update). The default value is HttpMethod.POST.

getInitiationMethod

@Deprecated
public HttpMethod getInitiationMethod()

Deprecated. (scheduled to be removed in 1.13) Use getInitiationRequestMethod() instead

Returns the HTTP method used for the initiation request. The default value is HttpMethod.POST.

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(GoogleHeaders initiationHeaders)

Sets the HTTP headers used for the initiation request.

getInitiationHeaders

public GoogleHeaders getInitiationHeaders()

Returns the HTTP headers used for the initiation request.

getNumBytesUploaded

public long getNumBytesUploaded()

Gets the total number of bytes uploaded by this uploader.

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

Returns:

the upload progress

Throws:

IOException