public abstract class MailMessageStorage extends java.lang.Object implements IMailMessageStorage
MailMessageStorage
- Abstract implementation of IMailMessageStorage
.EMPTY_RETVAL
Constructor and Description |
---|
MailMessageStorage() |
Modifier and Type | Method and Description |
---|---|
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.
|
java.lang.String[] |
getPrimaryContents(java.lang.String folder,
java.lang.String[] mailIds)
Gets the plain-text versions of the parts considered as primary mails' content.
|
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.
|
public abstract java.lang.String[] appendMessages(java.lang.String destFolder, MailMessage[] msgs) throws com.openexchange.exception.OXException
IMailMessageStorage
appendMessages
in interface IMailMessageStorage
destFolder
- The destination foldermsgs
- - The messages to append (must be completely pre-filled incl. content references)com.openexchange.exception.OXException
- If messages cannot be appended.public abstract java.lang.String[] copyMessages(java.lang.String sourceFolder, java.lang.String destFolder, java.lang.String[] mailIds, boolean fast) throws com.openexchange.exception.OXException
IMailMessageStorage
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.
copyMessages
in interface IMailMessageStorage
sourceFolder
- The source folder full namedestFolder
- The destination folder full namemailIds
- The mail IDs in source folderfast
- 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
com.openexchange.exception.OXException
- If messages cannot be copied.public abstract void deleteMessages(java.lang.String folder, java.lang.String[] mailIds, boolean hardDelete) throws com.openexchange.exception.OXException
IMailMessageStorage
If no mail could be found for a given mail ID, it is treated as a no-op.
deleteMessages
in interface IMailMessageStorage
folder
- The folder full namemailIds
- The mail IDshardDelete
- true
to hard delete the messages, meaning not to create a backup copy of each message in default trash
folder; otherwise false
com.openexchange.exception.OXException
- If messages cannot be deleted.public MailMessage[] getAllMessages(java.lang.String folder, IndexRange indexRange, MailSortField sortField, OrderDirection order, MailField[] fields) throws com.openexchange.exception.OXException
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.
getAllMessages
in interface IMailMessageStorage
folder
- The folder full nameindexRange
- 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 fieldorder
- Whether ascending or descending sort orderfields
- The fields to pre-fill in returned instances of MailMessage
MailMessage
com.openexchange.exception.OXException
public MailPart getAttachment(java.lang.String folder, java.lang.String mailId, java.lang.String sequenceId) throws com.openexchange.exception.OXException
IMailMessageStorage
sequenceId
.
If no mail could be found for given mail ID, returned mail part is null
.
getAttachment
in interface IMailMessageStorage
folder
- The folder full namemailId
- The mail IDsequenceId
- The attachment sequence IDMailPart
instancecom.openexchange.exception.OXException
- If no attachment can be found whose sequence ID matches given sequenceId
.public MailPart getImageAttachment(java.lang.String folder, java.lang.String mailId, java.lang.String contentId) throws com.openexchange.exception.OXException
IMailMessageStorage
Content-Id
header given through
argument contentId
.
If no mail could be found for given mail ID, returned mail part is null
.
getImageAttachment
in interface IMailMessageStorage
folder
- The folder full namemailId
- The mail IDcontentId
- The value of header Content-Id
MailPart
instancecom.openexchange.exception.OXException
- If no image can be found whose Content-Id
header matches given contentId
.public java.lang.String[] getPrimaryContents(java.lang.String folder, java.lang.String[] mailIds) throws com.openexchange.exception.OXException
If plain text for a single mail cannot be determined, null
is inserted at corresponding position in returned array.
getPrimaryContents
in interface IMailMessageStorage
folder
- The folder identifiermailIds
- The mail identifierscom.openexchange.exception.OXException
- If plain texts cannot be returnedpublic MailMessage getMessage(java.lang.String folder, java.lang.String mailId, boolean markSeen) throws com.openexchange.exception.OXException
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.
getMessage
in interface IMailMessageStorage
folder
- The folder full namemailId
- The mail IDmarkSeen
- true
to explicitly mark corresponding mail as seen (setting system flag \Seen); otherwise
false
to leave as-iscom.openexchange.exception.OXException
- If message could not be returnedpublic abstract MailMessage[] getMessages(java.lang.String folder, java.lang.String[] mailIds, MailField[] fields) throws com.openexchange.exception.OXException
IMailMessageStorage
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.
getMessages
in interface IMailMessageStorage
folder
- The folder full namemailIds
- The mail IDsfields
- The fields to pre-fill in returned instances of MailMessage
com.openexchange.exception.OXException
- If message could not be returnedpublic MailMessage[] getThreadSortedMessages(java.lang.String folder, IndexRange indexRange, MailSortField sortField, OrderDirection order, SearchTerm<?> searchTerm, MailField[] fields) throws com.openexchange.exception.OXException
IMailMessageStorage
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".
getThreadSortedMessages
in interface IMailMessageStorage
folder
- The folder full nameindexRange
- 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 elementsorder
- Whether ascending or descending sort ordersearchTerm
- The search termfields
- The fields to pre-fill in returned instances of MailMessage
null
if SORT is not supported by mail servercom.openexchange.exception.OXException
- If messages cannot be returnedpublic MailMessage[] getUnreadMessages(java.lang.String folder, MailSortField sortField, OrderDirection order, MailField[] fields, int limit) throws com.openexchange.exception.OXException
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.
getUnreadMessages
in interface IMailMessageStorage
folder
- The folder full namesortField
- The sort fieldorder
- The sort orderfields
- 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 folderMailMessage
com.openexchange.exception.OXException
- If unread messages cannot be returned.public java.lang.String[] moveMessages(java.lang.String sourceFolder, java.lang.String destFolder, java.lang.String[] mailIds, boolean fast) throws com.openexchange.exception.OXException
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.
moveMessages
in interface IMailMessageStorage
sourceFolder
- The source folder full namedestFolder
- The destination folder full namemailIds
- The mail IDs in source folderfast
- 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
com.openexchange.exception.OXException
- If messages cannot be copied.public abstract void releaseResources() throws com.openexchange.exception.OXException
IMailMessageStorage
MailAccess
releaseResources
in interface IMailMessageStorage
com.openexchange.exception.OXException
- If resources cannot be releasedpublic MailMessage saveDraft(java.lang.String draftFullname, ComposedMailMessage draftMail) throws com.openexchange.exception.OXException
IMailMessageStorage
saveDraft
in interface IMailMessageStorage
draftFullname
- The full name of default drafts folderdraftMail
- The draft mail as a composed mailcom.openexchange.exception.OXException
- If saving specified draft message failspublic abstract MailMessage[] searchMessages(java.lang.String folder, IndexRange indexRange, MailSortField sortField, OrderDirection order, SearchTerm<?> searchTerm, MailField[] fields) throws com.openexchange.exception.OXException
IMailMessageStorage
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.
searchMessages
in interface IMailMessageStorage
folder
- The folder full nameindexRange
- 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 fieldorder
- Whether ascending or descending sort ordersearchTerm
- The search term to filter messages; may be null
to obtain all messagesfields
- The fields to pre-fill in returned instances of MailMessage
MailMessage
com.openexchange.exception.OXException
- If mails cannot be returnedpublic void updateMessageColorLabel(java.lang.String folder, java.lang.String[] mailIds, int colorLabel) throws com.openexchange.exception.OXException
IMailMessageStorage
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).
updateMessageColorLabel
in interface IMailMessageStorage
folder
- The folder full namemailIds
- The mail IDscolorLabel
- The color label to applycom.openexchange.exception.OXException
- If color label cannot be updatedpublic abstract void updateMessageFlags(java.lang.String folder, java.lang.String[] mailIds, int flags, boolean set) throws com.openexchange.exception.OXException
IMailMessageStorage
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:
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.
updateMessageFlags
in interface IMailMessageStorage
folder
- The folder full namemailIds
- The mail IDsflags
- The bit pattern for the flags to alterset
- true
to enable the flags; otherwise false
com.openexchange.exception.OXException
- If system flags cannot be updatedpublic MailMessage[] getNewAndModifiedMessages(java.lang.String folder, MailField[] fields) throws com.openexchange.exception.OXException
IMailMessageStorage.EMPTY_RETVAL
is returned.getNewAndModifiedMessages
in interface IMailMessageStorage
folder
- The folder full namefields
- The fields to pre-fill in returned instances of MailMessage
com.openexchange.exception.OXException
- If mails cannot be returnedpublic MailMessage[] getDeletedMessages(java.lang.String folder, MailField[] fields) throws com.openexchange.exception.OXException
IMailMessageStorage.EMPTY_RETVAL
is returned.getDeletedMessages
in interface IMailMessageStorage
folder
- The folder full namefields
- The fields to pre-fill in returned instances of MailMessage
com.openexchange.exception.OXException
- If mails cannot be returned