SK.gnome.dwarf.mail.mime
Class MimePartBuilder

java.lang.Object
  SK.gnome.dwarf.mail.mime.MimePartBuilder

All Implemented Interfaces:

MimePart

Direct Known Subclasses:

MimeMessageBuilder

public class MimePartBuilder

extends java.lang.Object

implements MimePart

Provides a MimePart builder.

This class implements the MimePart interface and can be used to create MIME parts with a very little effort.

All methods which set MIME headers handle non-ASCII strings by encoding them as per RFC 2047.

Performance note: this class stores the part content in an internal byte buffer, therefore it is not suitable for a frequent building of large binary parts.

Field Summary

protected boolean	allow8bit Whether the 8bit transfer encoding is permitted.
static java.lang.String	DEFAULT_CHARSET The default MIME charset for encoding headers as per RFC 2047.
protected java.lang.String	charset The actual MIME charset for encoding headers as per RFC 2047.

Constructor Summary

MimePartBuilder()
Creates a new MimePartBuilder.

MimePartBuilder(boolean allow8bit)
Creates a new MimePartBuilder with 8bit transfer enabled.

MimePartBuilder(boolean allow8bit, java.lang.String charset)
Creates a new MimePartBuilder.

MimePartBuilder(java.lang.String charset)
Creates a new MimePartBuilder with the given charset.

Method Summary

void	addHeader(java.lang.String name, java.lang.String value) Adds the given header.
void	addMimePart(MimePartBuilder part) Adds the given MIME part.
java.io.InputStream	getContentInputStream() Returns the content input stream.
int	getContentSize() Returns the content size.
java.io.InputStream	getDecodedInputStream() Returns the decoded content input stream.
java.lang.String[]	getHeader(java.lang.String name) Returns all values of the given header.
java.lang.String	getHeader(java.lang.String name, java.lang.String delimiter) Returns all values of the given header, delimited by the given character sequence.
java.util.Iterator	getHeaderLines() Returns all header lines.
java.util.Iterator	getHeaderNames() Returns all header names.
int	getLineCount() Returns the line count of the body.
java.util.Iterator	getMatchingHeaderLines(java.lang.String[] names) Returns matching header lines.
MimePart	getMimePart(int number) Returns the nested MIME part.
int	getMimePartCount() Returns the number of nested MIME parts.
java.util.Iterator	getNonMatchingHeaderLines(java.lang.String[] names) Returns non matching header lines.
java.io.InputStream	getRawInputStream() Returns the raw input stream.
int	getRawSize() Returns the raw size of this part.
boolean	isMimeType(java.lang.String type) Whether this MIME part if of the given type.
void	removeHeader(java.lang.String name) Removes the given header.
void	removeMimePart(int number) Removes the given MIME part.
void	setAddressHeader(java.lang.String name, java.lang.String value) Sets the given address header.
void	setAddressHeader(java.lang.String name, java.lang.String[] value) Sets the given address header.
void	setContent(java.io.InputStream in, java.lang.String type, java.lang.String encoding) Sets the body content with the given MIME content type and transfer encoding.
void	setContent(java.lang.String text) Sets the body content.
void	setContent(java.lang.String text, java.lang.String charset) Sets the body content with the given charset.
void	setContentDescription(java.lang.String description) Sets the "Content-Description" header.
void	setContentLanguage(java.lang.String[] languages) Sets the "Content-Language" header.
void	setContentTransferEncoding(java.lang.String encoding) Sets the "Content-Transfer-Encoding" header.
void	setContentType(java.lang.String type) Sets the "Content-Type" header.
void	setHeader(java.lang.String name, java.lang.String value) Sets the given header.
void	setName(java.lang.String name) Sets the MIME part name.
void	writeTo(java.io.OutputStream out) Writes the entire MIME part to the given output stream.

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_CHARSET

public static final java.lang.String DEFAULT_CHARSET

The default MIME charset for encoding headers as per RFC 2047.

The default charset is "utf-8".

See Also:

Constant Field Values

charset

protected java.lang.String charset

The actual MIME charset for encoding headers as per RFC 2047.

allow8bit

protected boolean allow8bit

