org.apache.james.mailbox
Interface MailboxManager

All Superinterfaces:

RequestAware

public interface MailboxManager
extends RequestAware

Central MailboxManager which creates, lists, provides, renames and deletes Mailboxes

An important goal is to be JavaMail feature compatible. That means JavaMail could be used in both directions: As a backend for e.g. accessing a Maildir JavaMail store or as a frontend to access a JDBC MailboxManager through JavaMail. This should be possible by not too complicated wrapper classes. Due to the complexity of JavaMail it might be impossible to avoid some limitations.

Internally MailboxManager deals with named repositories that could have different implementations. E.g. JDBC connections to different hosts or Maildir / Mbox like stores. These repositories are identified by their names and maybe are configured in config.xml. The names of the mailboxes have to be mapped to the corresponding repository name. For user mailboxes this could be done by a "User.getRepositoryName()" property. It is imaginable that repositories lookup further properties from the user object like a path name for a file based storage method. Until Milestone 6 there is only one named repository: "default".

The only operation that requires dealing with the named repositories directly is the quota management. It is probably really difficult to implement a quota system that spans multiple repository implementations. That is why quotas are created for a specific repository. To be able to administer, repositories and theier belonging mailboxes can be listet.

Method Summary

void	addListener(MailboxPath mailboxPath, MailboxListener listener, MailboxSession session) Implementations of Mailbox may interpret the fact that someone is listening and do some caching and even postpone persistence until everyone has removed itself.
void	copyMessages(MessageRange set, MailboxPath from, MailboxPath to, MailboxSession session) this is done by the MailboxRepository because maybe this operation could be optimized in the corresponding store.
void	createMailbox(MailboxPath mailboxPath, MailboxSession mailboxSession) Creates a new mailbox.
MailboxSession	createSystemSession(java.lang.String userName, org.apache.commons.logging.Log log) Creates a new system session.
void	deleteMailbox(MailboxPath mailboxPath, MailboxSession session) Delete the mailbox with the name
char	getDelimiter() Return the delimter to use for folders
MessageManager	getMailbox(MailboxPath mailboxPath, MailboxSession session) Gets an session suitable for IMAP.
MailboxSession	login(java.lang.String userid, java.lang.String passwd, org.apache.commons.logging.Log log) Autenticates the given user against the given password.
void	logout(MailboxSession session, boolean force) Logs the session out, freeing any resources.
boolean	mailboxExists(MailboxPath mailboxPath, MailboxSession session) Does the given mailbox exist?
void	renameMailbox(MailboxPath from, MailboxPath to, MailboxSession session) Renames a mailbox.
java.util.List<MailboxMetaData>	search(MailboxQuery expression, MailboxSession session) Searches for mailboxes matching the given query.

Methods inherited from interface org.apache.james.mailbox.RequestAware

endProcessingRequest, startProcessingRequest

Method Detail

getDelimiter

char getDelimiter()

Return the delimter to use for folders

Returns:

delimiter

getMailbox

MessageManager getMailbox(MailboxPath mailboxPath,
                          MailboxSession session)
                          throws MailboxException

Gets an session suitable for IMAP.

Parameters:

mailboxPath - the Path of the mailbox, not null

session - the context for this call, not null

Returns:

ImapMailboxSession, not null

Throws:

MailboxException - when the mailbox cannot be opened

MailboxNotFoundException - when the given mailbox does not exist

createMailbox

void createMailbox(MailboxPath mailboxPath,
                   MailboxSession mailboxSession)
                   throws MailboxException

Creates a new mailbox. Any intermediary mailboxes missing from the hierarchy should be created.

Parameters:

mailboxPath -

mailboxSession - the context for this call, not null

Throws:

MailboxException - when creation fails

deleteMailbox

void deleteMailbox(MailboxPath mailboxPath,
                   MailboxSession session)
                   throws MailboxException

Delete the mailbox with the name

Parameters:

mailboxPath -

session -

Throws:

MailboxException

renameMailbox

void renameMailbox(MailboxPath from,
                   MailboxPath to,
                   MailboxSession session)
                   throws MailboxException

Renames a mailbox.

Parameters:

from - original mailbox

to - new mailbox

session - the context for this call, not nul

Throws:

MailboxException - otherwise

MailboxExistsException - when the to mailbox exists

MailboxNotFound - when the from mailbox does not exist

copyMessages

void copyMessages(MessageRange set,
                  MailboxPath from,
                  MailboxPath to,
                  MailboxSession session)
                  throws MailboxException

this is done by the MailboxRepository because maybe this operation could be optimized in the corresponding store.

Parameters:

set - messages to copy

from - name of the source mailbox

to - name of the destination mailbox

session - MailboxSession, not null

Throws:

MailboxException

search

java.util.List<MailboxMetaData> search(MailboxQuery expression,
                                       MailboxSession session)
                                       throws MailboxException

Searches for mailboxes matching the given query.

Parameters:

expression - not null

session - the context for this call, not null

Throws:

MailboxException

mailboxExists

boolean mailboxExists(MailboxPath mailboxPath,
                      MailboxSession session)
                      throws MailboxException

Does the given mailbox exist?

Parameters:

mailboxName - not null

session - the context for this call, not null

Returns:

true when the mailbox exists and is accessible for the given user, false otherwise

Throws:

MailboxException

createSystemSession

MailboxSession createSystemSession(java.lang.String userName,
                                   org.apache.commons.logging.Log log)
                                   throws BadCredentialsException,
                                          MailboxException

Creates a new system session. A system session is intended to be used for programmatic access. Use login(String, String, Log) when accessing this API from a protocol.

Parameters:

userName - the name of the user whose session is being created

log - context sensitive log

Returns:

MailboxSession, not null

Throws:

BadCredentialsException - when system access is not allowed for the given user

MailboxException - when the creation fails for other reasons

login

MailboxSession login(java.lang.String userid,
                     java.lang.String passwd,
                     org.apache.commons.logging.Log log)
                     throws BadCredentialsException,
                            MailboxException

Autenticates the given user against the given password. When authentic and authorized, a session will be supplied

Parameters:

userid - user name

passwd - password supplied

log - context sensitive log

Returns:

a MailboxSession when the user is authentic and authorized to access

Throws:

BadCredentialsException - when system access is denighed for the given user

MailboxException - when the creation fails for other reasons

logout

void logout(MailboxSession session,
            boolean force)
            throws MailboxException

Logs the session out, freeing any resources. Clients who open session should make best efforts to call this when the session is closed.

Note that clients may not always be able to call logout (whether forced or not). Mailboxes that create sessions which are expensive to maintain MUST retain a reference and periodically check MailboxSession.isOpen().

Note that implementations much be aware that it is possible that this method may be called more than once with the same session.

Parameters:

session - not null

force - true when the session logout is forced by premature connection termination

Throws:

MailboxException - when logout fails

addListener

void addListener(MailboxPath mailboxPath,
                 MailboxListener listener,
                 MailboxSession session)
                 throws MailboxException

Implementations of Mailbox may interpret the fact that someone is listening and do some caching and even postpone persistence until everyone has removed itself.

Listeners should return true from MailboxListener.isClosed() when they are ready to be removed.

Parameters:

mailboxPath - not null

listener - not null

session - not null

Throws:

MailboxException