com.openexchange.mail.api
Interface IMailFolderStorage

All Known Subinterfaces:

IMailFolderStorageEnhanced

All Known Implementing Classes:

MailFolderStorage

public interface IMailFolderStorage

IMailFolderStorage - Offers basic access methods to mail folder(s).

Author:

Thorben Betten

Field Summary

static MailFolder[]

EMPTY_PATH The constant to return or represent an empty path.

Method Summary

void	checkDefaultFolders() Checks user's default folder as defined in user's mail settings and creates them if any is missing.
void	clearFolder(java.lang.String fullname) Deletes the content of the folder identified through given fullname.
void	clearFolder(java.lang.String fullname, boolean hardDelete) Deletes the content of the folder identified through given fullname.
java.lang.String	createFolder(MailFolderDescription toCreate) Creates a new mail folder with attributes taken from given mail folder description
java.lang.String	deleteFolder(java.lang.String fullname) Deletes an existing mail folder identified through given fullname.
java.lang.String	deleteFolder(java.lang.String fullname, boolean hardDelete) Deletes an existing mail folder identified through given fullname.
boolean	exists(java.lang.String fullname) Checks if a folder exists whose fullname matches given fullname
java.lang.String	getConfirmedHamFolder() Gets the fullname of default confirmed ham folder
java.lang.String	getConfirmedSpamFolder() Gets the fullname of default confirmed spam folder
java.lang.String	getDraftsFolder() Gets the fullname of default drafts folder
MailFolder	getFolder(java.lang.String fullname) Gets the folder identified through given fullname
Quota	getMessageQuota(java.lang.String folder) Detects both quota limit and quota usage of MESSAGE resource on given mailbox folder's quota-root.
MailFolder[]	getPath2DefaultFolder(java.lang.String fullname) Gets the reverse path from the folder identified through given fullname to parental default folder.
Quota[]	getQuotas(java.lang.String folder, Quota.Type[] types) Detects both quotas' limit and usage on given mailbox folder's quota-root for specified resource types.
MailFolder	getRootFolder() Gets the mailbox's root folder.
java.lang.String	getSentFolder() Gets the fullname of default sent folder
java.lang.String	getSpamFolder() Gets the fullname of default spam folder
Quota	getStorageQuota(java.lang.String folder) Detects both quota limit and quota usage of STORAGE resource on given mailbox folder's quota-root.
MailFolder[]	getSubfolders(java.lang.String parentFullname, boolean all) Gets the first level subfolders located below the folder whose fullname matches given parameter parentFullname.
java.lang.String	getTrashFolder() Gets the fullname of default trash folder
java.lang.String	moveFolder(java.lang.String fullname, java.lang.String newFullname) Moves the folder identified through given fullname to the path specified through argument newFullname.
void	releaseResources() Releases all used resources when closing parental MailAccess
java.lang.String	renameFolder(java.lang.String fullname, java.lang.String newName) Renames the folder identified through given fullname to the specified new name.
java.lang.String	updateFolder(java.lang.String fullname, MailFolderDescription toUpdate) Updates an existing mail folder identified through given fullname.

Field Detail

EMPTY_PATH

static final MailFolder[] EMPTY_PATH

The constant to return or represent an empty path.

Method Detail

exists

boolean exists(java.lang.String fullname)
               throws MailException

Checks if a folder exists whose fullname matches given fullname

Parameters:

fullname - The fullname

Returns:

true if folder exists in mailbox; otherwise false

Throws:

MailException - If existence cannot be checked

getFolder

MailFolder getFolder(java.lang.String fullname)
                     throws MailException

Gets the folder identified through given fullname

Parameters:

fullname - The fullname

Returns:

The corresponding instance of MailFolder

Throws:

MailException - If either folder does not exist or could not be fetched

getSubfolders

MailFolder[] getSubfolders(java.lang.String parentFullname,
                           boolean all)
                           throws MailException

Gets the first level subfolders located below the folder whose fullname matches given parameter parentFullname.

If no subfolders exist below identified folder the constant EMPTY_PATH should be returned.

Parameters:

parentFullname - The parent fullname

all - Whether all or only subscribed subfolders shall be returned. If underlying mailing system does not support folder subscription, this argument should always be treated as true.

Returns:

An array of MailFolder representing the subfolders

Throws:

MailException - If either parent folder does not exist or its subfolders cannot be delivered

getRootFolder

MailFolder getRootFolder()
                         throws MailException