Whether the 8bit transfer encoding is permitted.

Constructor Detail

MimePartBuilder

public MimePartBuilder()
                throws java.io.IOException,
                       MimeException

Creates a new MimePartBuilder.

MimePartBuilder

public MimePartBuilder(boolean allow8bit)
                throws java.io.IOException,
                       MimeException

Creates a new MimePartBuilder with 8bit transfer enabled.

If the allow8bit parameter is true, the part will be created assuming that the MTA is capable to transfer 8bit content. If it is false, the content will be always converted to pure 7bit ASCII format.

Parameters:

allow8bit - whether to enable 8bit content

MimePartBuilder

public MimePartBuilder(java.lang.String charset)
                throws java.io.IOException,
                       MimeException

Creates a new MimePartBuilder with the given charset.

The charset parameter specifies the MIME charset used to encode the headers as per RFC 2047.

Parameters:

charset - the MIME charset

See Also:

charset

MimePartBuilder

public MimePartBuilder(boolean allow8bit,
                       java.lang.String charset)
                throws java.io.IOException,
                       MimeException

Creates a new MimePartBuilder.

If the allow8bit parameter is true, the part will be created assuming that the MTA is capable to transfer 8bit content. If it is false, the content will be always converted to pure 7bit ASCII format.

The charset parameter specifies the MIME charset used to encode the headers as per RFC 2047.

Parameters:

allow8bit - whether to enable 8bit content

charset - the MIME charset

See Also:

charset

Method Detail

getHeaderNames

public java.util.Iterator getHeaderNames()
                                  throws MimeException

Description copied from interface: MimePart

Returns all header names.

Specified by:

getHeaderNames in interface MimePart

Returns:

the header names

Throws:

MimeException - if a MIME syntax error occured

getHeader

public java.lang.String[] getHeader(java.lang.String name)
                             throws MimeException

Description copied from interface: MimePart

Returns all values of the given header.

Specified by:

getHeader in interface MimePart

Parameters:

name - the header name

Returns:

the array of header values

Throws:

MimeException - if a MIME syntax error occured

getHeader

public java.lang.String getHeader(java.lang.String name,
                                  java.lang.String delimiter)
                           throws MimeException

Description copied from interface: MimePart

Returns all values of the given header, delimited by the given character sequence.

Specified by:

getHeader in interface MimePart

Parameters:

name - the header name

delimiter - the value delimiter

Returns:

the string of delimited header values

Throws:

MimeException - if a MIME syntax error occured

getHeaderLines

public java.util.Iterator getHeaderLines()
                                  throws MimeException

Description copied from interface: MimePart

Returns all header lines.

The header lines are returned in the exact form as they appear in the MIME part.

Specified by:

getHeaderLines in interface MimePart

Returns:

the header lines

Throws:

MimeException - if a MIME syntax error occured

getMatchingHeaderLines

public java.util.Iterator getMatchingHeaderLines(java.lang.String[] names)
                                          throws MimeException

Description copied from interface: MimePart

Returns matching header lines.

The header lines are returned in the exact form as they appear in the MIME part.

Specified by:

getMatchingHeaderLines in interface MimePart

Parameters:

names - the header names

Returns:

the matching header lines

Throws:

MimeException - if a MIME syntax error occured

getNonMatchingHeaderLines

public java.util.Iterator getNonMatchingHeaderLines(java.lang.String[] names)
                                             throws MimeException

Description copied from interface: MimePart

Returns non matching header lines.

The header lines are returned in the exact form as they appear in the MIME part.

Specified by:

getNonMatchingHeaderLines in interface MimePart

Parameters:

names - the header names

Returns:

the non matching header lines

Throws:

MimeException - if a MIME syntax error occured

isMimeType

public boolean isMimeType(java.lang.String type)
                   throws MimeException

Description copied from interface: MimePart

Whether this MIME part if of the given type.

The type argument must be in the form of "type/subtype" pair. If wildcard character "*" is used as the subtype, the method will test only the main type. The type matching is case insensitive.

Specified by:

isMimeType in interface MimePart

Parameters:

type - the mime type

Returns:

true if this part is of the given type, false otherwise

Throws:

