org.abstracthorizon.mercury.maildir
Class MaildirFolder

java.lang.Object
  javax.mail.Folder
      org.abstracthorizon.mercury.maildir.MaildirFolder

Direct Known Subclasses:

UIDMaildirFolder

public class MaildirFolder
extends javax.mail.Folder

This class implements folder from javax.mail API.

Maildir folder is a direct subdirectory in the base structure of maildir "account". Full path of the maildir folder is contained in subdirectory's name. Components of that path are divided with forward slash ("/"). This implementation allows that subdirectory to start with a dot or without it. That is selectable under maildir.leadingDot property supplied in a session while obtaining the store. See MaildirStore. Note: subdirectories tmp, new and cur are used for "root" folder and cannot be used for names. Thus if maildir.leadingDot property contains "false" as a value then "tmp", "new" or "cur" are not permited file names. On some platforms where file system do recognise different cases "New" will be still allowed while "new" won't.

Maildir folder subdirectory contains three sub-subdirectories: tmp, new and cur

• tmp is used for adding new messages to the folder. Each message is firstly added to this folder. New file can be created in this folder and then, slowly, populated. When message file is finally output to the folder it can be then moved to new directory.
• new folder contains messages that have RECENT flag set. Messages in this implementation can have exclusively RECENT flag set or any of other flags. When RECENT is set all other flags are removed. RECENT flag is implicit - if message is in this directory then flag is set and if it is not then it is reset.
• cur directory contains messages that do not have RECENT flag set. They can have no or any flag but RECENT. Note: user defined flags are not permitted. Implementation doesn't prevent them but these flags will exist only while message object instance exists in memory.

Messages are files that contain RFC-822 messages as they are output with MimeMessage.writeTo method (or received by SMTP). Message file name is described in MaildirMessage class.

This implementation always permits messages to be written to the folder even if folder is "root" folder. If subfolders are not allowed a zero length file of a name ".nosubfolders" will be written in subdirectory and that would prevent new subfolders of being created. Existing subfolders won't be affected. Note: this implementation does not write any other files or alters the folder's directoy in any way..

Note: if subdirectory of folder's name exist this implementation will try to create tmp, new and cur subdirectories in it. Failure to do so will lead in an exception being thrown.

Author:

Daniel Sendula

Field Summary

protected javax.mail.Message[]	cacheArray
protected MaildirFolderData	folderData Folder data.
protected HashMap<javax.mail.internet.MimeMessage,MessageWrapper>	map Map that maps folder data messages to folder messages.
protected List<MessageBase>	messages Since folder must have messages ordered as at the time when it is opened this is the list that contains it.
protected boolean	opened Flag if folder is opened or not
protected MaildirStore	store Maildir store reference

Fields inherited from class javax.mail.Folder

HOLDS_FOLDERS, HOLDS_MESSAGES, mode, READ_ONLY, READ_WRITE

Constructor Summary

protected

MaildirFolder(MaildirStore store, MaildirFolderData folderData) Constructor.

Method Summary

