edu.ucsb.nceas.morpho.framework
Class MultipartForm

java.lang.Object
  extended byedu.ucsb.nceas.morpho.framework.MultipartForm

public class MultipartForm
extends java.lang.Object

This class represents name/value pairs and files in a byte array using the multipart/form-data encoding. After creating an instance, call "getLength()" to determine the content length of the encoded form, and call "writeEncodedMultipartForm()" to write the form to a stream. This is useful for sending large files in a stream using HTTP POST (of course, you have to use HTTPClient to replace the default http protocol handler in order to avoid buffering the stream).
Example:

     NVPair[] opts = { new NVPair("option", "doit") };
     NVPair[] file = { new NVPair("comment", "comment.txt") };
     NVPair[] hdrs = new NVPair[1];
     MultipartForm myform = new MultipartForm(opts, file);
     long length = myform.getLength();
     URL url = new URL("http://foo.bar.com");
     URLConnection con = url.openConnection();
     ((HttpURLConnection)con).setRequestMethod("POST");
     ((HttpURLConnection)con).setRequestProperty("Content-Length",
              new Long(length).toString());
     con.setDoInput(true);
     con.setDoOutput(true);
     con.setUseCaches(false);
     OutputStream out = con.getOutputStream();
     myform.writeEncodedMultipartForm(out);
 
The data written to out will look something like the following:
 -----------------------------114975832116442893661388290519
 Content-Disposition: form-data; name="option"
                                                          
 doit
 -----------------------------114975832116442893661388290519
 Content-Disposition: form-data; name="comment"; filename="comment.txt"
 Content-Type: text/plain
                                                          
 Gnus and Gnats are not Gnomes.
 -----------------------------114975832116442893661388290519--
 
where the "Gnus and Gnats ..." is the contents of the file comment.txt in the current directory.

If no elements are found in the parameters then a zero-length no data is written to out and the content-type is set to application/octet-string (because a multipart must always have at least one part.

For files an attempt is made to discover the content-type, and if found a Content-Type header will be added to that part. The content type is retrieved using java.net.URLConnection.guessContentTypeFromName() - see java.net.URLConnection.setFileNameMap() for how to modify that map. Note that under JDK 1.1 by default the map seems to be empty. If you experience troubles getting the server to accept the data then make sure the fileNameMap is returning a content-type for each file (this may mean you'll have to set your own).


Constructor Summary
MultipartForm(NVPair[] opts, NVPair[] files)
          Create a new form with form data and files using the multipart/form-data encoding.
MultipartForm(NVPair[] opts, NVPair[] files, FilenameMangler mangler)
          Create a new form with form data and files using the multipart/form-data encoding and use the given FilenameMangler to alter filenames before encoding.
 
Method Summary
 java.lang.String getContentType()
          Get the content header after encoding.
 long getLength()
          Get the length in bytes of this form after encoding.
 void writeEncodedMultipartForm(java.io.OutputStream out)
          Write the multipart/form-data encoded version of the form to the provided output stream, using a default bufferSize of 4096 bytes for reading in the files.
 void writeEncodedMultipartForm(java.io.OutputStream out, int bufferSize)
          Write the multipart/form-data encoded version of the form to the provided output stream, using the provided bufferSize for reading in the files.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

MultipartForm

public MultipartForm(NVPair[] opts,
                     NVPair[] files,
                     FilenameMangler mangler)
              throws java.io.IOException
Create a new form with form data and files using the multipart/form-data encoding and use the given FilenameMangler to alter filenames before encoding.

Parameters:
opts - the simple form-data to encode (may be null); for each NVPair the name refers to the 'name' attribute to be used in the header of the part, and the value is contents of the part. null elements in the array are ingored.
files - the files to encode (may be null); for each NVPair the name refers to the 'name' attribute to be used in the header of the part, and the value is the actual filename (the file will be read and it's contents put in the body of that part). null elements in the array are ingored.
mangler - the filename mangler, or null if no mangling is to be done. This allows you to change the name used in the filename attribute of the Content-Disposition header. Note: the mangler will be invoked twice for each filename.
Throws:
java.io.IOException - If any file operation fails.
See Also:
getLength(), writeEncodedMultipartForm(OutputStream out, int bufferSize)

MultipartForm

public MultipartForm(NVPair[] opts,
                     NVPair[] files)
              throws java.io.IOException
Create a new form with form data and files using the multipart/form-data encoding.

Parameters:
opts - the simple form-data to encode (may be null); for each NVPair the name refers to the 'name' attribute to be used in the header of the part, and the value is contents of the part.
files - the files to encode (may be null); for each NVPair the name refers to the 'name' attribute to be used in the header of the part, and the value is the actual filename (the file will be read and it's contents put in the body of that part).
Throws:
java.io.IOException - If any file operation fails.
See Also:
getLength(), writeEncodedMultipartForm(OutputStream out, int bufferSize)
Method Detail

writeEncodedMultipartForm

public void writeEncodedMultipartForm(java.io.OutputStream out)
                               throws java.io.IOException
Write the multipart/form-data encoded version of the form to the provided output stream, using a default bufferSize of 4096 bytes for reading in the files. Note that the output stream is closed after writing.

Parameters:
out - the OutputStream to which the encoded form should be written
Throws:
java.io.IOException - If any file operation fails.

writeEncodedMultipartForm

public void writeEncodedMultipartForm(java.io.OutputStream out,
                                      int bufferSize)
                               throws java.io.IOException
Write the multipart/form-data encoded version of the form to the provided output stream, using the provided bufferSize for reading in the files. Note that the output stream is closed after writing.

Parameters:
out - the OutputStream to which the encoded form should be written
bufferSize - the size in bytes of the buffer used to read data files
Throws:
java.io.IOException - If any file operation fails.

getLength

public long getLength()
Get the length in bytes of this form after encoding. This method can be used to set "Content-Length" headers and in other situations where the length must be known before the data is read from disk.

Returns:
the length of the encoded form in bytes

getContentType

public java.lang.String getContentType()
Get the content header after encoding. This returns a String that contains the value = "multipart/form-data; boundary=..." The exception to this is that if no opts or files are given the type is set to "application/octet-stream" instead.

Returns:
the content header String


Copyright © 2000 National Center for Ecological Analysis and Synthesis. All Rights Reserved.