com.openexchange.messaging
Interface MessagingMessageAccess

public interface MessagingMessageAccess

MessagingMessageAccess - Provides access to message storage.

Since:

Open-Xchange v6.16

Author:

Francisco Laguna, Thorben Betten

Method Summary

void	appendMessages(java.lang.String folder, MessagingMessage[] messages) Appends specified messages to given folder.
java.util.List<java.lang.String>	copyMessages(java.lang.String sourceFolder, java.lang.String destFolder, java.lang.String[] messageIds, boolean fast) Copies specified messages from source folder to destination folder.
void	deleteMessages(java.lang.String folder, java.lang.String[] messageIds, boolean hardDelete) Deletes specified messages in folder.
java.util.List<MessagingMessage>	getAllMessages(java.lang.String folder, IndexRange indexRange, MessagingField sortField, OrderDirection order, MessagingField... fields) A convenience method to get all messages located in given folder.
MessagingPart	getAttachment(java.lang.String folder, java.lang.String messageId, java.lang.String sectionId) Gets the message's attachment identified through given section identifier.
MessagingMessage	getMessage(java.lang.String folder, java.lang.String id, boolean peek) Gets the message associated with specified identifier.
java.util.List<MessagingMessage>	getMessages(java.lang.String folder, java.lang.String[] messageIds, MessagingField[] fields) Gets the messages located in given folder whose identifier matches specified identifier.
java.util.List<java.lang.String>	moveMessages(java.lang.String sourceFolder, java.lang.String destFolder, java.lang.String[] messageIds, boolean fast) Moves specified messages from source folder to destination folder.
MessagingMessage	perform(MessagingMessage message, java.lang.String action) Performs specified action to given message and either returns resulting message or null if no further user interaction is required.
MessagingMessage	perform(java.lang.String action) Performs specified action and either returns resulting message or null if no further user interaction is required.
MessagingMessage	perform(java.lang.String folder, java.lang.String id, java.lang.String action) Performs specified action to the message identified by given arguments and either returns resulting message or null if no further user interaction is required.
MessagingContent	resolveContent(java.lang.String folder, java.lang.String id, java.lang.String referenceId) This method resolves a @see ReferenceContent id.
java.util.List<MessagingMessage>	searchMessages(java.lang.String folder, IndexRange indexRange, MessagingField sortField, OrderDirection order, SearchTerm<?> searchTerm, MessagingField[] fields) Searches for messages located in given folder.
void	updateMessage(MessagingMessage message, MessagingField[] fields) Updates specified fields of given message.

Method Detail

getMessage

MessagingMessage getMessage(java.lang.String folder,
                            java.lang.String id,
                            boolean peek)
                            throws MessagingException

Gets the message associated with specified identifier.

Parameters:

folder - The folder identifier

id - The identifier

peek - true to peek message content (meaning any mechanisms to mark content as read disabled); otherwise false

Returns:

The message associated with specified identifier

Throws:

MessagingException - If message cannot be returned

getMessages

java.util.List<MessagingMessage> getMessages(java.lang.String folder,
                                             java.lang.String[] messageIds,
                                             MessagingField[] fields)
                                             throws MessagingException

Gets the messages located in given folder whose identifier matches specified identifier.

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.

Parameters:

folder - The folder identifier

messageIds - The message identifiers

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

Returns:

The corresponding messages

Throws:

MessagingException - If message could not be returned

searchMessages

java.util.List<MessagingMessage> searchMessages(java.lang.String folder,
                                                IndexRange indexRange,
                                                MessagingField sortField,
                                                OrderDirection order,
                                                SearchTerm<?> searchTerm,
                                                MessagingField[] fields)
                                                throws MessagingException

Searches for messages located in given folder. If the search yields no results, an empty List is returned. This method's purpose is to return filtered messages' information for a fast list view. Therefore this method's fields parameter should only contain instances of MessagingField 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.

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 MessagingMessage

Returns:

The desired, pre-filled instances of MessagingMessage

Throws:

MessagingException - If messages cannot be returned

getAttachment

MessagingPart getAttachment(java.lang.String folder,
                            java.lang.String messageId,
                            java.lang.String sectionId)
                            throws MessagingException

Gets the message's attachment identified through given section identifier.

Parameters:

folder - The folder fullname

messageId - The message identifier

sectionId - The attachment's section identifier

Returns:

The attachment wrapped by a MessagingPart instance

Throws:

MessagingException - If no attachment can be found whose sequence ID matches given section identifier.

updateMessage

void updateMessage(MessagingMessage message,
                   MessagingField[] fields)
                   throws MessagingException

Updates specified fields of given message.

Parameters:

message - The message

fields - The fields to update

Throws:

MessagingException - If update operation fails

appendMessages

void appendMessages(java.lang.String folder,
                    MessagingMessage[] messages)
                    throws MessagingException

Appends specified messages to given folder.

Parameters:

folder - The folder to append to

messages - The messages to append.

Throws:

MessagingException - If appending messages fails

copyMessages

java.util.List<java.lang.String> copyMessages(java.lang.String sourceFolder,
                                              java.lang.String destFolder,
                                              java.lang.String[] messageIds,
                                              boolean fast)
                                              throws MessagingException

Copies specified messages from source folder to destination folder.

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

Parameters:

sourceFolder - The source folder identifier

destFolder - The destination folder identifier

messageIds - The message identifiers

fast - true for fast copy (meaning no identifiers of corresponding messages in destination folder); otherwise false

Returns:

The identifiers of corresponding messages in destination folder. Unless parameter fast is set to true; then null is returned.

Throws:

MessagingException - If copy operation fails

moveMessages

java.util.List<java.lang.String> moveMessages(java.lang.String sourceFolder,
                                              java.lang.String destFolder,
                                              java.lang.String[] messageIds,
                                              boolean fast)
                                              throws MessagingException

Moves specified messages from source folder to destination folder.

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

Parameters:

sourceFolder - The source folder identifier

destFolder - The destination folder identifier

messageIds - The message identifiers

fast - true for fast move (meaning no identifiers of corresponding messages in destination folder); otherwise false

Returns:

The identifiers of corresponding messages in destination folder. Unless parameter fast is set to true; then null is returned.

Throws:

MessagingException - If move operation fails

deleteMessages

void deleteMessages(java.lang.String folder,
                    java.lang.String[] messageIds,
                    boolean hardDelete)
                    throws MessagingException

Deletes specified messages in folder.

Parameters:

folder - The folder to delete in

messageIds - The message identifiers

hardDelete - true to perform a hard-delete; otherwise false to backup in default location

Throws:

MessagingException - If delete operation fails

getAllMessages

java.util.List<MessagingMessage> getAllMessages(java.lang.String folder,
                                                IndexRange indexRange,
                                                MessagingField sortField,
                                                OrderDirection order,
                                                MessagingField... fields)
                                                throws MessagingException

A convenience method to get all messages located in given folder.

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

Parameters:

folder - The folder identifier

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 MessagingMessage

Returns:

The desired, pre-filled instances of MessagingMessage

Throws:

MessagingException - If returning all messages fails

perform

MessagingMessage perform(java.lang.String folder,
                         java.lang.String id,
                         java.lang.String action)
                         throws MessagingException

Performs specified action to the message identified by given arguments and either returns resulting message or null if no further user interaction is required.

Parameters:

folder - The folder identifier

id - The message identifier

action - The action to perform

Returns:

The resulting message or null if requested action yields no resulting message (meaning no further user interaction required)

Throws:

MessagingException - If performing specified action fails or action is not applicable for this perform() method

perform

MessagingMessage perform(java.lang.String action)
                         throws MessagingException

Performs specified action and either returns resulting message or null if no further user interaction is required.

Parameters:

action - The action to perform

Returns:

The resulting message or null if requested action yields no resulting message (meaning no further user interaction required)

Throws:

MessagingException - If performing specified action fails or action is not applicable for this perform() method

perform

MessagingMessage perform(MessagingMessage message,
                         java.lang.String action)
                         throws MessagingException

Performs specified action to given message and either returns resulting message or null if no further user interaction is required.

Parameters:

message - The message to process

action - The action to perform

Returns:

The resulting message or null if requested action yields no resulting message (meaning no further user interaction required)

Throws:

MessagingException - If performing specified action fails or action is not applicable for this perform() method

resolveContent

MessagingContent resolveContent(java.lang.String folder,
                                java.lang.String id,
                                java.lang.String referenceId)
                                throws MessagingException

This method resolves a @see ReferenceContent id.

Parameters:

folder - The folder identifier

id - The message identifier

referenceId - the reference identifier

Returns:

Throws:

MessagingException