protected MessageWrapper	addMessage(javax.mail.internet.MimeMessage msg, int num) Adds message to folder's internal storage.
protected void	addMessages(List<MaildirMessage> messages, boolean notify) Adds messages to the folder.
void	appendMessages(javax.mail.Message[] messages) Appends messages.
void	close(boolean expunge) Closes the folder.
boolean	create(int type) Creates folder.
boolean	delete(boolean recursive) Removes the folder.
boolean	exists() Return's true if folder exists.
javax.mail.Message[]	expunge() Expunges deleted messages.
javax.mail.Folder	getFolder(String name) Returns subfolder.
protected MaildirFolderData	getFolderData() Returns folder data.
List<MessageBase>	getFolderMessages() Returns folder messages.
String	getFullName() Returns folder's full name.
MaildirStore	getMaildirStore() Returns maildir store
javax.mail.Message	getMessage(int msgNum) Returns message with supplied message number
int	getMessageCount() Returns total number of messages for this folder
javax.mail.Message[]	getMessages() Returns all messages for this folder.
String	getName() Returns folder's name.
int	getNewMessageCount() Returns total number of new messages for this folder
javax.mail.Folder	getParent() Obtains parent folder from the store.
javax.mail.Flags	getPermanentFlags() Returns permanent flags.
char	getSeparator() Returns separator char
int	getType() Returns the type of the folder
protected boolean	hasMessage(javax.mail.internet.MimeMessage msg) Returns true if message is contained in this folder.
boolean	hasNewMessages() Returns true if there are new messages in this folder
boolean	isOpen() Returns true if folder is open
javax.mail.Folder[]	list(String pattern) Returns array of folders by given pattern
protected void	notifyMessageAddedListeners(javax.mail.Message[] msgs) Notifies if new messages are added to the folder
protected void	notifyMessageChangedListeners(int type, javax.mail.Message msg) Notifies that message is changed.
protected void	notifyMessageRemovedListeners(boolean removed, javax.mail.Message[] msgs) Notifies when messages are removed from this folder.
void	open(int mode) Opens the folder.
protected MessageWrapper	removeMessage(javax.mail.internet.MimeMessage msg) This medhod removes message.
protected List<? extends javax.mail.internet.MimeMessage>	removeMessages(Collection<? extends javax.mail.internet.MimeMessage> messages, boolean explicit) Removes messages from folder's representation.
boolean	renameTo(javax.mail.Folder folder) Renames the folder to given folder
protected void	setFolderMessages(List<MessageBase> messages) Sets folder messages.

Methods inherited from class javax.mail.Folder

addConnectionListener, addFolderListener, addMessageChangedListener, addMessageCountListener, copyMessages, fetch, finalize, getDeletedMessageCount, getMessages, getMessages, getMode, getStore, getUnreadMessageCount, getURLName, isSubscribed, list, listSubscribed, listSubscribed, notifyConnectionListeners, notifyFolderListeners, notifyFolderRenamedListeners, removeConnectionListener, removeFolderListener, removeMessageChangedListener, removeMessageCountListener, search, search, setFlags, setFlags, setFlags, setSubscribed, toString

Methods inherited from class java.lang.Object

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

Field Detail

store

protected MaildirStore store

Maildir store reference

opened

protected boolean opened

Flag if folder is opened or not

folderData

protected MaildirFolderData folderData

Folder data. In order to make this implementation closer to extensible API folder data is introduced. Class of MaildirFolderData is implementing all important operations on Maildir folders. This is first layer that should be extended by developer. This field is reference to instance of MaildirFolderData or any subclass of it.

messages

protected List<MessageBase> messages

Since folder must have messages ordered as at the time when it is opened this is the list that contains it.

map

protected HashMap<javax.mail.internet.MimeMessage,MessageWrapper> map

Map that maps folder data messages to folder messages.

cacheArray

protected javax.mail.Message[] cacheArray

Constructor Detail

MaildirFolder

protected MaildirFolder(MaildirStore store,
                        MaildirFolderData folderData)

Constructor.

Parameters:

store - maildir store

folderData - folder data

Method Detail

getMaildirStore

public MaildirStore getMaildirStore()

Returns maildir store

Returns:

maildir store

getFolderMessages

public List<MessageBase> getFolderMessages()

Returns folder messages. Note: This should not be used by anyone else but implementators of subclasses of Maildir API.

Returns:

folder messages

setFolderMessages

protected void setFolderMessages(List<MessageBase> messages)

Sets folder messages. Note: This should not be used by anyone else but implementators of subclasses of Maildir API.

Parameters:

messages - folder messages

getFolderData

protected MaildirFolderData getFolderData()

Returns folder data.

Returns:

folder data

getName

public String getName()

Returns folder's name.

Specified by:

getName in class javax.mail.Folder

Returns:

folder's name.

getFullName

public String getFullName()

Returns folder's full name. Full name is actually full path of the folder including folder's name.

Specified by:

getFullName in class javax.mail.Folder

Returns:

folder's full name.

getParent

public javax.mail.Folder getParent()
                            throws javax.mail.MessagingException

Obtains parent folder from the store. If folder is root then this should return null

Specified by:

