SK.gnome.dwarf.mail.store
Class MailMessage

java.lang.Object
  SK.gnome.dwarf.mail.store.MailMessage

All Implemented Interfaces:

java.lang.Comparable

public abstract class MailMessage

extends java.lang.Object

implements java.lang.Comparable

This class provides an abstract mail message.

Field Summary

protected MailFolder

folder Mail folder which the message belongs to.

Constructor Summary

protected

MailMessage(MailFolder folder) Creates a new MailMessage.

Method Summary

int	compareTo(java.lang.Object o) Compares the message to another message.
java.util.Set	getFlags() Returns the message flags.
MailFolder	getFolder() Returns the folder which the message belongs to.
abstract java.io.InputStream	getInputStream() Returns the message content.
abstract long	getInternalDate() Returns the internal date of the message.
abstract MimePart	getMimePart() Returns a parsed MIME represenation of the message.
abstract int	getNumber() Returns the message number.
abstract long	getSize() Returns the message size.
abstract long	getUID() Returns the UID of the message.
abstract boolean	isExpunged() Whether this message is expunged.
abstract boolean	isSet(MailFlag flag) Whether the given message flag is set.
java.lang.String	listFlags() List the message flags.
abstract void	setFlag(MailFlag flag, boolean set) Sets/unsets the given message flag.
void	setFlags(java.util.Set flags) Modifies the given message flags.
void	setFlags(java.util.Set flags, boolean set) Sets/unsets the given message flags.

Methods inherited from class java.lang.Object

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

Field Detail

folder

protected MailFolder folder

Mail folder which the message belongs to.

Constructor Detail

MailMessage

protected MailMessage(MailFolder folder)

Creates a new MailMessage.

Parameters:

folder - the folder which the message belongs to

Method Detail

getUID

public abstract long getUID()

Returns the UID of the message.

The UIDs in the particular folder are assigned to messages in a strictly ascending order and should persist across different mail sessions. A single UID number must not be assigned twice unless the folder's UID validity value changes between the assignments.

The returned value must be an unsigned 32bit integer.

Returns:

the uid number

getNumber

public abstract int getNumber()

Returns the message number.

The messages in the particular folder are ordered from 1 to N and this number need not to persist across different mail sessions. The message numbers may change even within the same session and may be reused as needed.

Please remember that this number is not an index to the message array returned from the MailFolder.getMessages() method!

Returns:

the message number

getSize

public abstract long getSize()
                      throws MailException

Returns the message size.

This must be an exact size of the whole unparsed message, including the header.

This method is valid only if the message is not expunged.

Returns:

the exact message size

Throws:

MailException - if the message is expunged or another error occured

getInternalDate

public abstract long getInternalDate()
                              throws MailException

Returns the internal date of the message.

This date generally corresponds to a system time in the moment the message was added to a folder.

This method is valid only if the message is not expunged.

Returns:

the internal date

Throws:

MailException - if the message is expunged or another error occured

isExpunged

public abstract boolean isExpunged()

Whether this message is expunged.

An expunged message has been permanently removed from the folder. However, a one or more MailMessage instances may still exist as references to the removed message. This method indicates that the physical representation of the message does not longer exists, therefore most of the operations may not be performed on the message.

Returns:

true if the message is expunged, false otherwise

isSet

public abstract boolean isSet(MailFlag flag)
                       throws MailException

Whether the given message flag is set.

This method is valid only if the message is not expunged.

Parameters:

flag - the message flag to check

Returns:

true if the flag is set, false otherwise

Throws:

MailException - if the message is expunged or another error occured

setFlag

public abstract void setFlag(MailFlag flag,
                             boolean set)
                      throws MailException

Sets/unsets the given message flag.

If the folder is open as read-write, the flag changes must be permanent. On the other hand, if it is read-only, the changes shall persist only for the particular mail session duration. This method must not allow to set/unset the \Recent flag.

If the folder is not read-only, the MailFlagEvent should be generated and dispatched via the folder's dispatchMailEvent method to inform the other folders about the change.

This method is valid only if the message is not expunged.

Parameters:

flag - the message flag to set/unset

set - true to set the flag, false to unset

Throws:

MailException - if the message is expunged or another error occured

getInputStream

public abstract java.io.InputStream getInputStream()
                                            throws java.io.IOException,
                                                   MailException

Returns the message content.

The whole unparsed message content is returned as an input stream, including the header.

This method is valid only if the message is not expunged.

Returns:

the message input stream

Throws:

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

MailException - if the message is expunged or another error occured

getMimePart

public abstract MimePart getMimePart()
                              throws MailException

Returns a parsed MIME represenation of the message.

This method is valid only if the message is not expunged.

Returns:

the MIME part

Throws:

MailException - if the message is expunged or another error occured

getFolder

public MailFolder getFolder()

Returns the folder which the message belongs to.

Returns:

the mail folder

setFlags

public void setFlags(java.util.Set flags,
                     boolean set)
              throws MailException

Sets/unsets the given message flags.

This is a template method which calls the setFlag(MailFlag, boolean) method.

Parameters:

flags - the flags to set/unset

set - true to set the given flags, false to unset them

Throws:

MailException - if an error occured

setFlags

public void setFlags(java.util.Set flags)
              throws MailException

Modifies the given message flags.

All flags contained in the flags collection are set and the rest of the flags are unset.

This is a template method which calls the setFlag(MailFlag, boolean) method.

Parameters:

flags - the flags to modify

Throws:

MailException - if an errpo occured

getFlags

public java.util.Set getFlags()
                       throws MailException

Returns the message flags.

This is a template method which calls the isSet(MailFlag) method.

Returns:

all message flags which are set

Throws:

MailException - if an error occured

listFlags

public java.lang.String listFlags()
                           throws MailException

List the message flags.

The list of flag string representations separated by a single space is returned.

This is a template method which calls the getFlags() method.

Returns:

the list of message flags as string

Throws:

MailException - if an error occured

compareTo

public int compareTo(java.lang.Object o)

Compares the message to another message.

The messages are compared by the message UIDs. Since this class implements the Comparable interface, an array of messages may be sorted easily by their UID numbers.

Specified by:

compareTo in interface java.lang.Comparable

Parameters:

o - the another object to compare