org.apache.james.imapserver
Interface Mailbox

All Superinterfaces:
org.apache.avalon.framework.component.Composable, org.apache.avalon.framework.configuration.Configurable
All Known Subinterfaces:
ACLMailbox

public interface Mailbox
extends org.apache.avalon.framework.configuration.Configurable, org.apache.avalon.framework.component.Composable

Interface for objects representing an IMAP4rev1 mailbox (folder). Contains logical information and provides a simple API. There should be one instance of this class for every open IMAP mailbox. Implementations may choose to store this object or recreate it on access. Storing is recommended.

Several methods throw AccessControlException. In normal use, these shouldn't get thrown because the Host will have checked access before returning a reference to this mailbox. However, having the methods here throw this exception allows the acl to be changed while a mailbox is selected. Mailbox Related Flags (rfc2060 name attributes) \Noinferiors It is not possible for any child levels of hierarchy to exist under this name; no child levels exist now and none can be created in the future. \Noselect It is not possible to use this name as a selectable mailbox. \Marked The mailbox has been marked "interesting" by the server; the mailbox probably contains messages that have been added since the last time the mailbox was selected. \Unmarked The mailbox does not contain any additional messages since the last time the mailbox was selected. Message related flags. The flags allowed per message are specific to each mailbox. The minimum list (rfc2060 system flags) is: \Seen Message has been read \Answered Message has been answered \Flagged Message is "flagged" for urgent/special attention \Deleted Message is "deleted" for removal by later EXPUNGE \Draft Message has not completed composition (marked as a draft). \Recent Message is "recently" arrived in this mailbox. This session is the first session to have been notified about this message; subsequent sessions will not see \Recent set for this message. This flag can not be altered by the client. If it is not possible to determine whether or not this session is the first session to be notified about a message, then that message SHOULD be considered recent. Reference: RFC 2060

Version:
0.1 on 14 Dec 2000
Author:
Charles Benett

Field Summary
static java.lang.String RECENT_FLAG
           
static java.lang.String SYSTEM_FLAGS
           
 
Method Summary
 void addMailboxEventListener(MailboxEventListener mel)
          Mailbox Events are used to inform registered listeners of events in the Mailbox.
 boolean allFlags(java.lang.String username)
          Indicates if specified user can change any flag on a permanent basis, except for \Recent which can never be changed by a user.
 boolean checkpoint()
          Returns true once this Mailbox has been checkpointed.
 boolean expunge(java.lang.String user)
          Removes all messages marked Deleted.
 java.lang.String getAbsoluteName()
          Returns absolute, that is user-independent, hierarchical name of mailbox (including namespace) Example: '#mail.fred.flintstone.apache.James.NewIdeas'
 int getExists()
          Indicates number of messages in folder
 java.lang.String getFlags(int msn, java.lang.String user)
          Get the IMAP-formatted String of flags for specified message.
 java.lang.String getFlagsUID(int uid, java.lang.String user)
          Get the IMAP-formatted String of flags for specified message.
 boolean getInferiorsAllowed()
          Indicates if child folders may be created.
 javax.mail.internet.InternetHeaders getInternetHeaders(int msn, java.lang.String user)
          Returns the Internet Headers for a message.
 javax.mail.internet.InternetHeaders getInternetHeadersUID(int uid, java.lang.String user)
          Returns the Internet Headers for a message.
 int getMailboxSize()
          Returns mailbox size in octets.
 MessageAttributes getMessageAttributes(int msn, java.lang.String user)
          Returns the message attributes for a message.
 MessageAttributes getMessageAttributesUID(int uid, java.lang.String user)
          Returns the message attributes for a message.
 java.lang.String getName()
          Returns name of this mailbox relative to its parent in the mailbox hierarchy.
 int getNextUID()
          Returns the 32 bit uid available for the next message.
 int getOldestUnseen(java.lang.String user)
          Indicates the oldest unseen message for the specified user.
 java.lang.String getPermanentFlags(java.lang.String username)
          Indicates which flags this user can change permanently.
 int getRecent()
          Indicates no of messages with \Recent flag set
 java.lang.String getSupportedFlags()
          Returns all flags supported by this mailbox.
 int getUIDValidity()
          Returns the current unique id validity value of this mailbox.
 int getUnseen(java.lang.String user)
          Indicates the number of unseen messages for the specified user.
 java.util.Map getUnseenByUser()
          Gets map of users to number of unseen messages.
 boolean hasCreateRights(java.lang.String user)
          Establishes if specified user has create rights for this mailbox.
 boolean hasLookupRights(java.lang.String user)
          Establishes if specified user has lookup rights for this mailbox.
 boolean isMarked()
          Indicates that messages have been added since this mailbox was last selected by any user.
 boolean isNotSelectableByAnyone()
           
 boolean isReadOnly(java.lang.String username)
          Indicates state in which the mailbox will be opened by specified user.
 boolean isSelectable(java.lang.String username)
          Indicates if this folder may be selected by the specified user.
 java.util.List listUIDs(java.lang.String user)
          Lists uids of messages in mailbox indexed by MSN.
 boolean markDeleted(int msn, java.lang.String user)
          Marks a message for deletion given a message sequence number.
 boolean markDeletedUID(int uid, java.lang.String user)
          Marks a message for deletion given a unique identifier.
 boolean matchesName(java.lang.String name)
          Returns true if the argument is the relative or absolute name of this mailbox
 void removeMailboxEventListener(MailboxEventListener mel)
           
 MimeMessageWrapper retrieve(int msn, java.lang.String user)
          Retrieves a message given a message sequence number.
 MimeMessageWrapper retrieveUID(int uid, java.lang.String user)
          Retrieves a message given a unique identifier.
 boolean setFlags(int msn, java.lang.String user, java.lang.String request)
          Updates the flags of a message.
 boolean setFlagsUID(int uid, java.lang.String user, java.lang.String request)
          Updates the flags of a message.
 void setNotSelectableByAnyone(boolean state)
          Mark this mailbox as not selectable by anyone.
 boolean store(javax.mail.internet.MimeMessage message, java.lang.String username)
          Stores a message in this mailbox.
 boolean store(javax.mail.internet.MimeMessage message, java.lang.String username, MessageAttributes attrs, Flags flags)
          Stores a message in this mailbox, using passed MessageAttributes and Flags.
 void unsetRecent()
          Remove \Recent flag from all messages in mailbox.
 boolean updateMessageAttributes(MessageAttributes attrs, java.lang.String user)
          Updates the attributes of a message.
 