Gets the mailbox's root folder.

Returns:

The mailbox's root folder

Throws:

MailException - If mailbox's default folder cannot be delivered

checkDefaultFolders

void checkDefaultFolders()
                         throws MailException

Checks user's default folder as defined in user's mail settings and creates them if any is missing.

See also createConfirmedSpam(), createConfirmedHam(), and unsubscribeSpamFolders().

Throws:

MailException - If user's default folder could not be checked

createFolder

java.lang.String createFolder(MailFolderDescription toCreate)
                              throws MailException

Creates a new mail folder with attributes taken from given mail folder description

Parameters:

toCreate - The mail folder to create

Returns:

The fullname of the created mail folder

Throws:

MailException - If creation fails

updateFolder

java.lang.String updateFolder(java.lang.String fullname,
                              MailFolderDescription toUpdate)
                              throws MailException

Updates an existing mail folder identified through given fullname. All attributes set in given mail folder description are applied.

The currently known attributes that make sense being updated are:

• permissions; meaning folder's permissions are updated if MailFolderDescription.containsPermissions() returns true
• subscription; meaning a subscribe/unsubscribe operation is performed if MailFolderDescription.containsSubscribed() returns true

Of course more folder attributes may be checked by implementation to enhance update operations. The programmer may extend the MailFolderDescription class to do so.

Note: If underlying mailing system does not support the corresponding capability, the update is treated as a no-op. For example if both MailCapabilities.hasPermissions() and MailCapabilities.hasSubscription() indicate false, the associated update operations are not going to be performed.

Parameters:

fullname - The fullname of the mail folder to update

toUpdate - The mail folder to update containing only the modified fields

Returns:

The fullname of the updated mail folder

Throws:

MailException - If either folder does not exist or cannot be updated

moveFolder

java.lang.String moveFolder(java.lang.String fullname,
                            java.lang.String newFullname)
                            throws MailException

Moves the folder identified through given fullname to the path specified through argument newFullname. Thus a rename can be implicitly performed.

E.g.:

 my.path.to.folder -> my.newpath.to.folder
 

Parameters:

fullname - The folder fullname

newFullname - The new fullname to move to

Returns:

The new fullname where the folder has been moved

Throws:

MailException - If either folder does not exist or cannot be moved

renameFolder

java.lang.String renameFolder(java.lang.String fullname,
                              java.lang.String newName)
                              throws MailException

Renames the folder identified through given fullname to the specified new name.

E.g.:

 my.path.to.folder -> my.path.to.newfolder
 

Parameters:

fullname - The folder fullname

newName - The new name

Returns:

The new fullname

Throws:

MailException - If either folder does not exist or cannot be renamed

deleteFolder

java.lang.String deleteFolder(java.lang.String fullname)
                              throws MailException

Deletes an existing mail folder identified through given fullname.

This is a convenience method that invokes deleteFolder(String, boolean) with hardDelete set to false.

Parameters:

fullname - The fullname of the mail folder to delete

Returns:

The fullname of the deleted mail folder

Throws:

MailException - If either folder does not exist or cannot be deleted

deleteFolder

java.lang.String deleteFolder(java.lang.String fullname,
                              boolean hardDelete)
                              throws MailException

Deletes an existing mail folder identified through given fullname.

If hardDelete is not set and folder is not located below default trash folder it is backed up (including subfolder tree) in default trash folder; otherwise it is deleted permanently.

While another backup folder with the same name already exists below default trash folder, an increasing serial number is appended to folder name until its name is unique inside default trash folder's subfolders. E.g.: If folder "DeleteMe" already exists below default trash folder, the next name would be "DeleteMe2". If again a folder "DeleteMe2" already exists below default trash folder, the next name would be "DeleteMe3", and so no.

If default trash folder cannot hold subfolders, the folder is either deleted permanently or an appropriate exception may be thrown.

Parameters:

fullname - The fullname of the mail folder to delete

hardDelete - Whether to delete permanently or to backup into trash folder

Returns:

The fullname of the deleted mail folder

Throws:

MailException - If either folder does not exist or cannot be deleted

clearFolder

void clearFolder(java.lang.String fullname)
                 throws MailException

Deletes the content of the folder identified through given fullname.

Parameters:

fullname - The fullname of the mail folder whose content should be cleared

Throws:

MailException - If either folder does not exist or its content cannot be cleared

clearFolder

void clearFolder(java.lang.String fullname,
                 boolean hardDelete)
                 throws MailException

