public interface IMailMessageStorage
IMailMessageStorage
- Offers basic access methods to mail message storage.Modifier and Type | Field and Description |
---|---|
static MailMessage[] |
EMPTY_RETVAL
The empty return value; e.g. may be used to indicate no result on
searchMessages(String, IndexRange, MailSortField, OrderDirection, SearchTerm, MailField[]) . |
Modifier and Type | Method and Description |
---|---|
java.lang.String[] |
appendMessages(java.lang.String destFolder,
MailMessage[] msgs)
Appends given messages to given folder.
|
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.
|
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.
|
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.
|
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).
|
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.
|
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.
|
static final MailMessage[] EMPTY_RETVAL
searchMessages(String, IndexRange, MailSortField, OrderDirection, SearchTerm, MailField[])
.java.lang.String[] appendMessages(java.lang.String destFolder, MailMessage[] msgs) throws com.openexchange.exception.OXException
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.java.lang.String[] copyMessages(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
.
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.
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.void deleteMessages(java.lang.String folder, java.lang.String[] mailIds, boolean hardDelete) throws com.openexchange.exception.OXException
If no mail could be found for a given mail ID, it is treated as a no-op.
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.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
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
MailPart getAttachment(java.lang.String folder, java.lang.String mailId, java.lang.String sequenceId) throws com.openexchange.exception.OXException
sequenceId
.
If no mail could be found for given mail ID, returned mail part is null
.
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
.MailPart getImageAttachment(java.lang.String folder, java.lang.String mailId, java.lang.String contentId) throws com.openexchange.exception.OXException
Content-Id
header given through
argument contentId
.
If no mail could be found for given mail ID, returned mail part is null
.
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
.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.
folder
- The folder identifiermailIds
- The mail identifierscom.openexchange.exception.OXException
- If plain texts cannot be returnedMailMessage 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.
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 returnedMailMessage[] getMessages(java.lang.String folder, java.lang.String[] mailIds, MailField[] fields) throws com.openexchange.exception.OXException
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.
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 returnedMailMessage[] getThreadSortedMessages(java.lang.String folder, IndexRange indexRange, MailSortField sortField, OrderDirection order, SearchTerm<?> searchTerm, MailField[] fields) throws com.openexchange.exception.OXException
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".
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 returnedMailMessage[] getUnreadMessages(java.lang.String folder, MailSortField sortField, OrderDirection order, MailField[] fields, int limit) throws com.openexchange.exception.OXException
EMPTY_RETVAL
may be returned if no unseen messages available in specified folder.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.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
.
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.void releaseResources() throws com.openexchange.exception.OXException
MailAccess
com.openexchange.exception.OXException
- If resources cannot be releasedMailMessage saveDraft(java.lang.String draftFullname, ComposedMailMessage draftMail) throws com.openexchange.exception.OXException
draftFullname
- The full name of default drafts folderdraftMail
- The draft mail as a composed mailcom.openexchange.exception.OXException
- If saving specified draft message failsMailMessage[] searchMessages(java.lang.String folder, IndexRange indexRange, MailSortField sortField, OrderDirection order, SearchTerm<?> searchTerm, MailField[] fields) throws com.openexchange.exception.OXException
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.
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 returnedvoid updateMessageColorLabel(java.lang.String folder, java.lang.String[] mailIds, int colorLabel) throws com.openexchange.exception.OXException
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).
folder
- The folder full namemailIds
- The mail IDscolorLabel
- The color label to applycom.openexchange.exception.OXException
- If color label cannot be updatedvoid updateMessageFlags(java.lang.String folder, java.lang.String[] mailIds, int flags, boolean set) throws com.openexchange.exception.OXException
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.
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 updatedMailMessage[] getNewAndModifiedMessages(java.lang.String folder, MailField[] fields) throws com.openexchange.exception.OXException
folder
- The folder full namefields
- The fields to pre-fill in returned instances of MailMessage
com.openexchange.exception.OXException
- If mails cannot be returnedMailMessage[] getDeletedMessages(java.lang.String folder, MailField[] fields) throws com.openexchange.exception.OXException
folder
- The folder full namefields
- The fields to pre-fill in returned instances of MailMessage
com.openexchange.exception.OXException
- If mails cannot be returned