SK.gnome.dwarf.mail.store
Class MailFolder

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

All Implemented Interfaces:

java.lang.Comparable, java.util.EventListener, MailEventListener

public abstract class MailFolder

extends java.lang.Object

implements java.lang.Comparable, MailEventListener

This class provides an abstract mail folder.

Mail folders can hold other mail folders as well as mail messages. Folders which have not a parent folder are called default folders. They may contain another folders only but no messages, therefore the meesage-oriented operations are not allowed on them. Default folder represents a root level of the whole folder tree for a particular user and may be obtained from the MailStore instance.

A special case of a folder is INBOX, which holds the incoming mail messages. It must be nested directly under the default folder and must be named INBOX.

A folder may not physically exists when its object representation is instantiated. The exists() method returns whether it exists or not, and if it does not, the create() method creates it physically.

There are two basic states of a folder - closed and open. A newly instantiated folder object is closed by default and it must be open by the open(int) method to get access to the contained messages. Furthemore, folders may be open either as READ_ONLY or READ_WRITE . A read-only folder must not allow a permanent change to its state except adding a new messages to it via the getNewMessages() method.

Messages which have been added to the folder recently may not be immediatelly accessible via its getMessages() method. In order to let the folder reflect the changes, the getNewMessages() method should be called explicitly to check for the new messages and to update ist internal state. This method is allowed to modify the permanent state of the folder even in the read-only mode.

Each MailFolder instance should inform another folder instances about its recent changes by generating an appropriate mail events and dispatching them via the dispatchMailEvent(MailEvent) method. The other folders may reflect the changes as needed since each folder implements the MailEventListener interface by default.

Field Summary

static java.lang.String	INBOX Default name for the inbox folder.
protected MailFolder	parent The parent folder of the mail folder.
static int	READ_ONLY Indicates that the folder must be open as read-only.
static int	READ_WRITE Indicates that the folder should be open as read-write.
protected MailStore	store The mail store which the folder belongs to.
protected java.lang.String	user The identification of a user which the folder belongs to.

Constructor Summary

protected

MailFolder(java.lang.String user, MailStore store, MailFolder parent) Creates a new MailFolder.

Method Summary

abstract void	addMessage(long time, java.util.Set flags, java.io.InputStream in) Adds the given message to the folder.
abstract void	close(boolean clearRecent) Closes the folder.
int	compareTo(java.lang.Object o) Compares the folder to another folder.
abstract void	copyMessage(MailMessage message) Copies the given message to the folder.
abstract void	create() Creates this folder.
abstract void	delete() Deletes the folder and its content.
protected void	dispatchMailEvent(MailEvent event) Dispatches the given mail event.
abstract boolean	exists() Whether this folder exists.
abstract MailMessage[]	expunge() Expunges the messages.
protected void	finalize() Fianalizes the object.
int	getFirstUnseen() Returns the number of the first unseen message.
abstract MailFolder	getFolder(java.lang.String folder) Returns a subfolder of the folder.
abstract java.lang.String	getFullName() Returns the full name of the folder.
protected MailStore	getMailStore() Returns the mail store which this folder belongs to.
MailMessage	getMessage(int number) Returns a message by the given number.
MailMessage	getMessage(long uid) Returns a message by the given UID.
int	getMessageCount() Returns the total message count.
int	getMessageCount(MailFlag flag, boolean set) Returns the count of messages with the given flag set/unset.
abstract MailMessage[]	getMessages() Returns messages contained by this folder.
abstract int	getMode() Returns the mode used to open the folder.
abstract java.lang.String	getName() Returns the name of the folder.
abstract MailMessage[]	getNewMessages() Checks for new messages in the folder.
abstract long	getNextUID() Returns the next predicted UID of this folder.
MailFolder	getParent() Returns the parent folder.
abstract char	getSeparator() Returns the folder separator character.
long	getSize() Returns the size of all messages in the folder.
long	getSize(MailFlag flag, boolean set) Returns the size of messages in the folder with the given flag set/unset.
abstract long	getUIDValidity() Returns the UID validity timestamp.
java.lang.String	getUser() Returns an identification of the user which this folder belongs to.
abstract void	handleMailEvent(MailEvent event) Handles the given mail event.
boolean	isDefaultFolder() Checks whether the folder is the default folder.
abstract boolean	isOpen() Checks whether the folder is open.
boolean	isReadOnly() Checks whether this folder is open in READ_ONLY mode.
abstract MailFolder[]	listFolders(java.lang.String pattern) List subfolders of the folder.
abstract void	open(int mode) Opens this folder.
abstract void	renameTo(java.lang.String name) Renames the folder to the given name.
MailMessage[]	search(SearchKey key) Searches the folder with the given key.
void	setFlags(MailFlag flag, boolean set) Sets/unsets the given message flags in the whole folder.
void	setFlags(java.util.Set flags) Modifies the given message flags in the whole folder.
java.lang.String	toString() Returns the string representation of the folder.

