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

Constructors

Constructor and Description
MailFolderStorage()

Method Summary

Methods

Modifier and Type	Method and Description
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 full name.
abstract void	clearFolder(java.lang.String fullName, boolean hardDelete) Deletes the content of the folder identified through given full name.
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 full name.
abstract java.lang.String	deleteFolder(java.lang.String fullName, boolean hardDelete) Deletes an existing mail folder identified through given full name.
abstract boolean	exists(java.lang.String fullName) Checks if a folder exists whose full name matches given fullName
abstract java.lang.String	getConfirmedHamFolder() Gets the full name of default confirmed ham folder
abstract java.lang.String	getConfirmedSpamFolder() Gets the full name of default confirmed spam folder
java.lang.String	getDefaultFolderPrefix() Gets the prefix (incl. separator character) for default folders.
abstract java.lang.String	getDraftsFolder() Gets the full name of default drafts folder
abstract MailFolder	getFolder(java.lang.String fullName) Gets the folder identified through given full name
Quota	getMessageQuota(java.lang.String fullName) 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 full name to parental default folder.
abstract Quota[]	getQuotas(java.lang.String fullName, 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 full name of default sent folder
abstract java.lang.String	getSpamFolder() Gets the full name of default spam folder
Quota	getStorageQuota(java.lang.String fullName) 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 full name of default trash folder
abstract java.lang.String	moveFolder(java.lang.String fullName, java.lang.String newFullName) Moves the folder identified through given full name 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 full name to the specified new name.
abstract java.lang.String	updateFolder(java.lang.String fullName, MailFolderDescription toUpdate) Updates an existing mail folder identified through given full name.

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 com.openexchange.exception.OXException

Description copied from interface: IMailFolderStorage

Checks if a folder exists whose full name matches given fullName

Specified by:

exists in interface IMailFolderStorage

Parameters:

fullName - The full name

Returns:

true if folder exists in mailbox; otherwise false

Throws:

com.openexchange.exception.OXException - If existence cannot be checked

getFolder

public abstract MailFolder getFolder(java.lang.String fullName)
                              throws com.openexchange.exception.OXException

Description copied from interface: IMailFolderStorage

Gets the folder identified through given full name

Specified by:

getFolder in interface IMailFolderStorage

Parameters:

fullName - The full name

Returns:

The corresponding instance of MailFolder

Throws:

com.openexchange.exception.OXException - If either folder does not exist or could not be fetched

getSubfolders

public abstract MailFolder[] getSubfolders(java.lang.String parentFullName,
                         boolean all)
                                    throws com.openexchange.exception.OXException

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 full name

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:

com.openexchange.exception.OXException - If either parent folder does not exist or its subfolders cannot be delivered

getRootFolder

public MailFolder getRootFolder()
                         throws com.openexchange.exception.OXException

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:

com.openexchange.exception.OXException - If mailbox's default folder cannot be delivered

checkDefaultFolders

public abstract void checkDefaultFolders()
                                  throws com.openexchange.exception.OXException

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:

com.openexchange.exception.OXException - If user's default folder could not be checked

createFolder

public abstract java.lang.String createFolder(MailFolderDescription toCreate)
                                       throws com.openexchange.exception.OXException

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:

com.openexchange.exception.OXException - If creation fails

updateFolder

public abstract java.lang.String updateFolder(java.lang.String fullName,
                            MailFolderDescription toUpdate)
                                       throws com.openexchange.exception.OXException

Description copied from interface: IMailFolderStorage

Updates an existing mail folder identified through given full name. 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 full name 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:

com.openexchange.exception.OXException - 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 com.openexchange.exception.OXException

Description copied from interface: IMailFolderStorage

Moves the folder identified through given full name 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 full name

newFullName - The new full name to move to

Returns:

The new fullName where the folder has been moved

Throws:

com.openexchange.exception.OXException - 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 com.openexchange.exception.OXException

Renames the folder identified through given full name 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 full name

newName - The new name

Returns:

The new full name

Throws:

com.openexchange.exception.OXException - If either folder does not exist or cannot be renamed

deleteFolder

public java.lang.String deleteFolder(java.lang.String fullName)
                              throws com.openexchange.exception.OXException

Description copied from interface: IMailFolderStorage

Deletes an existing mail folder identified through given full name.

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 full name of the mail folder to delete

Returns:

The fullName of the deleted mail folder

Throws:

com.openexchange.exception.OXException - If either folder does not exist or cannot be deleted

deleteFolder

public abstract java.lang.String deleteFolder(java.lang.String fullName,
                            boolean hardDelete)
                                       throws com.openexchange.exception.OXException

Description copied from interface: IMailFolderStorage

Deletes an existing mail folder identified through given full name.

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 full name 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:

com.openexchange.exception.OXException - If either folder does not exist or cannot be deleted

clearFolder

public void clearFolder(java.lang.String fullName)
                 throws com.openexchange.exception.OXException

Description copied from interface: IMailFolderStorage

Deletes the content of the folder identified through given full name.

Specified by:

clearFolder in interface IMailFolderStorage

Parameters:

fullName - The full name of the mail folder whose content should be cleared

Throws:

com.openexchange.exception.OXException - If either folder does not exist or its content cannot be cleared

clearFolder

public abstract void clearFolder(java.lang.String fullName,
               boolean hardDelete)
                          throws com.openexchange.exception.OXException

Description copied from interface: IMailFolderStorage

Deletes the content of the folder identified through given full name.

Specified by:

clearFolder in interface IMailFolderStorage

Parameters:

fullName - The full name of the mail folder whose content should be cleared

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

Throws:

com.openexchange.exception.OXException - If either folder does not exist or its content cannot be cleared

getPath2DefaultFolder

public MailFolder[] getPath2DefaultFolder(java.lang.String fullName)
                                   throws com.openexchange.exception.OXException

Description copied from interface: IMailFolderStorage

Gets the reverse path from the folder identified through given full name 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 full name

Returns:

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

Throws:

com.openexchange.exception.OXException - If either folder does not exist or path cannot be determined

getStorageQuota

public Quota getStorageQuota(java.lang.String fullName)
                      throws com.openexchange.exception.OXException

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:

fullName - The folder full name (if null "INBOX" is used)

Returns:

The quota of STORAGE resource

Throws:

com.openexchange.exception.OXException - If either folder does not exist or quota limit and/or quote usage cannot be determined

getMessageQuota

public Quota getMessageQuota(java.lang.String fullName)
                      throws com.openexchange.exception.OXException

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:

fullName - The folder full name (if null "INBOX" is used)

Returns:

The quota of MESSAGE resource

Throws:

com.openexchange.exception.OXException - If either folder does not exist or quota limit and/or quote usage cannot be determined

getQuotas

public abstract Quota[] getQuotas(java.lang.String fullName,
                Quota.Type[] types)
                           throws com.openexchange.exception.OXException

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:

fullName - The folder full name (if null "INBOX" is used)

types - The desired quota resource types

Returns:

The quotas for specified resource types

Throws:

com.openexchange.exception.OXException - If either folder does not exist or quota limit and/or quote usage cannot be determined

getDefaultFolderPrefix

public java.lang.String getDefaultFolderPrefix()
                                        throws com.openexchange.exception.OXException

Gets the prefix (incl. separator character) for default folders.

By now a compound full name is assumed. Override if not appropriate.

Specified by:

getDefaultFolderPrefix in interface IMailFolderStorage

Returns:

The prefix

Throws:

com.openexchange.exception.OXException - If a mail error occurs

getConfirmedHamFolder

public abstract java.lang.String getConfirmedHamFolder()
                                                throws com.openexchange.exception.OXException

Description copied from interface: IMailFolderStorage

Gets the full name of default confirmed ham folder

Specified by:

getConfirmedHamFolder in interface IMailFolderStorage

Returns:

The full name of default confirmed ham folder

Throws:

com.openexchange.exception.OXException - If confirmed ham folder's full name cannot be returned

getConfirmedSpamFolder

public abstract java.lang.String getConfirmedSpamFolder()
                                                 throws com.openexchange.exception.OXException

Description copied from interface: IMailFolderStorage

Gets the full name of default confirmed spam folder

Specified by:

getConfirmedSpamFolder in interface IMailFolderStorage

Returns:

The full name of default confirmed spam folder

Throws:

com.openexchange.exception.OXException - If confirmed spam folder's full name cannot be returned

getDraftsFolder

public abstract java.lang.String getDraftsFolder()
                                          throws com.openexchange.exception.OXException

Description copied from interface: IMailFolderStorage

Gets the full name of default drafts folder

Specified by:

getDraftsFolder in interface IMailFolderStorage

Returns:

The full name of default drafts folder

Throws:

com.openexchange.exception.OXException - If draft folder's full name cannot be returned

getSpamFolder

public abstract java.lang.String getSpamFolder()
                                        throws com.openexchange.exception.OXException

Description copied from interface: IMailFolderStorage

Gets the full name of default spam folder

Specified by:

getSpamFolder in interface IMailFolderStorage

Returns:

The full name of default spam folder

Throws:

com.openexchange.exception.OXException - If spam folder's full name cannot be returned

getSentFolder

public abstract java.lang.String getSentFolder()
                                        throws com.openexchange.exception.OXException

Description copied from interface: IMailFolderStorage

Gets the full name of default sent folder

Specified by:

getSentFolder in interface IMailFolderStorage

Returns:

The full name of default sent folder

Throws:

com.openexchange.exception.OXException - If sent folder's full name cannot be returned

getTrashFolder

public abstract java.lang.String getTrashFolder()
                                         throws com.openexchange.exception.OXException

Description copied from interface: IMailFolderStorage

Gets the full name of default trash folder

Specified by:

getTrashFolder in interface IMailFolderStorage

Returns:

The full name of default trash folder

Throws:

com.openexchange.exception.OXException - If trash folder's full name cannot be returned

releaseResources

public abstract void releaseResources()
                               throws com.openexchange.exception.OXException

Description copied from interface: IMailFolderStorage

Releases all used resources when closing parental MailAccess

Specified by:

releaseResources in interface IMailFolderStorage

Throws:

com.openexchange.exception.OXException - If resources cannot be released