Methods inherited from interface org.apache.avalon.framework.configuration.Configurable
configure
 
Methods inherited from interface org.apache.avalon.framework.component.Composable
compose
 

Field Detail

SYSTEM_FLAGS

public static final java.lang.String SYSTEM_FLAGS

RECENT_FLAG

public static final java.lang.String RECENT_FLAG
Method Detail

getName

public java.lang.String getName()
Returns name of this mailbox relative to its parent in the mailbox hierarchy. Example: 'NewIdeas'

getAbsoluteName

public java.lang.String getAbsoluteName()
Returns absolute, that is user-independent, hierarchical name of mailbox (including namespace) Example: '#mail.fred.flintstone.apache.James.NewIdeas'

matchesName

public boolean matchesName(java.lang.String name)
Returns true if the argument is the relative or absolute name of this mailbox
Parameters:
name - possible name for this Mailbox

getUIDValidity

public int getUIDValidity()
Returns the current unique id validity value of this mailbox.

getNextUID

public int getNextUID()
Returns the 32 bit uid available for the next message.

getMailboxSize

public int getMailboxSize()
Returns mailbox size in octets. Should only include actual messages and not any implementation-specific data, such as message attributes.

getInferiorsAllowed

public boolean getInferiorsAllowed()
Indicates if child folders may be created. It does not indicate which users can create child folders.

isSelectable

public boolean isSelectable(java.lang.String username)
                     throws AccessControlException
Indicates if this folder may be selected by the specified user. Requires both that the mailbox is not NotSelectableByAnyone and that the user has at least read rights. It does not indicate whether user can write to mailbox
Parameters:
username - String represnting user
Throws:
AccessControlException - if username does not have lookup rights

isMarked

public boolean isMarked()
Indicates that messages have been added since this mailbox was last selected by any user.

getSupportedFlags

public java.lang.String getSupportedFlags()
Returns all flags supported by this mailbox. e.g. \Answered \Deleted

allFlags

public boolean allFlags(java.lang.String username)
                 throws AccessControlException
Indicates if specified user can change any flag on a permanent basis, except for \Recent which can never be changed by a user.
Parameters:
username - String represnting user
Throws:
AccessControlException - if username does not have lookup rights

getPermanentFlags

public java.lang.String getPermanentFlags(java.lang.String username)
                                   throws AccessControlException
Indicates which flags this user can change permanently. If allFlags() returns true for this user, then this method must have the same return value as getSupportedFlags.
Parameters:
username - String represnting user

getExists

public int getExists()
Indicates number of messages in folder

getRecent

public int getRecent()
Indicates no of messages with \Recent flag set

unsetRecent

public void unsetRecent()
Remove \Recent flag from all messages in mailbox. Should be called whenever a user session finishes.

getOldestUnseen

public int getOldestUnseen(java.lang.String user)
Indicates the oldest unseen message for the specified user.

getUnseen

