com.openexchange.mail.api
Class MailMessageStorage

java.lang.Object
  com.openexchange.mail.api.MailMessageStorage

All Implemented Interfaces:

IMailMessageStorage

Direct Known Subclasses:

MailMessageStorageLong

public abstract class MailMessageStorage
extends java.lang.Object
implements IMailMessageStorage

MailMessageStorage - Abstract implementation of IMailMessageStorage.

Author:

Thorben Betten

Field Summary

Fields inherited from interface com.openexchange.mail.api.IMailMessageStorage

EMPTY_RETVAL

Constructor Summary

MailMessageStorage()

Method Summary

abstract java.lang.String[]	appendMessages(java.lang.String destFolder, MailMessage[] msgs) Appends given messages to given folder.
abstract java.lang.String[]	copyMessages(java.lang.String sourceFolder, java.lang.String destFolder, java.lang.String[] mailIds, boolean fast) Copies the mails identified through given mail IDs from source folder to destination folder.
abstract void	deleteMessages(java.lang.String folder, java.lang.String[] mailIds, boolean hardDelete) Deletes the messages located in given folder identified through given mail IDs.
MailMessage[]	getAllMessages(java.lang.String folder, IndexRange indexRange, MailSortField sortField, OrderDirection order, MailField[] fields) A convenience method that delivers all messages contained in given folder through invoking searchMessages() without search arguments.
MailPart	getAttachment(java.lang.String folder, java.lang.String mailId, java.lang.String sequenceId) A convenience method that fetches the mail message's attachment identified through given sequenceId.
MailMessage[]	getDeletedMessages(java.lang.String folder, MailField[] fields) Gets all deleted messages in specified folder.
MailPart	getImageAttachment(java.lang.String folder, java.lang.String mailId, java.lang.String contentId) A convenience method that fetches the mail message's image attachment identified by its Content-Id header given through argument contentId.
MailMessage	getMessage(java.lang.String folder, java.lang.String mailId, boolean markSeen) Gets the mail located in given folder whose mail ID matches specified ID.
abstract MailMessage[]	getMessages(java.lang.String folder, java.lang.String[] mailIds, MailField[] fields) Gets the mails located in given folder whose mail ID matches specified ID.
MailMessage[]	getNewAndModifiedMessages(java.lang.String folder, MailField[] fields) Gets all new and modified messages in specified folder.
MailMessage[]	getThreadSortedMessages(java.lang.String folder, IndexRange indexRange, MailSortField sortField, OrderDirection order, SearchTerm<?> searchTerm, MailField[] fields) An optional convenience method that gets the messages located in given folder sorted by message thread reference.
MailMessage[]	getUnreadMessages(java.lang.String folder, MailSortField sortField, OrderDirection order, MailField[] fields, int limit) Gets all unread messages located in given folder; meaning messages that do not have the \Seen flag set.
java.lang.String[]	moveMessages(java.lang.String sourceFolder, java.lang.String destFolder, java.lang.String[] mailIds, boolean fast) Moves the mails identified through given mail IDs from source folder to destination folder.
abstract void	releaseResources() Releases all resources used by this message storage when closing superior MailAccess
MailMessage	saveDraft(java.lang.String draftFullname, ComposedMailMessage draftMail) A convenience method that saves given draft mail to default drafts folder and supports deletion of old draft's version (draft-edit operation).
abstract MailMessage[]	searchMessages(java.lang.String folder, IndexRange indexRange, MailSortField sortField, OrderDirection order, SearchTerm<?> searchTerm, MailField[] fields) Searches mails located in given folder.
void	updateMessageColorLabel(java.lang.String folder, java.lang.String[] mailIds, int colorLabel) An optional method that updates the color label of the messages specified by given mail IDs located in given folder.
abstract void	updateMessageFlags(java.lang.String folder, java.lang.String[] mailIds, int flags, boolean set) Updates the flags of the messages specified by given mail IDs located in given folder.

Methods inherited from class java.lang.Object

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

Constructor Detail

MailMessageStorage

public MailMessageStorage()

Method Detail

appendMessages

public abstract java.lang.String[] appendMessages(java.lang.String destFolder,
                                                  MailMessage[] msgs)
                                           throws MailException

Description copied from interface: IMailMessageStorage

Appends given messages to given folder.

Specified by:

appendMessages in interface IMailMessageStorage

Parameters:

destFolder - The destination folder

msgs - - The messages to append (must be completely pre-filled incl. content references)

Returns:

The corresponding mail IDs in destination folder

Throws:

MailException - If messages cannot be appended.

copyMessages

public abstract java.lang.String[] copyMessages(java.lang.String sourceFolder,
                                                java.lang.String destFolder,
                                                java.lang.String[] mailIds,
                                                boolean fast)
                                         throws MailException

