com.addicticks.net.httpsupload

Class HttpsFileUploader

java.lang.Object

com.addicticks.net.httpsupload.HttpsFileUploader

public class HttpsFileUploader
extends Object

Uploading file(s) to a HTTP/HTTPS site using POST method and the multipart/form-data encoding (RFC2388). .

The class has the following features:

• Allows uploading multiple files (or streams) in one operation (if supported by the endpoint).

• Has no external dependencies, e.g. no Apache HttpClient.

• Certificate validation can be turned off. This is important when working against a site that uses a self-signed certificate.

• Support for endpoints that require authentication (only authentication type "Basic" is currently supported).

• Java's HttpURLConnection/HttpsURLConnection will normally do internal buffering of the request being sent. If the file being uploaded is large this means that Java will try to buffer all of the file in memory. This class avoids this by streaming the file contents to the server and therefore allows very large files to be uploaded without causing an out-of-memory error in the JVM. If you are uploading from a stream rather than a file then this feature does not apply.

• Support for explicitly setting network proxy. This is implemented without the use of global system properties, so can be used without affecting other classes in the same JVM.

• Upload progress can be tracked for every 1% progress. This allows a UI to let the user know how the upload is progressing.

EXAMPLE:

 // Configure the connection        
 HttpsFileUploaderConfig uploaderConfig = new HttpsFileUploaderConfig(endpointURL);
 uploaderConfig.setEndpointUsername(endpointUsername);
 uploaderConfig.setEndpointPassword(endpointPassword);
 uploaderConfig.setValidateCertificates(false);
 uploaderConfig.setProxyAddress(proxyAddress);
 uploaderConfig.setProxyPort(proxyPort);
 
 // Do the upload.
 // A single file is uploaded along with a single text field.
 result = HttpsFileUploader.upload(
     uploaderConfig, 
     Collections.singletonMap("file1", new HttpsFileUploader.UploadItemFile(new File("hugefile.zip"))), 
     Collections.singletonMap("email", "johnny@company.com"), 
     this);
 
 // Evaluate the result.
 if (!result.isError()) {
     System.out.println("OK, upload successful");
 } else {
     System.out.println("Error uploading, http code :" + result.getHttpStatusCode());
     System.out.println("Message from server : " + result.getResponseTextNoHtml());
 }
 
 

Author:

Addicticks

Method Summary

Modifier and Type	Method and Description
static HttpsFileUploaderResult	upload(HttpsFileUploaderConfig config, File uploadFile) Uploads a file.
static HttpsFileUploaderResult	upload(HttpsFileUploaderConfig config, Map<String,UploadItem> uploadFiles, Map<String,String> otherFields, UploadProgress progressNotifier) Uploads a file (or files) using POST method.

Methods inherited from class java.lang.Object

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

Method Detail

upload

public static HttpsFileUploaderResult upload(HttpsFileUploaderConfig config,
                                             Map<String,UploadItem> uploadFiles,
                                             Map<String,String> otherFields,
                                             UploadProgress progressNotifier)
                                      throws IOException

Uploads a file (or files) using POST method. The file is never cached in memory so very big files can be uploaded without causing a memory problem. Optionally allows upload directly from an InputStream rather than a physical file.

After the method returns the result should be examined for errors.

Multiple files can be uploaded in the same method call as long as each file has its own destination field on the server, e.g. "file1", "file2", etc. Upload of multiple files into the same field is not supported. (this is anyway a rather recent feature for example IE did not support it until v10).

Some endpoints also allow uploading of other information than just the file(s). This is supported via the otherFields argument.

This is a blocking call. You may want to spawn it off into its own thread.



See general description and example here.

Parameters:

config - configuration for the connection.

uploadFiles - the files or streams to upload. The key of the map is the form field name into which the file/stream is uploaded. Quite often the server side only allows a single file to be uploaded at a time. In this case this map only has a single element but then it may be easier to use the upload(com.addicticks.net.httpsupload.HttpsFileUploaderConfig, java.io.File) method. Most often the form field name is file or if multiple files are accepted: file1, file2, ... and so on.

otherFields - Other fields to be POST'ed into the form besides the file(s). Some forms allow certain other fields, such as the name or email address of the uploader. The key of the map must be the form field name and the value is the plain text value of the field. The null value is acceptable.

progressNotifier - Optional callback notifier. This will give a callback for each percent of the file that has been uploaded. Use null if no progress notification is required.

Returns:

result of the upload operation

Throws:

IOException - if the endpoint cannot be reached or if input file(s) cannot be read.

upload

public static HttpsFileUploaderResult upload(HttpsFileUploaderConfig config,
                                             File uploadFile)
                                      throws IOException

Uploads a file. This is a convenience method of the more general upload(...) method. This method only uploads a single file and expects the destination field for the file on the server to be named "file".

After the method returns the result should be examined for errors.

Parameters:

config - configuration for the connection.

uploadFile - file to upload

Returns:

result of the upload operation

Throws:

IOException - if the endpoint cannot be reached or if input file cannot be read.

See Also:

upload(com.addicticks.net.httpsupload.HttpsFileUploaderConfig, java.util.Map, java.util.Map, com.addicticks.net.httpsupload.UploadProgress)