com.google.api.client.googleapis
Class MediaHttpUploader

java.lang.Object
  com.google.api.client.googleapis.MediaHttpUploader

public final class MediaHttpUploader
extends Object

Media HTTP Uploader. Has support for resumable media uploads following the specifications listed here.

Implementation is not thread-safe.

Since:

1.7

Author:

[email protected] (Ravi Mistry)

Nested Class Summary

static class

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

Field Summary

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

MediaHttpUploader(AbstractInputStreamContent mediaContent, HttpTransport transport, HttpRequestInitializer httpRequestInitializer)
Construct the MediaHttpUploader.

Method Summary

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() 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.
void	serverErrorCallback() The call back method that will be invoked by MediaExponentialBackOffPolicy.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	setInitiationHeaders(GoogleHeaders initiationHeaders) Sets the HTTP headers used for the initiation request.
MediaHttpUploader	setInitiationMethod(HttpMethod initiationMethod) 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 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

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

Parameters:

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

Returns:

HTTP request

Throws:

IOException

serverErrorCallback

public void serverErrorCallback()
                         throws IOException

The call back method that will be invoked by MediaExponentialBackOffPolicy.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.

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

public MediaHttpUploader setInitiationMethod(HttpMethod initiationMethod)

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

public HttpMethod getInitiationMethod()

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

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