public int getUnseen(java.lang.String user)
Indicates the number of unseen messages for the specified user.

isReadOnly

public boolean isReadOnly(java.lang.String username)
                   throws AccessControlException
Indicates state in which the mailbox will be opened by specified user. A return value of true indicates Read Only, false indicates Read-Write and an AccessControlException is thrown if user does not have read rights.

Implementations decide if Read Only means only lookup and read rights (lr) or lookup, read and keep seen rights (lrs). This may even vary between mailboxes.

Parameters:
username - String represnting user
Throws:
AccessControlException - if the user can not open this mailbox at least Read-Only.

addMailboxEventListener

public void addMailboxEventListener(MailboxEventListener mel)
Mailbox Events are used to inform registered listeners of events in the Mailbox. Example if mail is delivered to an Inbox or if another user appends/ deletes a message.

removeMailboxEventListener

public void removeMailboxEventListener(MailboxEventListener mel)

store

public boolean store(javax.mail.internet.MimeMessage message,
                     java.lang.String username)
              throws AccessControlException,
                     AuthorizationException,
                     java.lang.IllegalArgumentException
Stores a message in this mailbox. User must have insert rights.
Parameters:
mail - the message to be stored
username - String represnting user
Throws:
AccessControlException - if username does not have lookup rights for this mailbox.
AuthorizationException - if username has lookup rights but does not have insert rights.

store

public boolean store(javax.mail.internet.MimeMessage message,
                     java.lang.String username,
                     MessageAttributes attrs,
                     Flags flags)
              throws AccessControlException,
                     AuthorizationException,
                     java.lang.IllegalArgumentException
Stores a message in this mailbox, using passed MessageAttributes and Flags. User must have insert rights.
Parameters:
mail - the message to be stored
username - String represnting user
attrs - non-null MessageAttributes for use with this Message
flags - a Flags object for this message
Throws:
AccessControlException - if username does not have lookup rights for this mailbox.
AuthorizationException - if username has lookup rights but does not have insert rights.

retrieve

public MimeMessageWrapper retrieve(int msn,
                                   java.lang.String user)
                            throws AccessControlException,
                                   AuthorizationException
Retrieves a message given a message sequence number.
Parameters:
msn - the message sequence number
username - String represnting user
Throws:
AccessControlException - if user does not have lookup rights for this mailbox.
AuthorizationException - if user has lookup rights but does not have read rights.

retrieveUID

public MimeMessageWrapper retrieveUID(int uid,
                                      java.lang.String user)
                               throws AccessControlException,
                                      AuthorizationException
Retrieves a message given a unique identifier.
Parameters:
uid - the unique identifier of a message
username - String represnting user
Throws:
AccessControlException - if user does not have read rights for this mailbox.
AuthorizationException - if user has lookup rights but does not have read rights.

markDeleted

public boolean markDeleted(int msn,
                           java.lang.String user)
                    throws AccessControlException,
                           AuthorizationException
Marks a message for deletion given a message sequence number.
Parameters:
msn - the message sequence number
username - String represnting user
Throws:
AccessControlException - if user does not have read rights for this mailbox.
AuthorizationException - if user has lookup rights but does not have delete rights.

markDeletedUID

public boolean markDeletedUID(int uid,
                              java.lang.String user)
                       throws AccessControlException,
                              AuthorizationException
Marks a message for deletion given a unique identifier.
Parameters:
uidunique - identifier
username - String represnting user
Throws:
AccessControlException - if user does not have read rights for this mailbox.
AuthorizationException - if user has lookup rights but does not have delete rights.

getMessageAttributes

public MessageAttributes getMessageAttributes(int msn,
                                              java.lang.String user)
                                       throws AccessControlException,
                                              AuthorizationException
Returns the message attributes for a message.
Parameters:
msn - message sequence number
username - String represnting user
Throws:
AccessControlException - if user does not have read rights for this mailbox.
AuthorizationException - if user has lookup rights but does not have delete rights.

getMessageAttributesUID

public MessageAttributes getMessageAttributesUID(int uid,
                                                 java.lang.String user)
                                          throws AccessControlException,
                                                 AuthorizationException
Returns the message attributes for a message.
Parameters:
uid - unique identifier
username - String represnting user
Throws:
AccessControlException - if user does not have read rights for this mailbox.
AuthorizationException - if user has lookup rights but does not have delete rights.

updateMessageAttributes

public boolean updateMessageAttributes(MessageAttributes attrs,
                                       java.lang.String user)
                                throws AccessControlException,
                                       AuthorizationException
Updates the attributes of a message.
Parameters:
MessageAttributes - of a message already in this Mailbox
Throws:
AccessControlException - if user does not have read rights for this mailbox.
AuthorizationException - if user has lookup rights but does not have delete rights.