Methods inherited from class java.lang.Object

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

Field Detail

READ_ONLY

public static final int READ_ONLY

Indicates that the folder must be open as read-only.

See Also:

open(int), Constant Field Values

READ_WRITE

public static final int READ_WRITE

Indicates that the folder should be open as read-write.

See Also:

open(int), Constant Field Values

INBOX

public static final java.lang.String INBOX

Default name for the inbox folder.

The name of folder containing the incoming messages must be always "INBOX".

See Also:

Constant Field Values

user

protected java.lang.String user

The identification of a user which the folder belongs to.

store

protected MailStore store

The mail store which the folder belongs to.

parent

protected MailFolder parent

The parent folder of the mail folder.

Null value means that the folder is the top-level folder in the folder hierarchy. Such folders we call the default folders. They may contain another subfolders but no messages.

Constructor Detail

MailFolder

protected MailFolder(java.lang.String user,
                     MailStore store,
                     MailFolder parent)

Creates a new MailFolder.

Parameters:

user - the user identification which this folder belongs to

store - the store which this folder belongs to

parent - the parent folder or null if this is the default folder

Method Detail

getName

public abstract java.lang.String getName()

Returns the name of the folder.

Returns:

the folder name

getFullName

public abstract java.lang.String getFullName()

Returns the full name of the folder.

Returns the full name of the folder as it may be identified within the whole folder hierarchy. The particular name components must be separated by a char returned via the getSeparator() method.

Returns:

the full name of the folder

getSeparator

public abstract char getSeparator()

Returns the folder separator character.

The recommended separator character to use is "." or "/".

Returns:

the separator character

exists

public abstract boolean exists()

Whether this folder exists.

Returns:

true if this folder exists, false otherwise.

create

public abstract void create()
                     throws MailException

Creates this folder.

The method returns silently if the folder exists already.

An appropriate FolderEvent should be generated and dispatched when a new folder is created by this method.

Throws:

MailException - if the folder could not be created

getNextUID

public abstract long getNextUID()
                         throws MailException

Returns the next predicted UID of this folder.

UIDs must be assigned to messages in a strictly ascending order and the particular UID must not be used twise unless the folder's UID validity value changes between the assignments. The array of messages returned from the getMessages() method must be sorted by the UID numbers.

The returned value must be an unsigned 32bit integer.

This method is valid only for non-default open folders, otherwise a MailException is thrown.

Returns:

the next UID

Throws:

MailException - if an error occured

getUIDValidity

public abstract long getUIDValidity()
                             throws MailException

Returns the UID validity timestamp.

If this value changes, the UIDs of the contained messages must be no longer considered valid so the client should refresh the cached information about the folder.

The returned value must be an unsigned 32bit integer.

This method is valid only for non-default open folders, otherwise a MailException is thrown.

Returns:

the UID validity timestamp

Throws:

MailException - if an error occured

open

public abstract void open(int mode)
                   throws MailException

Opens this folder.

The mode parameter may by either READ_ONLY or READ_WRITE. Read-only folders must not allow any permanent changes to their state. One exception to his rule is checking new messages via the getNewMessages() method, since it may add a newly arrived message to the folder. However, the \Recent flag of new messages must not be unset when closing such read-only folder.

It is completely OK if a folder opens as read-only even if the mode parameter was set to READ_WRITE. This would mean that the folder for any reason refuses the read-write access. A typical example is to avoid simultaneous write access to a single folder, if it is open already by another process. However, if the mode parameter was set to READ_ONLY, the folder must not open itself as read-write in any case.

An appropriate FolderEvent should be generated and dispatched when a folder is open by this method.

This method is valid only for existing non-default folders, which are not open, otherwise a MailException is thrown.

Parameters:

mode - either READ_ONLY or READ_WRITE constant

Throws:

MailException - if the folder could not be opened

getMode

public abstract int getMode()
                     throws MailException

Returns the mode used to open the folder.

This method is valid only for open folders, otherwise a MailException is thrown.

Returns:

either READ_ONLY or READ_WRITE constant

Throws:

MailException - if an error occured

See Also:

open(int)

isOpen

public abstract boolean isOpen()
                        throws MailException

Checks whether the folder is open.

This method is valid only for existing non-default folders, otherwise a MailException is thrown.

Returns:

true if the folder is open, false otherwise

Throws:

MailException - if an error occured

See Also:

isReadOnly()

renameTo

public abstract void renameTo(java.lang.String name)
                       throws MailException

Renames the folder to the given name.

This operation may change the UID validity value as returned by getUIDValidity() method.

The name parameter must be a full name of the new folder.