MimeException - if a MIME syntax error occured

getRawSize

public int getRawSize()
               throws MimeException

Description copied from interface: MimePart

Returns the raw size of this part.

Returns the size of the whole MIME part including the header.

Specified by:

getRawSize in interface MimePart

Returns:

the raw size

Throws:

MimeException - if a MIME syntax error occured

getContentSize

public int getContentSize()
                   throws MimeException

Description copied from interface: MimePart

Returns the content size.

Returns the size of content-encoded MIME part body.

Specified by:

getContentSize in interface MimePart

Returns:

the content size

Throws:

MimeException - if a MIME syntax error occured

getLineCount

public int getLineCount()
                 throws java.io.IOException,
                        MimeException

Description copied from interface: MimePart

Returns the line count of the body.

Returns the total line count of the content-encoded MIME part body.

Specified by:

getLineCount in interface MimePart

Returns:

the line count

Throws:

MimeException - if a MIME syntax error occured

java.io.IOException - if an I/O error occured

getRawInputStream

public java.io.InputStream getRawInputStream()
                                      throws java.io.IOException,
                                             MimeException

Description copied from interface: MimePart

Returns the raw input stream.

Returns the input stream of the whole MIME part including the header.

Specified by:

getRawInputStream in interface MimePart

Returns:

the raw stream

Throws:

MimeException - if a MIME syntax error occured

java.io.IOException - if an I/O error occured

getContentInputStream

public java.io.InputStream getContentInputStream()
                                          throws java.io.IOException,
                                                 MimeException

Description copied from interface: MimePart

Returns the content input stream.

Returns the input stream of the content-encoded MIME part body.

Specified by:

getContentInputStream in interface MimePart

Returns:

the content stream

Throws:

java.io.IOException - if an I/O error occured

MimeException - if a MIME syntax error occured

getDecodedInputStream

public java.io.InputStream getDecodedInputStream()
                                          throws java.io.IOException,
                                                 MimeException

Description copied from interface: MimePart

Returns the decoded content input stream.

Returns the input stream of the content-decoded MIME part body.

Specified by:

getDecodedInputStream in interface MimePart

Returns:

the content stream

Throws:

java.io.IOException - if an I/O error occured

MimeException - if a MIME syntax error occured

getMimePartCount

public int getMimePartCount()
                     throws MimeException

Description copied from interface: MimePart

Returns the number of nested MIME parts.

Returns the total number of nested MIME parts. The parts are numbered from zero. Only parts of type "multipart/*" or "message/rfc822" are regarded as multipart. If the part if of type "message/rfc822", it has only one directly nested part - the RFC822 message itself, which may in turn contain another MIME parts, if it is a multipart message.

Specified by:

getMimePartCount in interface MimePart

Returns:

the number of MIME parts

Throws:

MimeException - if a MIME syntax error occured

getMimePart

public MimePart getMimePart(int number)
                     throws MimeException

Description copied from interface: MimePart

Returns the nested MIME part.

Specified by:

getMimePart in interface MimePart

Parameters:

number - the part number

Returns:

the given MIME part

Throws:

MimeException - if a MIME syntax error occured

setName

public void setName(java.lang.String name)

Sets the MIME part name.

The name is used to set the corresponding parameter of the Content-Type header.

Parameters:

name - the part name

setHeader

public void setHeader(java.lang.String name,
                      java.lang.String value)
               throws MailException

Sets the given header.

It sets the header with the given name to the given value. All other occurences of the header are removed.

If the given value is a non-ASCII string, it is first encoded as per RFC 2047 using the actual charset.

Parameters:

name - the header name

value - the header value

Throws:

MailException - if an error occured

setAddressHeader

public void setAddressHeader(java.lang.String name,
                             java.lang.String value)
                      throws MailException

Sets the given address header.

It sets the header with the given name to the given value. All other occurences of the header are removed. The value must be a comma-separated list of valid RFC 822 addresses.

The addresses are automatically encoded as per RFC 2047 using the actual charset.

This method calls setHeader(String, String) to set the header value.

Parameters:

name - the header name

value - comma-separated list of addresses

Throws:

MailException - if an error occured

setAddressHeader