getFlags

public java.lang.String getFlags(int msn,
                                 java.lang.String user)
                          throws AccessControlException,
                                 AuthorizationException
Get the IMAP-formatted String of flags for specified message.
Parameters:
msn - message sequence number for a message in this mailbox
username - String represnting user
Throws:
AccessControlException - if user does not have lookup rights for this mailbox.
AuthorizationException - if user has lookup rights but does not have read rights.

getFlagsUID

public java.lang.String getFlagsUID(int uid,
                                    java.lang.String user)
                             throws AccessControlException,
                                    AuthorizationException
Get the IMAP-formatted String of flags for specified message.
Parameters:
uid - UniqueIdentifier for a message in this mailbox
username - String represnting user
Throws:
AccessControlException - if user does not have lookup rights for this mailbox.
AuthorizationException - if user has lookup rights but does not have read rights.

setFlags

public boolean setFlags(int msn,
                        java.lang.String user,
                        java.lang.String request)
                 throws AccessControlException,
                        AuthorizationException,
                        java.lang.IllegalArgumentException
Updates the flags of a message.
Parameters:
msn - message sequence number for a message in this mailbox
username - String represnting user
request - IMAP formatted string of flag request
Throws:
AccessControlException - if user does not have read rights for this mailbox.
AuthorizationException - if user has lookup rights but does not have delete rights.

setFlagsUID

public boolean setFlagsUID(int uid,
                           java.lang.String user,
                           java.lang.String request)
                    throws AccessControlException,
                           AuthorizationException,
                           java.lang.IllegalArgumentException
Updates the flags of a message.
Parameters:
uid - UniqueIdentifier for a message in this mailbox
username - String represnting user
request - IMAP formatted string of flag request
Throws:
AccessControlException - if user does not have read rights for this mailbox.
AuthorizationException - if user has lookup rights but does not have delete rights.

getInternetHeaders

public javax.mail.internet.InternetHeaders getInternetHeaders(int msn,
                                                              java.lang.String user)
                                                       throws AccessControlException,
                                                              AuthorizationException
Returns the Internet Headers for a message. These are the top-level headers only, ie not MIME part headers or headers of encapsulated messages.
Parameters:
msn - message sequence number
username - String represnting user
Throws:
AccessControlException - if user does not have read rights for this mailbox.
AuthorizationException - if user has lookup rights but does not have delete rights.

getInternetHeadersUID

public javax.mail.internet.InternetHeaders getInternetHeadersUID(int uid,
                                                                 java.lang.String user)
                                                          throws AccessControlException,
                                                                 AuthorizationException
Returns the Internet Headers for a message. These are the top-level headers only, ie not MIME part headers or headers of encapsulated messages.
Parameters:
uid - UniqueIdentifier for a message in this mailbox
username - String represnting user
Throws:
AccessControlException - if user does not have read rights for this mailbox.
AuthorizationException - if user has lookup rights but does not have delete rights.

expunge

public boolean expunge(java.lang.String user)
                throws AccessControlException,
                       AuthorizationException,
                       java.lang.IllegalArgumentException
Removes all messages marked Deleted. User must have delete rights.
Parameters:
username - String represnting user
Throws:
AccessControlException - if user does not have read rights for this mailbox.
AuthorizationException - if user has delete rights but does not have delete rights.

hasLookupRights

public boolean hasLookupRights(java.lang.String user)
Establishes if specified user has lookup rights for this mailbox.
Parameters:
username - String represnting user

hasCreateRights

public boolean hasCreateRights(java.lang.String user)
                        throws AccessControlException
Establishes if specified user has create rights for this mailbox.
Parameters:
username - String represnting user
Throws:
AccessControlException - if user does not have lookup rights for this mailbox.

listUIDs

public java.util.List listUIDs(java.lang.String user)
Lists uids of messages in mailbox indexed by MSN.
Parameters:
username - String represnting user

checkpoint

public boolean checkpoint()
Returns true once this Mailbox has been checkpointed. This may include resolving in-memory state with disk state. Implementations not requiring checkpointing should return immeadiately.

setNotSelectableByAnyone

public void setNotSelectableByAnyone(boolean state)
Mark this mailbox as not selectable by anyone. Example folders at the roots of hierarchies, e. #mail for each user.
Parameters:
state - true if folder is not selectable by anyone

isNotSelectableByAnyone

public boolean isNotSelectableByAnyone()

getUnseenByUser

public java.util.Map getUnseenByUser()
Gets map of users to number of unseen messages. User key will only be present if getOldestUnseen() has been called, usually as a result of an IMAP SELECT or EXAMINE.


Copyright © 2001 Apache Jakarta Project. All Rights Reserved.