Overview  Package   Class  Use  Tree  Deprecated  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

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

java.lang.Object
  extended by 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:
[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.
 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)
          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

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
Overview  Package   Class  Use  Tree  Deprecated  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Copyright © 2010-2012 Google. All Rights Reserved.