Deletes the content of the folder identified through given fullname.

Parameters:

fullname - The fullname of the mail folder whose content should be cleared

hardDelete - Whether to delete permanently or to backup into trash folder

Throws:

MailException - If either folder does not exist or its content cannot be cleared

getPath2DefaultFolder

MailFolder[] getPath2DefaultFolder(java.lang.String fullname)
                                   throws MailException

Gets the reverse path from the folder identified through given fullname to parental default folder. All occurring folders on that path are contained in reverse order in returned array of MailFolder instances.

Parameters:

fullname - The folder fullname

Returns:

All occurring folders in reverse order as an array of MailFolder instances.

Throws:

MailException - If either folder does not exist or path cannot be determined

getStorageQuota

Quota getStorageQuota(java.lang.String folder)
                      throws MailException

Detects both quota limit and quota usage of STORAGE resource on given mailbox folder's quota-root. If the folder denoted by passed mailbox folder's quota-root is the INBOX itself, the whole mailbox's STORAGE quota is going to be returned; meaning the sum of all available (limit) and allocated (usage) storage size.

Note that the Quota.getLimit() and Quota.getUsage() is in 1024 octets.

Parameters:

folder - The folder fullname (if null "INBOX" is used)

Returns:

The quota of STORAGE resource

Throws:

MailException - If either folder does not exist or quota limit and/or quote usage cannot be determined

getMessageQuota

Quota getMessageQuota(java.lang.String folder)
                      throws MailException

Detects both quota limit and quota usage of MESSAGE resource on given mailbox folder's quota-root. If the folder denoted by passed mailbox folder's quota-root is the INBOX itself, the whole mailbox's MESSAGE quota is going to be returned; meaning the sum of all available (limit) and allocated (usage) message amount.

Parameters:

folder - The folder fullname (if null "INBOX" is used)

Returns:

The quota of MESSAGE resource

Throws:

MailException - If either folder does not exist or quota limit and/or quote usage cannot be determined

getQuotas

Quota[] getQuotas(java.lang.String folder,
                  Quota.Type[] types)
                  throws MailException

Detects both quotas' limit and usage on given mailbox folder's quota-root for specified resource types. If the folder denoted by passed mailbox folder's quota-root is the INBOX itself, the whole mailbox's quota is going to be returned; meaning the sum of all available (limit) and allocated (usage) resources.

If no quota restriction exists for a certain resource type, both quota usage and limit value carry constant Quota.UNLIMITED to indicate no limitations on that resource type.

Note that the Quota.getLimit() and Quota.getUsage() returned for Quota.Type#STORAGE quota is in 1024 octets.

Parameters:

folder - The folder fullname (if null "INBOX" is used)

types - The desired quota resource types

Returns:

The quotas for specified resource types

Throws:

MailException - If either folder does not exist or quota limit and/or quote usage cannot be determined

getConfirmedHamFolder

java.lang.String getConfirmedHamFolder()
                                       throws MailException

Gets the fullname of default confirmed ham folder

Returns:

The fullname of default confirmed ham folder

Throws:

MailException - If confirmed ham folder's fullname cannot be returned

getConfirmedSpamFolder

java.lang.String getConfirmedSpamFolder()
                                        throws MailException

Gets the fullname of default confirmed spam folder

Returns:

The fullname of default confirmed spam folder

Throws:

MailException - If confirmed spam folder's fullname cannot be returned

getDraftsFolder

java.lang.String getDraftsFolder()
                                 throws MailException

Gets the fullname of default drafts folder

Returns:

The fullname of default drafts folder

Throws:

MailException - If draft folder's fullname cannot be returned

getSpamFolder

java.lang.String getSpamFolder()
                               throws MailException

Gets the fullname of default spam folder

Returns:

The fullname of default spam folder

Throws:

MailException - If spam folder's fullname cannot be returned

getSentFolder

java.lang.String getSentFolder()
                               throws MailException

Gets the fullname of default sent folder

Returns:

The fullname of default sent folder

Throws:

MailException - If sent folder's fullname cannot be returned

getTrashFolder

java.lang.String getTrashFolder()
                                throws MailException

Gets the fullname of default trash folder

Returns:

The fullname of default trash folder

Throws:

MailException - If trash folder's fullname cannot be returned

releaseResources

void releaseResources()
                      throws MailException

Releases all used resources when closing parental MailAccess

Throws:

MailException - If resources cannot be released