Description copied from interface: IMailMessageStorage

Copies the mails identified through given mail IDs from source folder to destination folder.

If no mail could be found for a given mail ID, the corresponding value in returned array of String is null.

Moreover the implementation should take care if a copy operation from or to default drafts folder is performed. If so, this method should ensure that system flag DRAFT is enabled or disabled.

Specified by:

copyMessages in interface IMailMessageStorage

Parameters:

sourceFolder - The source folder fullname

destFolder - The destination folder fullname

mailIds - The mail IDs in source folder

fast - true to perform a fast copy operation, meaning the corresponding mail IDs in destination folder are ignored and an empty array of String is returned; otherwise false

Returns:

The corresponding mail IDs if copied messages in destination folder

Throws:

MailException - If messages cannot be copied.

deleteMessages

public abstract void deleteMessages(java.lang.String folder,
                                    java.lang.String[] mailIds,
                                    boolean hardDelete)
                             throws MailException

Description copied from interface: IMailMessageStorage

Deletes the messages located in given folder identified through given mail IDs.

If no mail could be found for a given mail ID, it is treated as a no-op.

Specified by:

deleteMessages in interface IMailMessageStorage

Parameters:

folder - The folder fullname

mailIds - The mail IDs

hardDelete - true to hard delete the messages, meaning not to create a backup copy of each message in default trash folder; otherwise false

Throws:

MailException - If messages cannot be deleted.

getAllMessages

public MailMessage[] getAllMessages(java.lang.String folder,
                                    IndexRange indexRange,
                                    MailSortField sortField,
                                    OrderDirection order,
                                    MailField[] fields)
                             throws MailException

A convenience method that delivers all messages contained in given folder through invoking searchMessages() without search arguments.

Note that sorting needs not to be supported by underlying mailing system. This can be done n application side, too

This method may be overridden in implementing subclass if a faster way can be achieved.

Specified by:

getAllMessages in interface IMailMessageStorage

Parameters:

folder - The folder fullname

indexRange - The index range specifying the desired sub-list in sorted list; may be null to obtain complete list. Range begins at the specified start index and extends to the message at index end - 1. Thus the length of the range is end - start.

sortField - The sort field

order - Whether ascending or descending sort order

fields - The fields to pre-fill in returned instances of MailMessage

Returns:

The desired, pre-filled instances of MailMessage

Throws:

MailException

getAttachment

public MailPart getAttachment(java.lang.String folder,
                              java.lang.String mailId,
                              java.lang.String sequenceId)
                       throws MailException

Description copied from interface: IMailMessageStorage

A convenience method that fetches the mail message's attachment identified through given sequenceId.

If no mail could be found for given mail ID, returned mail part is null.

Specified by:

getAttachment in interface IMailMessageStorage

Parameters:

folder - The folder fullname

mailId - The mail ID

sequenceId - The attachment sequence ID

Returns:

The attachment wrapped by a MailPart instance

Throws:

MailException - If no attachment can be found whose sequence ID matches given sequenceId.

getImageAttachment

public MailPart getImageAttachment(java.lang.String folder,
                                   java.lang.String mailId,
                                   java.lang.String contentId)
                            throws MailException

Description copied from interface: IMailMessageStorage

A convenience method that fetches the mail message's image attachment identified by its Content-Id header given through argument contentId.

If no mail could be found for given mail ID, returned mail part is null.

Specified by:

getImageAttachment in interface IMailMessageStorage

Parameters:

folder - The folder fullname

mailId - The mail ID

contentId - The value of header Content-Id

Returns:

The image attachment wrapped by an MailPart instance

Throws:

MailException - If no image can be found whose Content-Id header matches given contentId.

getMessage

public MailMessage getMessage(java.lang.String folder,
                              java.lang.String mailId,
                              boolean markSeen)
                       throws MailException

Gets the mail located in given folder whose mail ID matches specified ID.

This is a convenience method that invokes getMessages(String, String[], MailField[]) with specified mail ID and MailField.FULL. Thus the returned instance of MailMessage is completely pre-filled including content references.

If no mail could be found for given mail ID, null is returned.

This method may be overridden in implementing subclass if a faster way can be achieved.

Specified by:

getMessage in interface IMailMessageStorage

Parameters:

folder - The folder fullname

mailId - The mail ID

markSeen - true to explicitly mark corresponding mail as seen (setting system flag \Seen); otherwise false to leave as-is

Returns:

Corresponding message

Throws:

MailException - If message could not be returned

getMessages

public abstract MailMessage[] getMessages(java.lang.String folder,
                                          java.lang.String[] mailIds,
                                          MailField[] fields)
                                   throws MailException

Description copied from interface: IMailMessageStorage