An appropriate FolderEvent should be generated and dispatched when a folder is renamed by this method.

This method is valid only for existing non-default folders, which are not open, otherwise a MailException is thrown.

Parameters:

name - new folder name

Throws:

MailException - if an error occured

delete

public abstract void delete()
                     throws MailException

Deletes the folder and its content.

This method deletes the whole folder tree including subfolders and messages.

An appropriate FolderEvent should be generated and dispatched when a folder is deleted by this method.

This method is valid only for existing non-default folders, which are not open, otherwise a MailException is thrown.

Throws:

MailException - if an error occured

close

public abstract void close(boolean clearRecent)
                    throws MailException

Closes the folder.

The \Recent flag of the messages is cleared permanently if the clearRecent parameter is true and the folder is open as read-write.

An appropriate FolderEvent should be generated and dispatched when a folder is closed by this method.

This method is valid only for open folders, otherwise a MailException is thrown.

Parameters:

clearRecent - true to clear the \Recent flag, false otherwise

Throws:

MailException - if an error occured.

getMessages

public abstract MailMessage[] getMessages()
                                   throws MailException

Returns messages contained by this folder.

This method is valid only for open folders, otherwise a MailException is thrown.

Returns:

array of messages

Throws:

MailException - if an error occured

getNewMessages

public abstract MailMessage[] getNewMessages()
                                      throws MailException

Checks for new messages in the folder.

When a new message is added to the folder it may not be immediatelly available via the getMessages() method. The getNewMessages() method should be called explicitly to allow the folder to check for newly arrived messages and to update its internal state. This mechanism allows to add messages to folders which are not even open, thus simplifying simultaneous access to the folder. All new messages returned by this method must have the \Recent flag set permanently, even if the folder is open as read-only.

An appropriate MessageCountEvent should be generated and dispatched when a new messages are added to the folder.

This method is valid only for open folders, otherwise a MailException is thrown.

Returns:

array of new messages

Throws:

MailException - if an error occured

copyMessage

public abstract void copyMessage(MailMessage message)
                          throws java.io.IOException,
                                 MailException

Copies the given message to the folder.

The source message flags must be copied also.

Please note that the folder's internal state may not automatically reflect this change and that the getNewMessages() method should be called explicitly to make the new messages available via the getMessages() method.

This method is valid only for existing non-default folders, otherwise a MailException is thrown.

Parameters:

message - the source message

Throws:

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

MailException - if an error occured

addMessage

public abstract void addMessage(long time,
                                java.util.Set flags,
                                java.io.InputStream in)
                         throws java.io.IOException,
                                MailException

Adds the given message to the folder.

The message content is read from the given input stream. If the time parameter is greater or equal to zero, the message internal date must be set to this value. If the flags parameter is not empty, the message flags must be set according to MailFlag instances found in this collection.

Please note that the folder's internal state may not automatically reflect this change and that the getNewMessages() method should be called explicitly to make the new messages available via the getMessages() method.

This method is valid only for existing non-default folders, otherwise a MailException is thrown.

Parameters:

time - the message internal date

flags - the message flags

in - the input stream to read message from

Throws:

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

MailException - if an error occured

expunge

public abstract MailMessage[] expunge()
                               throws MailException

Expunges the messages.

This method permanently removes all messages from the folder, which are marked as deleted by the "\Deleted" flag. The removed messages are returned in the resulting array. A call to MailMessage.isExpunged() must return true for all expunged messages.

An appropriate MessageCountEvent should be generated and dispatched when the messages are removed from the folder.

This method is valid only for folders, which are open as read-write, otherwise a MailException is thrown.

Returns:

the expunged messages

Throws:

MailException - if an error occured

getFolder

public abstract MailFolder getFolder(java.lang.String folder)
                              throws MailException

Returns a subfolder of the folder.

Parameters:

folder - the folder name

Returns:

the subfolder

Throws:

MailException - if an error occured

listFolders

public abstract MailFolder[] listFolders(java.lang.String pattern)
                                  throws MailException

List subfolders of the folder.

This method is valid only for existing folders, otherwise a MailException is thrown.

Parameters:

pattern - the search pattern

Returns:

the list of subfolders

Throws:

MailException - if an error occured

handleMailEvent

public abstract void handleMailEvent(MailEvent event)
                              throws MailException

Handles the given mail event.

Specified by:

handleMailEvent in interface MailEventListener

Parameters:

event - the mail event

Throws:

MailException - if an error occured

getUser

public java.lang.String getUser()

Returns an identification of the user which this folder belongs to.

Returns:

the user name

getParent

public MailFolder getParent()

Returns the parent folder.

Returns:

the parent folder or null if this is the default folder

isDefaultFolder

public boolean isDefaultFolder()

Checks whether the folder is the default folder.

A default folder may contain only subfolders but no messages, thus some of the message-oriented operations are not permitted on it.

