com.openexchange.messaging
Interface MessagingFolderAccess

public interface MessagingFolderAccess

MessagingFolderAccess - Provides access to folder storage.

Since:

Open-Xchange v6.16

Author:

Francisco Laguna, Thorben Betten

Method Summary

void	clearFolder(java.lang.String folderId) Deletes the content of the folder identified through given identifier.
void	clearFolder(java.lang.String folderId, boolean hardDelete) Deletes the content of the folder identified through given identifier.
java.lang.String	createFolder(MessagingFolder toCreate) Creates a new messaging folder with attributes taken from given messaging folder description
java.lang.String	deleteFolder(java.lang.String folderId) Deletes an existing messaging folder identified through given identifier.
java.lang.String	deleteFolder(java.lang.String folderId, boolean hardDelete) Deletes an existing messaging folder identified through given identifier.
boolean	exists(java.lang.String folderId) Checks if a folder exists whose identifier matches given identifier
java.lang.String	getConfirmedHamFolder() Gets the identifier of default confirmed ham folder
java.lang.String	getConfirmedSpamFolder() Gets the identifier of default confirmed spam folder
java.lang.String	getDraftsFolder() Gets the identifier of default drafts folder
MessagingFolder	getFolder(java.lang.String folderId) Gets the folder identified through given identifier
Quota	getMessageQuota(java.lang.String folderId) Detects both quota limit and quota usage of MESSAGE resource on given messaging folder's quota-root.
MessagingFolder[]	getPath2DefaultFolder(java.lang.String folderId) Gets the reverse path from the folder identified through given identifier to parental default folder.
Quota[]	getQuotas(java.lang.String folder, Quota.Type[] types) Detects both quotas' limit and usage on given messaging folder's quota-root for specified resource types.
MessagingFolder	getRootFolder() Gets the account's root folder.
java.lang.String	getSentFolder() Gets the identifier of default sent folder
java.lang.String	getSpamFolder() Gets the identifier of default spam folder
Quota	getStorageQuota(java.lang.String folderId) Detects both quota limit and quota usage of STORAGE resource on given messaging folder's quota-root.
MessagingFolder[]	getSubfolders(java.lang.String parentIdentifier, boolean all) Gets the first level subfolders located below the folder whose identifier matches given parameter parentIdentifier.
java.lang.String	getTrashFolder() Gets the identifier of default trash folder
java.lang.String	moveFolder(java.lang.String folderId, java.lang.String newParentId) Moves the folder identified through given identifier to the parent specified through argument newParentId.
java.lang.String	renameFolder(java.lang.String folderId, java.lang.String newName) Renames the folder identified through given identifier to the specified new name.
java.lang.String	updateFolder(java.lang.String identifier, MessagingFolder toUpdate) Updates an existing messaging folder identified through given identifier.

Method Detail

exists

boolean exists(java.lang.String folderId)
               throws MessagingException

Checks if a folder exists whose identifier matches given identifier

Parameters:

folderId - The identifier

Returns:

true if folder exists in account; otherwise false

Throws:

MessagingException - If existence cannot be checked

getFolder

MessagingFolder getFolder(java.lang.String folderId)
                          throws MessagingException

Gets the folder identified through given identifier

Parameters:

folderId - The identifier

Returns:

The corresponding instance of MessagingFolder

Throws:

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

getSubfolders

MessagingFolder[] getSubfolders(java.lang.String parentIdentifier,
                                boolean all)
                                throws MessagingException

Gets the first level subfolders located below the folder whose identifier matches given parameter parentIdentifier.

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

Parameters:

parentIdentifier - The parent identifier

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

Returns:

An array of MessagingFolder representing the subfolders

Throws:

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

getRootFolder

MessagingFolder getRootFolder()
                              throws MessagingException

Gets the account's root folder.

A convenience method for getFolder(String) invoked with MessagingFolder.ROOT_FULLNAME.

Returns:

The account's root folder

Throws:

MessagingException - If account's default folder cannot be delivered

createFolder

java.lang.String createFolder(MessagingFolder toCreate)
                              throws MessagingException

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

Parameters:

toCreate - The messaging folder to create

Returns:

The identifier of the created messaging folder

Throws:

MessagingException - If creation fails

updateFolder

java.lang.String updateFolder(java.lang.String identifier,
                              MessagingFolder toUpdate)
                              throws MessagingException

Updates an existing messaging folder identified through given identifier. All attributes set in given messaging folder instance are applied.

The currently known attributes that make sense being updated are:

• permissions
• subscription

Of course more folder attributes may be checked by implementation to enhance update operations.

Note: If underlying messaging system does not support the corresponding capability, the update is treated as a no-op.