Gets the mails located in given folder whose mail ID matches specified ID. The constant IMailMessageStorage.EMPTY_RETVAL may be returned, if folder contains no messages.

The returned instances of MailMessage are pre-filled with specified fields through argument fields.

If any mail ID is invalid, null is returned for that entry.

Specified by:

getMessages in interface IMailMessageStorage

Parameters:

folder - The folder fullname

mailIds - The mail IDs

fields - The fields to pre-fill in returned instances of MailMessage

Returns:

Corresponding mails as an array

Throws:

MailException - If message could not be returned

getThreadSortedMessages

public MailMessage[] getThreadSortedMessages(java.lang.String folder,
                                             IndexRange indexRange,
                                             MailSortField sortField,
                                             OrderDirection order,
                                             SearchTerm<?> searchTerm,
                                             MailField[] fields)
                                      throws MailException

Description copied from interface: IMailMessageStorage

An optional convenience method that gets the messages located in given folder sorted by message thread reference. By default null is returned assuming that mailing system does not support message thread reference, but may be overridden if it does.

If underlying mailing system is IMAP, this method requires the IMAPv4 SORT extension or in detail the IMAP CAPABILITY command should contain "SORT THREAD=ORDEREDSUBJECT THREAD=REFERENCES".

Specified by:

getThreadSortedMessages in interface IMailMessageStorage

Parameters:

folder - The folder fullname

indexRange - The index range specifying the desired sub-list in sorted list; may be null to obtain complete list. Range begins at the specified start index and extends to the message at index end - 1. Thus the length of the range is end - start.

sortField - The sort field applied to thread root elements

order - Whether ascending or descending sort order

searchTerm - The search term

fields - The fields to pre-fill in returned instances of MailMessage

Returns:

The thread-sorted messages or null if SORT is not supported by mail server

Throws:

MailException - If messages cannot be returned

getUnreadMessages

public MailMessage[] getUnreadMessages(java.lang.String folder,
                                       MailSortField sortField,
                                       OrderDirection order,
                                       MailField[] fields,
                                       int limit)
                                throws MailException

Gets all unread messages located in given folder; meaning messages that do not have the \Seen flag set. The constant IMailMessageStorage.EMPTY_RETVAL may be returned if no unseen messages available in specified folder.

This is a convenience method that may be overridden if a faster way can be achieved.

Specified by:

getUnreadMessages in interface IMailMessageStorage

Parameters:

folder - The folder fullname

sortField - The sort field

order - The sort order

fields - The fields to pre-fill in returned instances of MailMessage

limit - The max. number of returned unread messages or -1 to request all unread messages in folder

Returns:

Unread messages contained in an array of MailMessage

Throws:

MailException - If unread messages cannot be returned.

moveMessages

public java.lang.String[] moveMessages(java.lang.String sourceFolder,
                                       java.lang.String destFolder,
                                       java.lang.String[] mailIds,
                                       boolean fast)
                                throws MailException

Moves the mails identified through given mail IDs from source folder to destination folder.

If no mail could be found for a given mail ID, the corresponding value in returned array of String is null.

This is a convenience method that may be overridden if a faster way can be achieved.

Specified by:

moveMessages in interface IMailMessageStorage

Parameters:

sourceFolder - The source folder fullname

destFolder - The destination folder fullname

mailIds - The mail IDs in source folder

fast - true to perform a fast move operation, meaning the corresponding mail IDs in destination folder are ignored and an empty array of String is returned; otherwise false

Returns:

The corresponding mail IDs if copied messages in destination folder

Throws:

MailException - If messages cannot be copied.

releaseResources

public abstract void releaseResources()
                               throws MailException

Description copied from interface: IMailMessageStorage

Releases all resources used by this message storage when closing superior MailAccess

Specified by:

releaseResources in interface IMailMessageStorage

Throws:

MailException - If resources cannot be released

saveDraft

public MailMessage saveDraft(java.lang.String draftFullname,
                             ComposedMailMessage draftMail)
                      throws MailException

Description copied from interface: IMailMessageStorage

A convenience method that saves given draft mail to default drafts folder and supports deletion of old draft's version (draft-edit operation).

Specified by:

saveDraft in interface IMailMessageStorage

Parameters:

draftFullname - The fullname of default drafts folder

draftMail - The draft mail as a composed mail

Returns:

The stored draft mail

Throws:

MailException - If saving specified draft message fails

searchMessages

public abstract MailMessage[] searchMessages(java.lang.String folder,
                                             IndexRange indexRange,
                                             MailSortField sortField,
                                             OrderDirection order,
                                             SearchTerm<?> searchTerm,
                                             MailField[] fields)
                                      throws MailException

Description copied from interface: IMailMessageStorage

