ca.ucalgary.services.util
Class MultiPartFormOutputStream

java.lang.Object
  ca.ucalgary.services.util.MultiPartFormOutputStream

public class MultiPartFormOutputStream
extends Object

MultiPartFormOutputStream is used to write "multipart/form-data" to a java.net.URLConnection for POSTing. This is primarily for file uploading to HTTP servers. Code taken from Useful Code of the Day: http://forums.sun.com/thread.jspa?threadID=451245&forumID=31

Since:

JDK1.3

Constructor Summary

MultiPartFormOutputStream(OutputStream os, String boundary)
Creates a new MultiPartFormOutputStream object using the specified output stream and boundary.

Method Summary

void	close() Closes the stream.
static String	createBoundary() Creates a multipart boundary string by concatenating 20 hyphens (-) and the hexadecimal (base-16) representation of the current time in milliseconds.
static URLConnection	createConnection(URL url) Creates a new java.net.URLConnection object from the specified java.net.URL.
void	flush() Flushes the stream.
String	getBoundary() Gets the multipart boundary string being used by this stream.
static String	getContentType(String boundary) Gets the content type string suitable for the java.net.URLConnection which includes the multipart boundary string.
void	writeField(String name, boolean value) Writes an boolean field value.
void	writeField(String name, char value) Writes an char field value.
void	writeField(String name, double value) Writes an double field value.
void	writeField(String name, float value) Writes an float field value.
void	writeField(String name, int value) Writes an int field value.
void	writeField(String name, long value) Writes an long field value.
void	writeField(String name, short value) Writes an short field value.
void	writeField(String name, String value) Writes an string field value.
void	writeFile(String name, String mimeType, File file) Writes a file's contents.
void	writeFile(String name, String mimeType, String fileName, byte[] data) Writes the given bytes.
void	writeFile(String name, String mimeType, String fileName, InputStream is) Writes a input stream's contents.

Methods inherited from class java.lang.Object

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

Constructor Detail

MultiPartFormOutputStream

public MultiPartFormOutputStream(OutputStream os,
                                 String boundary)

Creates a new MultiPartFormOutputStream object using the specified output stream and boundary. The boundary is required to be created before using this method, as described in the description for the getContentType(String) method. The boundary is only checked for null or empty string, but it is recommended to be at least 6 characters. (Or use the static createBoundary() method to create one.)

Parameters:

os - the output stream

boundary - the boundary

See Also:

createBoundary(), getContentType(String)

Method Detail

writeField

public void writeField(String name,
                       boolean value)
                throws IOException

Writes an boolean field value.

Parameters:

name - the field name (required)

value - the field value

Throws:

IOException - on input/output errors

writeField

public void writeField(String name,
                       double value)
                throws IOException

Writes an double field value.

Parameters:

name - the field name (required)

value - the field value

Throws:

IOException - on input/output errors

writeField

public void writeField(String name,
                       float value)
                throws IOException

Writes an float field value.

Parameters:

name - the field name (required)

value - the field value

Throws:

IOException - on input/output errors

writeField

public void writeField(String name,
                       long value)
                throws IOException

Writes an long field value.

Parameters:

name - the field name (required)

value - the field value

Throws:

IOException - on input/output errors

writeField

public void writeField(String name,
                       int value)
                throws IOException

Writes an int field value.

Parameters:

name - the field name (required)

value - the field value

Throws:

IOException - on input/output errors

writeField

public void writeField(String name,
                       short value)
                throws IOException

Writes an short field value.

Parameters:

name - the field name (required)

value - the field value

Throws:

IOException - on input/output errors

writeField

public void writeField(String name,
                       char value)
                throws IOException

Writes an char field value.

Parameters:

name - the field name (required)

value - the field value

Throws:

IOException - on input/output errors

writeField

public void writeField(String name,
                       String value)
                throws IOException

Writes an string field value. If the value is null, an empty string is sent ("").

Parameters:

name - the field name (required)

value - the field value

Throws:

IOException - on input/output errors

writeFile

public void writeFile(String name,
                      String mimeType,
                      File file)
               throws IOException

Writes a file's contents. If the file is null, does not exists, or is a directory, a java.lang.IllegalArgumentException will be thrown.

Parameters:

name - the field name

mimeType - the file content type (optional, recommended)

file - the file (the file must exist)

Throws:

IOException - on input/output errors

writeFile

public void writeFile(String name,
                      String mimeType,
                      String fileName,
                      InputStream is)
               throws IOException

Writes a input stream's contents. If the input stream is null, a java.lang.IllegalArgumentException will be thrown.

Parameters:

name - the field name

mimeType - the file content type (optional, recommended)

fileName - the file name (required)

is - the input stream

Throws:

IOException - on input/output errors

writeFile

public void writeFile(String name,
                      String mimeType,
                      String fileName,
                      byte[] data)
               throws IOException

Writes the given bytes. The bytes are assumed to be the contents of a file, and will be sent as such. If the data is null, a java.lang.IllegalArgumentException will be thrown.

Parameters:

name - the field name

mimeType - the file content type (optional, recommended)

fileName - the file name (required)

data - the file data

Throws:

IOException - on input/output errors

flush

public void flush()
           throws IOException

Flushes the stream. Actually, this method does nothing, as the only write methods are highly specialized and automatically flush.

Throws:

IOException - on input/output errors

close

public void close()
           throws IOException

Closes the stream.

NOTE: This method MUST be called to finalize the multipart stream.

Throws:

IOException - on input/output errors

getBoundary

public String getBoundary()

Gets the multipart boundary string being used by this stream.

Returns:

the boundary

createConnection

public static URLConnection createConnection(URL url)
                                      throws IOException

Creates a new java.net.URLConnection object from the specified java.net.URL. This is a convenience method which will set the doInput, doOutput, useCaches and defaultUseCaches fields to the appropriate settings in the correct order.

Returns:

a java.net.URLConnection object for the URL

Throws:

IOException - on input/output errors

createBoundary

public static String createBoundary()

Creates a multipart boundary string by concatenating 20 hyphens (-) and the hexadecimal (base-16) representation of the current time in milliseconds.

Returns:

a multipart boundary string

See Also:

getContentType(String)

getContentType

public static String getContentType(String boundary)

Gets the content type string suitable for the java.net.URLConnection which includes the multipart boundary string.

This method is static because, due to the nature of the java.net.URLConnection class, once the output stream for the connection is acquired, it's too late to set the content type (or any other request parameter). So one has to create a multipart boundary string first before using this class, such as with the createBoundary() method.

Parameters:

boundary - the boundary string

Returns:

the content type string

See Also:

createBoundary()