public class

MediaHttpUploader

extends Object
java.lang.Object
   ↳ com.kinvey.java.core.MediaHttpUploader

Class Overview

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 markSupported() as false then it is wrapped in an BufferedInputStream to support the mark(int) and 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.

Implementation is not thread-safe.

Summary

Nested Classes
enum MediaHttpUploader.UploadState Upload state associated with the Media HTTP uploader. 
class MediaHttpUploader.UploadUrlResponse This class is deprecated. No replacement. 
Constants
String CONTENT_LENGTH_HEADER Upload content type header.
String CONTENT_TYPE_HEADER Upload content length header.
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).
int MINIMUM_CHUNK_SIZE Minimum number of bytes that can be uploaded to the server (set to 256KB).
Public Constructors
MediaHttpUploader(AbstractInputStreamContent mediaContent, HttpTransport transport, HttpRequestInitializer httpRequestInitializer)
Construct the MediaHttpUploader.
Public Methods
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 uploaded by this uploader 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%).
UploaderProgressListener 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.
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 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(UploaderProgressListener progressListener)
Sets the progress listener to send progress notifications to or null for none.
HttpResponse upload(AbstractKinveyClientRequest initiationClientRequest)
Executes a direct media upload or resumable media upload conforming to the specifications listed here.
[Expand]
Inherited Methods
From class java.lang.Object

Constants

public static final String CONTENT_LENGTH_HEADER

Upload content type header.

Constant Value: "X-Upload-Content-Length"

public static final String CONTENT_TYPE_HEADER

Upload content length header.

Constant Value: "X-Upload-Content-Type"

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

Constant Value: 10485760 (0x00a00000)

public static final int MINIMUM_CHUNK_SIZE

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

Constant Value: 262144 (0x00040000)

Public Constructors

public MediaHttpUploader (AbstractInputStreamContent mediaContent, HttpTransport transport, HttpRequestInitializer httpRequestInitializer)

Construct the MediaHttpUploader.

The input stream received by calling 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 markSupported() as false then it is wrapped in an BufferedInputStream to support the mark(int) and 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

Public Methods

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.

public boolean getDisableGZipContent ()

Returns whether to disable GZip compression of HTTP content.

public HttpHeaders getInitiationHeaders ()

Returns the HTTP headers used for the initiation request.

Upgrade warning: in prior version 1.12 the initiation headers were of type GoogleHeaders, but as of version 1.13 that type is deprecated, so we now use type HttpHeaders.

public String getInitiationRequestMethod ()

Returns the HTTP method used for the initiation request.

The default value is POST.

public HttpContent getMediaContent ()

Returns the HTTP content of the media to be uploaded.

public HttpContent getMetadata ()

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

public long getNumBytesUploaded ()

Gets the total number of bytes uploaded by this uploader or 0 for direct uploads when the content length is not known.

Returns
  • the number of bytes uploaded

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
  • the upload progress
Throws
IllegalArgumentException if the specified AbstractInputStreamContent has no content length
IOException

public UploaderProgressListener getProgressListener ()

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

public HttpTransport getTransport ()

Returns the transport to use for requests.

public MediaHttpUploader.UploadState getUploadState ()

Gets the current upload state of the uploader.

Returns
  • the upload state

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.

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.

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.

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.

Upgrade warning: Prior to version 1.13.0-beta setChunkSize(int) accepted any chunk size above MINIMUM_CHUNK_SIZE, it now accepts only multiples of MINIMUM_CHUNK_SIZE.

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.

public MediaHttpUploader setDisableGZipContent (boolean disableGZipContent)

Sets whether to disable GZip compression of HTTP content.

By default it is false.

public MediaHttpUploader setInitiationHeaders (HttpHeaders initiationHeaders)

Sets the HTTP headers used for the initiation request.

Upgrade warning: in prior version 1.12 the initiation headers were of type GoogleHeaders, but as of version 1.13 that type is deprecated, so we now use type HttpHeaders.

public MediaHttpUploader setInitiationRequestMethod (String initiationRequestMethod)

Sets the HTTP method used for the initiation request.

Can only be POST (for media upload) or PUT (for media update). The default value is POST.

public MediaHttpUploader setMetadata (HttpContent metadata)

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

public MediaHttpUploader setProgressListener (UploaderProgressListener progressListener)

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

public HttpResponse upload (AbstractKinveyClientRequest initiationClientRequest)

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 disconnect() when the returned HTTP response object is no longer needed. However, 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();
     }
 

Returns
  • HTTP response
Throws
IOException