Parameters:

identifier - The identifier of the messaging folder to update

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

Returns:

The identifier of the updated messaging folder

Throws:

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

moveFolder

java.lang.String moveFolder(java.lang.String folderId,
                            java.lang.String newParentId)
                            throws MessagingException

Moves the folder identified through given identifier to the parent specified through argument newParentId.

E.g.:

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

Parameters:

folderId - The folder identifier

newParentId - The identifier of the new parent to move to

Returns:

The new identifier where the folder has been moved

Throws:

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

renameFolder

java.lang.String renameFolder(java.lang.String folderId,
                              java.lang.String newName)
                              throws MessagingException

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

E.g.:

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

Parameters:

folderId - The folder identifier

newName - The new name

Returns:

The new identifier

Throws:

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

deleteFolder

java.lang.String deleteFolder(java.lang.String folderId)
                              throws MessagingException

Deletes an existing messaging folder identified through given identifier.

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

Parameters:

folderId - The identifier of the messaging folder to delete

Returns:

The identifier of the deleted messaging folder

Throws:

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

deleteFolder

java.lang.String deleteFolder(java.lang.String folderId,
                              boolean hardDelete)
                              throws MessagingException

Deletes an existing messaging folder identified through given identifier.

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:

folderId - The identifier of the messaging folder to delete

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

Returns:

The identifier of the deleted messaging folder

Throws:

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

clearFolder

void clearFolder(java.lang.String folderId)
                 throws MessagingException

Deletes the content of the folder identified through given identifier.

Parameters:

folderId - The identifier of the messaging folder whose content should be cleared

Throws:

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

clearFolder

void clearFolder(java.lang.String folderId,
                 boolean hardDelete)
                 throws MessagingException

Deletes the content of the folder identified through given identifier.

Parameters:

folderId - The identifier of the messaging folder whose content should be cleared

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

Throws:

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

getPath2DefaultFolder

MessagingFolder[] getPath2DefaultFolder(java.lang.String folderId)
                                        throws MessagingException

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

Parameters:

folderId - The folder identifier

Returns:

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

Throws:

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

getStorageQuota

Quota getStorageQuota(java.lang.String folderId)
                      throws MessagingException

Detects both quota limit and quota usage of STORAGE resource on given messaging folder's quota-root. If the folder denoted by passed messaging folder's quota-root is the INBOX itself, the whole account'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:

folderId - The folder identifier (if null "INBOX" is used)

Returns:

The quota of STORAGE resource

Throws:

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

getMessageQuota

Quota getMessageQuota(java.lang.String folderId)
                      throws MessagingException

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

Parameters:

folderId - The folder identifier (if null "INBOX" is used)

Returns:

The quota of MESSAGE resource

Throws:

MessagingException - 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 MessagingException

Detects both quotas' limit and usage on given messaging folder's quota-root for specified resource types. If the folder denoted by passed messaging folder's quota-root is the INBOX itself, the whole account'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 identifier (if null "INBOX" is used)

types - The desired quota resource types

Returns:

The quotas for specified resource types

Throws:

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

getConfirmedHamFolder

java.lang.String getConfirmedHamFolder()
                                       throws MessagingException

Gets the identifier of default confirmed ham folder

Returns:

The identifier of default confirmed ham folder or null if not applicable

Throws:

MessagingException - If confirmed ham folder's identifier cannot be returned

getConfirmedSpamFolder

java.lang.String getConfirmedSpamFolder()
                                        throws MessagingException

Gets the identifier of default confirmed spam folder

Returns:

The identifier of default confirmed spam folder or null if not applicable

Throws:

MessagingException - If confirmed spam folder's identifier cannot be returned

getDraftsFolder

java.lang.String getDraftsFolder()
                                 throws MessagingException

Gets the identifier of default drafts folder

Returns:

The identifier of default drafts folder or null if not applicable

Throws:

MessagingException - If draft folder's identifier cannot be returned

getSpamFolder

java.lang.String getSpamFolder()
                               throws MessagingException

Gets the identifier of default spam folder

Returns:

The identifier of default spam folder or null if not applicable

Throws:

MessagingException - If spam folder's identifier cannot be returned

getSentFolder

java.lang.String getSentFolder()
                               throws MessagingException

Gets the identifier of default sent folder

Returns:

The identifier of default sent folder or null if not applicable

Throws:

MessagingException - If sent folder's identifier cannot be returned

getTrashFolder

java.lang.String getTrashFolder()
                                throws MessagingException

Gets the identifier of default trash folder

Returns:

The identifier of default trash folder or null if not applicable

Throws:

MessagingException - If trash folder's identifier cannot be returned