You need to upload a file or a set of files with an HTTP multipart POST.

Create a MultipartPostMethod and add File objects as parameters using addParameter( ) and addPart( ). The MultipartPostMethod creates a request with a Content-Type header of multipart/form-data, and each part is separated by a boundary. The following example sends two files in an HTTP multipart POST:

               import org.apache.commons.httpclient.HttpClient;
import org.apache.commons.httpclient.HttpException;
import org.apache.commons.httpclient.methods.MultipartPostMethod;
import org.apache.commons.httpclient.methods.multipart.FilePart;
HttpClient client = new HttpClient( );
        
// Create POST method
String weblintURL = "http://ats.nist.gov/cgi-bin/cgi.tcl/echo.cgi";
MultipartPostMethod method = 
    new MultipartPostMethod( weblintURL );
File file = new File( "data", "test.txt" );
               File file2 = new File( "data", "sample.txt" );
               method.addParameter("test.txt", file );
               method.addPart( new FilePart( "sample.txt", file2, "text/plain", 
"ISO-8859-1" ) ); 
// Execute and print response
client.executeMethod( method );
String response = method.getResponseBodyAsString( );
System.out.println( response );
method.releaseConnection( );

Two File objects are added to the MultipartPostMethod using two different methods. The first method, addParameter( ), adds a File object and sets the file name to test.txt. The second method, addPart(), adds a FilePart object to the MultipartPostMethod. Both files are sent in the request separated by a part boundary, and the script echoes the location and type of both files on the server:

<h3>Form input</h3>
<pre>
sample.txt = /tmp/CGI14480.4 sample.txt {text/plain; charset=ISO-8859-1}
test.txt = /tmp/CGI14480.2 test.txt {application/octet-stream; 
charset=ISO-8859-1}
</pre>

Adding a part as a FilePart object allows you to specify the Multipurpose Internet Main Extensions (MIME) type and the character set of the part. In this example, the sample.txt file is added with a text/plain MIME type and an ISO-8859-1 character set. If a File is added to the method using addParameter( ) or setParameter( ), it is sent with the default application/octet-stream type and the default ISO-8859-1 character set.

When HttpClient executes the MultipartPostMethod created in the previous example, the following request is sent to the server. The Content-Type header is multipart/form-data, and an arbitrary boundary is created to delineate multiple parts being sent in the request:

POST /cgi-bin/cgi.tcl/echo.cgi HTTP/1.1
User-Agent: Jakarta Commons-HttpClient/3.0final
Host: ats.nist.gov
Content-Length: 498
Content-Type: multipart/form-data; boundary=----------------31415926535
8979323846
------------------314159265358979323846
Content-Disposition: form-data; name=test.txt; filename=test.txt
Content-Type: application/octet-stream; charset=ISO-8859-1
Content-Transfer-Encoding: binary
This is a test.
------------------314159265358979323846
Content-Disposition: form-data; name=sample.txt; filename=sample.txt
Content-Type: text/plain; charset=ISO-8859-1
Content-Transfer-Encoding: binary
This is a sample
------------------314159265358979323846--

Each part contains a Content-Disposition header to name the part and a Content-Type header to classify the part with a MIME type and character set.

RFC 1867 (form-based file upload in HTML defines a multipart POST) can be found at http://www.zvon.org/tmRFC/RFC1867/Output/index.html. Each part is sent using MIME, which is described in RFC 2045, Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies (http://www.zvon.org/tmRFC/RF2045/Output/index.html).