com.openexchange.mail.api
Class MailFolderStorage

java.lang.Object
  com.openexchange.mail.api.MailFolderStorage

All Implemented Interfaces:

IMailFolderStorage

public abstract class MailFolderStorage
extends java.lang.Object
implements IMailFolderStorage

MailFolderStorage - Abstract implementation of IMailFolderStorage.

Author:

Thorben Betten

Field Summary

Fields inherited from interface com.openexchange.mail.api.IMailFolderStorage

EMPTY_PATH

Constructor Summary

MailFolderStorage()

Method Summary

abstract 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.
abstract void	clearFolder(java.lang.String fullname, boolean hardDelete) Deletes the content of the folder identified through given fullname.
abstract 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.
abstract java.lang.String	deleteFolder(java.lang.String fullname, boolean hardDelete) Deletes an existing mail folder identified through given fullname.
abstract boolean	exists(java.lang.String fullname) Checks if a folder exists whose fullname matches given fullname
abstract java.lang.String	getConfirmedHamFolder() Gets the fullname of default confirmed ham folder
abstract java.lang.String	getConfirmedSpamFolder() Gets the fullname of default confirmed spam folder
abstract java.lang.String	getDraftsFolder() Gets the fullname of default drafts folder
abstract 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.
abstract 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.
abstract java.lang.String	getSentFolder() Gets the fullname of default sent folder
abstract 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.
abstract MailFolder[]	getSubfolders(java.lang.String parentFullname, boolean all) Gets the first level subfolders located below the folder whose fullname matches given parameter parentFullname.
abstract java.lang.String	getTrashFolder() Gets the fullname of default trash folder
abstract 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.
abstract 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.
abstract java.lang.String	updateFolder(java.lang.String fullname, MailFolderDescription toUpdate) Updates an existing mail folder identified through given fullname.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

MailFolderStorage

public MailFolderStorage()

Method Detail

exists

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

Description copied from interface: IMailFolderStorage

Checks if a folder exists whose fullname matches given fullname

Specified by:

exists in interface IMailFolderStorage

Parameters:

fullname - The fullname

Returns:

true if folder exists in mailbox; otherwise false

Throws:

MailException - If existence cannot be checked

getFolder

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

Description copied from interface: IMailFolderStorage

Gets the folder identified through given fullname

Specified by:

getFolder in interface IMailFolderStorage

Parameters:

fullname - The fullname

Returns:

The corresponding instance of MailFolder

Throws:

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

getSubfolders

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

Description copied from interface: IMailFolderStorage

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

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

Specified by:

getSubfolders in interface IMailFolderStorage

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

public MailFolder getRootFolder()
                         throws MailException

Gets the mailbox's root folder.

This is a convenience method that invokes getFolder(String) with its parameter set to MailFolder.DEFAULT_FOLDER_ID. It may be overridden if a faster way can be achieved by specific implementation.

Specified by:

getRootFolder in interface IMailFolderStorage

Returns:

The mailbox's root folder

Throws:

MailException - If mailbox's default folder cannot be delivered

checkDefaultFolders

public abstract void checkDefaultFolders()
                                  throws MailException

Description copied from interface: IMailFolderStorage

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().

Specified by:

checkDefaultFolders in interface IMailFolderStorage

Throws:

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

createFolder

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

Description copied from interface: IMailFolderStorage

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

Specified by:

createFolder in interface IMailFolderStorage

Parameters:

toCreate - The mail folder to create

Returns:

The fullname of the created mail folder

Throws:

MailException - If creation fails

updateFolder

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

Description copied from interface: IMailFolderStorage

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.

Specified by:

updateFolder in interface IMailFolderStorage

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

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

Description copied from interface: IMailFolderStorage

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
 

Specified by:

moveFolder in interface IMailFolderStorage

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

public 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.

Since a rename is a move operation in the same (parent) folder, this is only a convenience method that may be overridden if necessary.

E.g.:

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

Specified by:

renameFolder in interface IMailFolderStorage

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

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

Description copied from interface: IMailFolderStorage

Deletes an existing mail folder identified through given fullname.

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

Specified by:

deleteFolder in interface IMailFolderStorage

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

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

Description copied from interface: IMailFolderStorage

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.

Specified by:

deleteFolder in interface IMailFolderStorage

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

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

Description copied from interface: IMailFolderStorage

Deletes the content of the folder identified through given fullname.

Specified by:

clearFolder in interface IMailFolderStorage

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

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

Description copied from interface: IMailFolderStorage

Deletes the content of the folder identified through given fullname.

Specified by:

clearFolder in interface IMailFolderStorage

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

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

Description copied from interface: IMailFolderStorage

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.

Specified by:

getPath2DefaultFolder in interface IMailFolderStorage

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

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

Description copied from interface: IMailFolderStorage

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.

Specified by:

getStorageQuota in interface IMailFolderStorage

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

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

Description copied from interface: IMailFolderStorage

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.

Specified by:

getMessageQuota in interface IMailFolderStorage

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

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

Description copied from interface: IMailFolderStorage

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.

Specified by:

getQuotas in interface IMailFolderStorage

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

public abstract java.lang.String getConfirmedHamFolder()
                                                throws MailException

Description copied from interface: IMailFolderStorage

Gets the fullname of default confirmed ham folder

Specified by:

getConfirmedHamFolder in interface IMailFolderStorage

Returns:

The fullname of default confirmed ham folder

Throws:

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

getConfirmedSpamFolder

public abstract java.lang.String getConfirmedSpamFolder()
                                                 throws MailException

Description copied from interface: IMailFolderStorage

Gets the fullname of default confirmed spam folder

Specified by:

getConfirmedSpamFolder in interface IMailFolderStorage

Returns:

The fullname of default confirmed spam folder

Throws:

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

getDraftsFolder

public abstract java.lang.String getDraftsFolder()
                                          throws MailException

Description copied from interface: IMailFolderStorage

Gets the fullname of default drafts folder

Specified by:

getDraftsFolder in interface IMailFolderStorage

Returns:

The fullname of default drafts folder

Throws:

MailException - If draft folder's fullname cannot be returned

getSpamFolder

public abstract java.lang.String getSpamFolder()
                                        throws MailException

Description copied from interface: IMailFolderStorage

Gets the fullname of default spam folder

Specified by:

getSpamFolder in interface IMailFolderStorage

Returns:

The fullname of default spam folder

Throws:

MailException - If spam folder's fullname cannot be returned

getSentFolder

public abstract java.lang.String getSentFolder()
                                        throws MailException

Description copied from interface: IMailFolderStorage

Gets the fullname of default sent folder

Specified by:

getSentFolder in interface IMailFolderStorage

Returns:

The fullname of default sent folder

Throws:

MailException - If sent folder's fullname cannot be returned

getTrashFolder

public abstract java.lang.String getTrashFolder()
                                         throws MailException

Description copied from interface: IMailFolderStorage

Gets the fullname of default trash folder

Specified by:

getTrashFolder in interface IMailFolderStorage

Returns:

The fullname of default trash folder

Throws:

MailException - If trash folder's fullname cannot be returned

releaseResources

public abstract void releaseResources()
                               throws MailException

Description copied from interface: IMailFolderStorage

Releases all used resources when closing parental MailAccess

Specified by:

releaseResources in interface IMailFolderStorage

Throws:

MailException - If resources cannot be released