com.google.gdata.client.uploader

Class ResumableHttpFileUploader

java.lang.Object

com.google.gdata.client.uploader.ResumableHttpFileUploader

Direct Known Subclasses:

ResumableGDataFileUploader

public class ResumableHttpFileUploader
extends Object

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

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	ResumableHttpFileUploader.Builder Builder class for constructing ResumableHttpFileUploader instances.
static class	ResumableHttpFileUploader.RequestMethod Http request type to use in upload requests.
static class	ResumableHttpFileUploader.ResponseMessage The response message returned by the upload task when it has finished uploading the last chunk.
static class	ResumableHttpFileUploader.UploadState Upload state associated with this file uploader.

Field Summary

Fields

Modifier and Type	Field and Description
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).
static long	DEFAULT_PROGRESS_INTERVAL_MS Default number of milliseconds for the progress notification interval.
static String	METHOD_OVERRIDE Method-override http header.

Constructor Summary

Constructors

Constructor and Description
ResumableHttpFileUploader(URL url, File file, ExecutorService executor, ProgressListener progressListener, long progressIntervalMillis) Deprecated. Please use ResumableHttpFileUploader.Builder
ResumableHttpFileUploader(URL url, File file, ExecutorService executor, ProgressListener progressListener, long chunkSize, long progressIntervalMillis) Deprecated. Please use ResumableHttpFileUploader.Builder

Method Summary

Methods

Modifier and Type	Method and Description
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.
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.
ResumableHttpFileUploader.UploadState	getUploadState() Gets the current upload state of the uploader.
boolean	isDone() Identifies if the upload task has completed
boolean	isPaused() Identifies if the uploader is paused
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) Deprecated. Please use ResumableHttpFileUploader.Builder#setRequestMethod(RequestMethod)
Future<ResumableHttpFileUploader.ResponseMessage>	start() Starts an upload beginning with the first byte in the file.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

DEFAULT_MAX_CHUNK_SIZE

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

DEFAULT_PROGRESS_INTERVAL_MS

public static final long DEFAULT_PROGRESS_INTERVAL_MS

Default number of milliseconds for the progress notification interval.

See Also:

Constant Field Values

METHOD_OVERRIDE

public static final String METHOD_OVERRIDE

Method-override http header.

See Also:

Constant Field Values

Constructor Detail

ResumableHttpFileUploader

@Deprecated
public ResumableHttpFileUploader(URL url,
                                    File file,
                                    ExecutorService executor,
                                    ProgressListener progressListener,
                                    long progressIntervalMillis)
                          throws IOException

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

ResumableHttpFileUploader

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

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

Method Detail

setHttpRequestMethod

@Deprecated
public void setHttpRequestMethod(ResumableHttpFileUploader.RequestMethod requestMethod)

Deprecated. Please use ResumableHttpFileUploader.Builder#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

getHttpRequestMethod

public ResumableHttpFileUploader.RequestMethod getHttpRequestMethod()

Returns the http request method to use for upload.

addHeader

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

getNumBytesUploaded

public long getNumBytesUploaded()

Gets the total number of bytes uploaded by this uploader.

Returns:

the number of bytes uploaded

getProgress

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

getResponse

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

getUploadState

public ResumableHttpFileUploader.UploadState getUploadState()

Gets the current upload state of the uploader.

Returns:

the upload state

isPaused

public boolean isPaused()

Identifies if the uploader is paused

Returns:

true if the uploader is paused

pause

public void pause()

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

resume

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.

start

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

isDone

public boolean isDone()

Identifies if the upload task has completed

Returns:

true if the uploader is done

getData

public UploadData getData()

Gets the file associated with this uploader.

Returns:

the file to upload