Searches mails located in given folder. If the search yields no results, the constant IMailMessageStorage.EMPTY_RETVAL may be returned. This method's purpose is to return filtered mails' headers for a fast list view. Therefore this method's fields parameter should only contain instances of MailField which are marked as [low cost]. Otherwise pre-filling of returned messages may take a long time and does no more fit to generate a fast list view.

Note that sorting needs not to be supported by underlying mailing system. This can be done on application side, too.
Same is for search, but in most cases it's faster to search on mailing system, but this heavily depends on how mails are accessed.

Specified by:

searchMessages in interface IMailMessageStorage

Parameters:

folder - The folder fullname

indexRange - The index range specifying the desired sub-list in sorted list; may be null to obtain complete list. Range begins at the specified start index and extends to the message at index end - 1. Thus the length of the range is end - start.

sortField - The sort field

order - Whether ascending or descending sort order

searchTerm - The search term to filter messages; may be null to obtain all messages

fields - The fields to pre-fill in returned instances of MailMessage

Returns:

The desired, pre-filled instances of MailMessage

Throws:

MailException - If mails cannot be returned

updateMessageColorLabel

public void updateMessageColorLabel(java.lang.String folder,
                                    java.lang.String[] mailIds,
                                    int colorLabel)
                             throws MailException

Description copied from interface: IMailMessageStorage

An optional method that updates the color label of the messages specified by given mail IDs located in given folder.

If no mail could be found for a given mail ID, it is treated as a no-op.

The underlying mailing system needs to support some kind of user-definable flags to support this method. Otherwise this method should be left unchanged with an empty body.

The color labels are user flags with the common prefix "cl_" and its numeric color code appended (currently numbers 0 to 10).

Specified by:

updateMessageColorLabel in interface IMailMessageStorage

Parameters:

folder - The folder fullname

mailIds - The mail IDs

colorLabel - The color label to apply

Throws:

MailException - If color label cannot be updated

updateMessageFlags

public abstract void updateMessageFlags(java.lang.String folder,
                                        java.lang.String[] mailIds,
                                        int flags,
                                        boolean set)
                                 throws MailException

Description copied from interface: IMailMessageStorage

Updates the flags of the messages specified by given mail IDs located in given folder. If parameter set is true the affected flags denoted by flags are added; otherwise removed.

If no mail could be found for a given mail ID, it is treated as a no-op.

System flags are:

• ANSWERED - This flag is set by clients to indicate that this message has been answered to.
• DELETED - Clients set this flag to mark a message as deleted. The expunge operation on a folder removes all messages in that folder that are marked for deletion.
• DRAFT - This flag is set by clients to indicate that the message is a draft message.
• FLAGGED - No semantic is defined for this flag. Clients alter this flag.
• RECENT - Folder implementations set this flag to indicate that this message is new to this folder, that is, it has arrived since the last time this folder was opened.
• SEEN - This flag is implicitly set by the implementation when the this Message's content is returned to the client in some form.Clients can alter this flag.
• USER - A special flag that indicates that this folder supports user defined flags.

If mail folder in question supports user flags (storing individual strings per message) the virtual flags can also be updated through this routine; e.g. MailMessage.FLAG_FORWARDED.

Moreover this routine checks for any spam related actions; meaning the MailMessage.FLAG_SPAM shall be enabled/disabled. Thus the SpamHandler#handleSpam(String, String[], boolean, MailAccess)/ SpamHandler#handleHam(String, String[], boolean, MailAccess) methods needs to be executed.

Specified by:

updateMessageFlags in interface IMailMessageStorage

Parameters:

folder - The folder fullname

mailIds - The mail IDs

flags - The bit pattern for the flags to alter

set - true to enable the flags; otherwise false

Throws:

MailException - If system flags cannot be updated

getNewAndModifiedMessages

public MailMessage[] getNewAndModifiedMessages(java.lang.String folder,
                                               MailField[] fields)
                                        throws MailException

Gets all new and modified messages in specified folder. By default the constant IMailMessageStorage.EMPTY_RETVAL is returned.

Specified by:

getNewAndModifiedMessages in interface IMailMessageStorage

Parameters:

folder - The folder fullname

fields - The fields to pre-fill in returned instances of MailMessage

Returns:

All new and modified messages in specified folder

Throws:

MailException - If mails cannot be returned

getDeletedMessages

public MailMessage[] getDeletedMessages(java.lang.String folder,
                                        MailField[] fields)
                                 throws MailException

Gets all deleted messages in specified folder. By default the constant IMailMessageStorage.EMPTY_RETVAL is returned.

Specified by:

getDeletedMessages in interface IMailMessageStorage

Parameters:

folder - The folder fullname

fields - The fields to pre-fill in returned instances of MailMessage

Returns:

All deleted messages in specified folder

Throws:

MailException - If mails cannot be returned