public void setAddressHeader(java.lang.String name,
                             java.lang.String[] value)
                      throws MailException

Sets the given address header.

It sets the header with the given name to the given value. All other occurences of the header are removed. The value must be an array of valid RFC 822 addresses.

The addresses are automatically encoded as per RFC 2047 using the actual charset.

This method calls setHeader(String, String) to set the header value.

Parameters:

name - the header name

value - array of addresses

Throws:

MailException - if an error occured

addHeader

public void addHeader(java.lang.String name,
                      java.lang.String value)
               throws MailException

Adds the given header.

It adds the header with the given name and value. All other occurences of the headers are left untouched.

If the given value is a non-ASCII string, it is first encoded as per RFC 2047 using the actual charset.

Parameters:

name - the header name

value - the header value

Throws:

MailException - if an error occured

removeHeader

public void removeHeader(java.lang.String name)

Removes the given header.

It removes all occurences of the given header.

Parameters:

name - the header name

setContentDescription

public void setContentDescription(java.lang.String description)
                           throws MailException

Sets the "Content-Description" header.

Parameters:

description - the description

Throws:

MailException - if an error occured

setContentLanguage

public void setContentLanguage(java.lang.String[] languages)
                        throws MailException

Sets the "Content-Language" header.

Parameters:

languages - the languages

Throws:

MailException - if an error occured

setContentType

public void setContentType(java.lang.String type)
                    throws MailException

Sets the "Content-Type" header.

It the part's name is not null, the corresponding parameter of the Content-Type header is set also.

If this part contains another parts, the boundary parameter is automatically added to the Content-Type header value, too.

Parameters:

type - the MIME content type

Throws:

MailException - if an error occured

setContentTransferEncoding

public void setContentTransferEncoding(java.lang.String encoding)
                                throws MailException

Sets the "Content-Transfer-Encoding" header.

The currently supported encodings are: 7bit, 8bit, quoted-printable, base64 and uuencode.

Parameters:

encoding - the encoding

Throws:

MailException - if an error occured

setContent

public void setContent(java.lang.String text)
                throws java.io.IOException,
                       MailException

Sets the body content.

It sets the text body by calling setContent(String, String) with the null charset argument.

Parameters:

text - the body text

Throws:

java.io.IOException - if an I/O error occured

MailException - if an error occured

setContent

public void setContent(java.lang.String text,
                       java.lang.String charset)
                throws java.io.IOException,
                       MailException

Sets the body content with the given charset.

It sets the text body by encoding it first as necessary according to the given MIME charset. If the charset parameter is null, a default "us-ascii" or DEFAULT_CHARSET is choosen according to the given text.

This method sets also the Content-Type and Content-Transfer-Encoding headers, overriding the existing values.

Parameters:

text - the body text

charset - the MIME charset or null

Throws:

java.io.IOException - if an I/O error occured

MailException - if an error occured

setContent

public void setContent(java.io.InputStream in,
                       java.lang.String type,
                       java.lang.String encoding)
                throws java.io.IOException,
                       MailException

Sets the body content with the given MIME content type and transfer encoding.

It sets the body by encoding the octets first as necessary according to the given transfer encoding. The currently supported encodings are: 7bit, 8bit, quoted-printable, base64 and uuencode.

This method sets the Content-Type and Content-Transfer-Encoding headers by overriding the existing ones.

Parameters:

in - the input stream

type - the MIME content type

encoding - the transfer encoding

Throws:

java.io.IOException - if an I/O error occured

MailException - if an error occured

addMimePart

public void addMimePart(MimePartBuilder part)
                 throws MailException

Adds the given MIME part.

Please note that this method does not modify the Content-Type header, therefore it must be set manually to one of the MIME multipart types after all the nested MIME parts have been added.

Parameters:

part - the MIME part

Throws:

MailException

removeMimePart

public void removeMimePart(int number)

Removes the given MIME part.

Parameters:

number - the part number

writeTo

public void writeTo(java.io.OutputStream out)
             throws java.io.IOException,
                    MimeException

Writes the entire MIME part to the given output stream.

Parameters:

out - the output stream to write to

Throws:

java.io.IOException - if an error occured

MimeException