getParent in class javax.mail.Folder

Returns:

parent folder

Throws:

javax.mail.MessagingException

exists

public boolean exists()
               throws javax.mail.MessagingException

Return's true if folder exists.

Specified by:

exists in class javax.mail.Folder

Returns:

true if folder exists.

Throws:

javax.mail.MessagingException

list

public javax.mail.Folder[] list(String pattern)
                         throws javax.mail.MessagingException

Returns array of folders by given pattern

Specified by:

list in class javax.mail.Folder

Parameters:

pattern - pattern to be used for filtering folders

Returns:

array of folders by given pattern

Throws:

javax.mail.MessagingException

getSeparator

public char getSeparator()
                  throws javax.mail.MessagingException

Returns separator char

Specified by:

getSeparator in class javax.mail.Folder

Returns:

separator char

Throws:

javax.mail.MessagingException

getFolder

public javax.mail.Folder getFolder(String name)
                            throws javax.mail.MessagingException

Returns subfolder.

Specified by:

getFolder in class javax.mail.Folder

Parameters:

name - name of sub folder

Returns:

subfolder

Throws:

javax.mail.MessagingException

create

public boolean create(int type)
               throws javax.mail.MessagingException

Creates folder. It returns true if folder is successfully created. Only cases it can return false are when this is root folder, parent doesn't exist and creation of it failed or creation of needed directories failed. Note: tmp, new and cur directories must be created or an exception will be thrown.

Specified by:

create in class javax.mail.Folder

Parameters:

type - See Folder.HOLDS_FOLDERS and Folder.HOLDS_MESSAGES.

Returns:

true if folder is successfully created.

Throws:

javax.mail.MessagingException

delete

public boolean delete(boolean recursive)
               throws javax.mail.MessagingException

Removes the folder. It can return false if it is root folder or when deleting any files in this folder or any subfolders in case of recursive having true passed to it fails.

Specified by:

delete in class javax.mail.Folder

Parameters:

recursive - true means that all subfolders must be removed

Returns:

if folder is successfully deleted

Throws:

javax.mail.MessagingException

getType

public int getType()
            throws javax.mail.MessagingException

Returns the type of the folder

Specified by:

getType in class javax.mail.Folder

Returns:

the type of the folder

Throws:

javax.mail.MessagingException

renameTo

public boolean renameTo(javax.mail.Folder folder)
                 throws javax.mail.MessagingException

Renames the folder to given folder

Specified by:

renameTo in class javax.mail.Folder

Parameters:

folder - folder details to be used when renaming

Returns:

true if rename was successful

Throws:

javax.mail.MessagingException - thrown if folder is not opened

open

public void open(int mode)
          throws javax.mail.MessagingException

Opens the folder. Mode is ignored in this implementation

Specified by:

open in class javax.mail.Folder

Parameters:

mode - mode folder to be opened in.

Throws:

javax.mail.MessagingException - thrown if folder is not opened or does not exist

close

public void close(boolean expunge)
           throws javax.mail.MessagingException

Closes the folder. It releases resources it has allocated.

Specified by:

close in class javax.mail.Folder

Parameters:

expunge - if folder are not expunged

Throws:

javax.mail.MessagingException - if folder is not opened

appendMessages

public void appendMessages(javax.mail.Message[] messages)
                    throws javax.mail.MessagingException

Appends messages.

Specified by:

appendMessages in class javax.mail.Folder

Parameters:

messages - messages to be appended

Throws:

javax.mail.MessagingException - if folder doesn't exist

expunge

public javax.mail.Message[] expunge()
                             throws javax.mail.MessagingException

Expunges deleted messages. It renumerates messages as well.

Specified by:

expunge in class javax.mail.Folder

Returns:

array of expunged messages

Throws:

javax.mail.MessagingException - if folder is not opened

addMessages

protected void addMessages(List<MaildirMessage> messages,
                           boolean notify)
                    throws javax.mail.MessagingException

Adds messages to the folder. It is called by MaildirFolderData

Parameters:

messages - messages to be added

notify - should folder listeners be notified for new messages to be added

Throws:

javax.mail.MessagingException

removeMessages

protected List<? extends javax.mail.internet.MimeMessage> removeMessages(Collection<? extends javax.mail.internet.MimeMessage> messages,
                                                                         boolean explicit)
                                                                  throws javax.mail.MessagingException

Removes messages from folder's representation.

Parameters:

messages - messages to be removed

explicit - when notifying pass if messages removed because of explicit expunge method called

Returns:

list of removed messages from this folder

Throws:

javax.mail.MessagingException

addMessage

protected MessageWrapper addMessage(javax.mail.internet.MimeMessage msg,
                                    int num)
                             throws javax.mail.MessagingException

Adds message to folder's internal storage. This method wraps message as well.

Parameters:

msg - folder data message

num - message number

Returns:

wrapped message

Throws:

javax.mail.MessagingException

removeMessage

protected MessageWrapper removeMessage(javax.mail.internet.MimeMessage msg)
                                throws javax.mail.MessagingException

This medhod removes message. Argument could be folder's message or folder data's message.

Parameters:

msg - message to be removed

Returns:

wrapped message that is removed

Throws:

javax.mail.MessagingException

hasMessage

protected boolean hasMessage(javax.mail.internet.MimeMessage msg)
                      throws javax.mail.MessagingException

Returns true if message is contained in this folder.

Parameters:

msg - folder data's message or folder's message

Returns:

true if message is contained in this folder.

Throws:

javax.mail.MessagingException

isOpen

public boolean isOpen()

Returns true if folder is open

Specified by:

isOpen in class javax.mail.Folder

Returns:

true if folder is open

getPermanentFlags

public javax.mail.Flags getPermanentFlags()

Returns permanent flags.

Specified by:

getPermanentFlags in class javax.mail.Folder

Returns:

permanent folder's flags.

notifyMessageChangedListeners

protected void notifyMessageChangedListeners(int type,
                                             javax.mail.Message msg)

Notifies that message is changed.

Overrides:

notifyMessageChangedListeners in class javax.mail.Folder

Parameters:

type - type of change

msg - message that is changed

notifyMessageAddedListeners

protected void notifyMessageAddedListeners(javax.mail.Message[] msgs)

Notifies if new messages are added to the folder

Overrides:

notifyMessageAddedListeners in class javax.mail.Folder

Parameters:

msgs - messages that are added

notifyMessageRemovedListeners

protected void notifyMessageRemovedListeners(boolean removed,
                                             javax.mail.Message[] msgs)

Notifies when messages are removed from this folder.

Overrides:

notifyMessageRemovedListeners in class javax.mail.Folder

Parameters:

removed - if messages are removed

msgs - messages that are removed

hasNewMessages

public boolean hasNewMessages()
                       throws javax.mail.MessagingException

Returns true if there are new messages in this folder

Specified by:

hasNewMessages in class javax.mail.Folder

Returns:

true if there are new messages in this folder

Throws:

javax.mail.MessagingException

getMessageCount

public int getMessageCount()
                    throws javax.mail.MessagingException

Returns total number of messages for this folder

Specified by:

getMessageCount in class javax.mail.Folder

Returns:

total number of messages for this folder

Throws:

javax.mail.MessagingException

getNewMessageCount

public int getNewMessageCount()
                       throws javax.mail.MessagingException

Returns total number of new messages for this folder

Overrides:

getNewMessageCount in class javax.mail.Folder

Returns:

total number of new messages for this folder

Throws:

javax.mail.MessagingException

getMessage

public javax.mail.Message getMessage(int msgNum)
                              throws javax.mail.MessagingException

Returns message with supplied message number

Specified by:

getMessage in class javax.mail.Folder

Parameters:

msgNum - number of message that is requested

Returns:

message with supplied message number

Throws:

javax.mail.MessagingException - if folder is not opened

getMessages

public javax.mail.Message[] getMessages()
                                 throws javax.mail.MessagingException

Returns all messages for this folder.

Overrides:

getMessages in class javax.mail.Folder

Returns:

all messages for this folder

Throws:

javax.mail.MessagingException - if folder is not opened