Returns:

true if the folder is default, false otherwise

isReadOnly

public boolean isReadOnly()
                   throws MailException

Checks whether this folder is open in READ_ONLY mode.

This is a template method, which calls the getMode() method to obtain the actual mode.

This method is valid only for open folders, otherwise a MailException is thrown.

Returns:

true if the folder is in read-only mode, false otherwise

Throws:

MailException - if an error occured

See Also:

open(int)

getMessage

public MailMessage getMessage(int number)
                       throws MailException

Returns a message by the given number.

This is a template method, which calls the getMessages() method to obtain the messages. It may be overriden for a better performance.

Parameters:

number - the message number

Returns:

the message

Throws:

MailException - if the message was not found or another error occured

getMessage

public MailMessage getMessage(long uid)
                       throws MailException

Returns a message by the given UID.

This is a template method, which calls the getMessages() method to obtain the messages. It may be overriden for a better performance.

Parameters:

uid - the message UID

Returns:

the message

Throws:

MailException - if the message was not found or another error occured

getMessageCount

public int getMessageCount()
                    throws MailException

Returns the total message count.

The expunged messages are not included in the returned value.

This is a template method, which calls the getMessages() method to obtain the messages. It may be overriden for a better performance.

Returns:

the count of all messages in the folder except the expunged ones

Throws:

MailException - if an error occured

getMessageCount

public int getMessageCount(MailFlag flag,
                           boolean set)
                    throws MailException

Returns the count of messages with the given flag set/unset.

The expunged messages are not included in the returned value.

This is a template method, which calls the getMessages() method to obtain the messages. It may be overriden for a better performance.

Returns:

the count of all messages in the folder except the expunged ones

Throws:

MailException - if an error occured

getFirstUnseen

public int getFirstUnseen()
                   throws MailException

Returns the number of the first unseen message.

Returns the number of the first message which has not set the \Seen flag.

This is a template method, which calls the getMessages() method to obtain the messages. It may be overriden for a better performance.

Returns:

the first unseen message number

Throws:

MailException - if an error occured

getSize

public long getSize()
             throws MailException

Returns the size of all messages in the folder.

The expunged messages are not included in the returned value.

This is a template method, which calls the getMessages() method to obtain the messages. It may be overriden for a better performance.

Returns:

the size of the folder

Throws:

MailException - if an error occured

getSize

public long getSize(MailFlag flag,
                    boolean set)
             throws MailException

Returns the size of messages in the folder with the given flag set/unset.

The expunged messages are not included in the returned value.

This is a template method, which calls the getMessages() method to obtain the messages. It may be overriden for a better performance.

Returns:

the size of the folder

Throws:

MailException - if an error occured

setFlags

public void setFlags(MailFlag flag,
                     boolean set)
              throws MailException

Sets/unsets the given message flags in the whole folder.

This is a template method, which calls the getMessages() method to obtain the messages. It may be overriden for a better performance.

Parameters:

flag - the mail flag to set/unset

set - true to set the flag, false to unset

Throws:

MailException - if an error occured

setFlags

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

Modifies the given message flags in the whole folder.

All flags contained in the flags collection are set and the rest of the flags are unset for all messages in the folder.

This is a template method, which calls the getMessages() method to obtain the messages. It may be overriden for a better performance.

Parameters:

flags - the flags to modify

Throws:

MailException - if an error occured

search

public MailMessage[] search(SearchKey key)
                     throws MailException

Searches the folder with the given key.

This method returns an array of messages matching the given search key.

If a MailException is thrown by the search key while matching a message, it is catched and added to the key's list of errors via its addError method, and the searching process continues with the next message in the folder.

This is a template method, which calls getMessages() method first to obtain the array of messages and applies the given search key on it. It may be overriden for better performance.

Parameters:

key - the search key

Returns:

array of matched messages

Throws:

MailException - if an error occured

toString

public java.lang.String toString()

Returns the string representation of the folder.

Returns:

the folder's full name

compareTo

public int compareTo(java.lang.Object o)

Compares the folder to another folder.

Folders are compared lexically according to the full folder name. Since this class implements the Comparable interface, an array of folders may be sorted easily by their full names.

Specified by:

compareTo in interface java.lang.Comparable

Parameters:

o - the another object to compare

getMailStore

protected MailStore getMailStore()

Returns the mail store which this folder belongs to.

Returns:

mail store

dispatchMailEvent

protected final void dispatchMailEvent(MailEvent event)

Dispatches the given mail event.

It dispatches the event by passing it to the event dispatching method of the associated mail store.

Parameters:

event - the mail event

finalize

protected void finalize()
                 throws java.lang.Throwable

Fianalizes the object.

It closes the folder if it is still open in the moment of finalizing.

Throws:

java.lang.Throwable