public class

ResumableHttpFileUploader

extends Object
java.lang.Object
   ↳ com.google.gdata.client.uploader.ResumableHttpFileUploader
Known Direct Subclasses

Class Overview

Uploads a file using resumable HTTP requests (see http://code.google.com/p/gears/wiki/ResumableHttpRequestsProposal). This implementation supports time based progress notifications, polling for progress, resumability, and completion notifications. Each instance creates a separate task (to be executed by an ExecutorService), which actually generates the HTTP request and writes bytes to the server. The task blocks a thread spawned by the ExecutorService) for the duration of the upload (i.e., until the upload is either completed, paused, or an error occurs). This frees the current thread from blocking, which allows various non-blocking interaction with the uploader (like polling for progress, preventing UI from being blocked, etc.).

Summary

Nested Classes
class ResumableHttpFileUploader.Builder Builder class for constructing ResumableHttpFileUploader instances. 
enum ResumableHttpFileUploader.RequestMethod Http request type to use in upload requests. 
class ResumableHttpFileUploader.ResponseMessage The response message returned by the upload task when it has finished uploading the last chunk. 
enum ResumableHttpFileUploader.UploadState Upload state associated with this file uploader. 
Constants
long DEFAULT_PROGRESS_INTERVAL_MS Default number of milliseconds for the progress notification interval.
String METHOD_OVERRIDE Method-override http header.
Fields
public static long DEFAULT_MAX_CHUNK_SIZE Default maximum number of bytes that will be uploaded to the server in any single HTTP request (set to 10 MB).
private final BackoffPolicy backoffPolicy Back off policy which determines the amount of time to wait before retrying an HTTP request.
private final long chunkSize Maximum size of individual chunks that will get uploaded by single HTTP requests.
private final UploadData data The file to upload.
private final ExecutorService executor Executor service to execute asynchronous upload tasks.
private Map<String, String> headers Extra http headers to send in each request.
private ResumableHttpFileUploader.RequestMethod httpRequestMethod HTTP request method to use when uploading.
private long numBytesUploaded Number of bytes that have been successfully uploaded to the server by this uploader.
private final long progressIntervalMillis Number of milliseconds between progress listener notifications.
private final ProgressListener progressListener Progress listener interface instance to send progress notifications to.
private Timer progressNotifier Timer for sending progress notifications on a fixed time interval.
private Future<ResumableHttpFileUploader.ResponseMessage> uploadResultFuture The future which will contain the eventual response stream from the upload server.
private ResumableHttpFileUploader.UploadState uploadState The current state of the uploader.
private URL url The URL which locates the destination of the upload.
private final UrlConnectionFactory urlConnectionFactory Factory for creating HTTP connections.
Public Constructors
ResumableHttpFileUploader(URL url, File file, ExecutorService executor, ProgressListener progressListener, long progressIntervalMillis)
This constructor is deprecated. Please use ResumableHttpFileUploader.Builder
ResumableHttpFileUploader(URL url, File file, ExecutorService executor, ProgressListener progressListener, long chunkSize, long progressIntervalMillis)
This constructor is deprecated. Please use ResumableHttpFileUploader.Builder
Public Methods
String addHeader(String key, String value)
Add a http header to send in each of the upload requests.
UploadData getData()
Gets the file associated with this uploader.
ResumableHttpFileUploader.RequestMethod getHttpRequestMethod()
Returns the http request method to use for upload.
synchronized 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 and 1.0 (100%).
ResumableHttpFileUploader.ResponseMessage getResponse()
Gets the response from the server if it is available.
synchronized ResumableHttpFileUploader.UploadState getUploadState()
Gets the current upload state of the uploader.
synchronized boolean isDone()
Identifies if the upload task has completed
synchronized boolean isPaused()
Identifies if the uploader is paused
synchronized void pause()
Causes the uploader to pause uploading.
void resume()
Resumes an upload if it is currently paused, or if it has not yet started.
void setHttpRequestMethod(ResumableHttpFileUploader.RequestMethod requestMethod)
This method is deprecated. Please use setRequestMethod(RequestMethod)
Future<ResumableHttpFileUploader.ResponseMessage> start()
Starts an upload beginning with the first byte in the file.
[Expand]
Inherited Methods
From class java.lang.Object

Constants

public static final long DEFAULT_PROGRESS_INTERVAL_MS

Default number of milliseconds for the progress notification interval.

Constant Value: 100 (0x0000000000000064)

public static final String METHOD_OVERRIDE

Method-override http header.

Constant Value: "X-HTTP-Method-Override"

Fields

public static long DEFAULT_MAX_CHUNK_SIZE

Default maximum number of bytes that will be uploaded to the server in any single HTTP request (set to 10 MB).

private final BackoffPolicy backoffPolicy

Back off policy which determines the amount of time to wait before retrying an HTTP request.

private final long chunkSize

Maximum size of individual chunks that will get uploaded by single HTTP requests.

private final UploadData data

The file to upload.

private final ExecutorService executor

Executor service to execute asynchronous upload tasks.

private Map<String, String> headers

Extra http headers to send in each request.

private ResumableHttpFileUploader.RequestMethod httpRequestMethod

HTTP request method to use when uploading.

private long numBytesUploaded

Number of bytes that have been successfully uploaded to the server by this uploader.

private final long progressIntervalMillis

Number of milliseconds between progress listener notifications.

private final ProgressListener progressListener

Progress listener interface instance to send progress notifications to.

private Timer progressNotifier

Timer for sending progress notifications on a fixed time interval.

private Future<ResumableHttpFileUploader.ResponseMessage> uploadResultFuture

The future which will contain the eventual response stream from the upload server.

private ResumableHttpFileUploader.UploadState uploadState

The current state of the uploader.

private URL url

The URL which locates the destination of the upload.

private final UrlConnectionFactory urlConnectionFactory

Factory for creating HTTP connections.

Public Constructors

public ResumableHttpFileUploader (URL url, File file, ExecutorService executor, ProgressListener progressListener, long progressIntervalMillis)

This constructor is deprecated.
Please use ResumableHttpFileUploader.Builder

Constructs a new uploader that uses the default maximum chunk size per HTTP request.

Parameters
url Which locates the destination of the upload request
file Containing bytes to send to the server
executor Service to execute asynchronous upload tasks with
progressListener For receiving progress notifications
progressIntervalMillis Number of milliseconds between progress listener notifications
Throws
IOException if the file is not readable or does not exist

public ResumableHttpFileUploader (URL url, File file, ExecutorService executor, ProgressListener progressListener, long chunkSize, long progressIntervalMillis)

This constructor is deprecated.
Please use ResumableHttpFileUploader.Builder

Constructs a new uploader with configurable chunk size to use per HTTP request.

Parameters
url Which locates the destination of the upload request
file Containing bytes to send to the server
executor Service to execute asynchronous upload tasks with
progressListener For receiving progress notifications
chunkSize Size of the chunks that will get uploaded by individual HTTP requests
progressIntervalMillis Number of milliseconds between progress listener notifications
Throws
IOException if the file is not readable or does not exist

Public Methods

public String addHeader (String key, String value)

Add a http header to send in each of the upload requests.

Parameters
key Http header name
value Http header value
Returns
  • old value if any

public UploadData getData ()

Gets the file associated with this uploader.

Returns
  • the file to upload

public ResumableHttpFileUploader.RequestMethod getHttpRequestMethod ()

Returns the http request method to use for upload.

public synchronized long getNumBytesUploaded ()

Gets the total number of bytes uploaded by this uploader.

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 and 1.0 (100%).

Returns
  • the upload progress

public ResumableHttpFileUploader.ResponseMessage getResponse ()

Gets the response from the server if it is available. If the stream is not yet available, null is returned.

Returns
  • the stream containing the response from the server

public synchronized ResumableHttpFileUploader.UploadState getUploadState ()

Gets the current upload state of the uploader.

Returns
  • the upload state

public synchronized boolean isDone ()

Identifies if the upload task has completed

Returns
  • true if the uploader is done

public synchronized boolean isPaused ()

Identifies if the uploader is paused

Returns
  • true if the uploader is paused

public synchronized void pause ()

Causes the uploader to pause uploading. The uploader may be resumed later by calling resume(). This method does not block.

public void resume ()

Resumes an upload if it is currently paused, or if it has not yet started. This should be called if the server has received some bytes for the file. Note that it causes an extra HTTP request to be sent to the server in order to determine the offset at which the uploader should begin sending bytes. This method does not block.

public void setHttpRequestMethod (ResumableHttpFileUploader.RequestMethod requestMethod)

This method is deprecated.
Please use setRequestMethod(RequestMethod)

Set the http request type for upload. Resumable upload can accept either PUT request or POST request with x-http-method-override header set to PUT.

Parameters
requestMethod Http request type

public Future<ResumableHttpFileUploader.ResponseMessage> start ()

Starts an upload beginning with the first byte in the file. This method does not block.

Returns
  • future to access upload result