org.apache.james.imapserver
Interface Host

All Superinterfaces:
org.apache.avalon.framework.component.Composable, org.apache.avalon.framework.configuration.Configurable, org.apache.avalon.framework.context.Contextualizable, org.apache.avalon.phoenix.Service
All Known Implementing Classes:
JamesHost

public interface Host
extends org.apache.avalon.framework.configuration.Configurable, org.apache.avalon.framework.component.Composable, org.apache.avalon.framework.context.Contextualizable, org.apache.avalon.phoenix.Service

A host machine that has an IMAP4rev1 messaging server. There should be one instance of this class per instance of James. An IMAP messaging system may span more than one host.

String parameters representing mailbox names must be the full hierarchical name of the target, with namespace, as used by the specified user. Examples: '#mail.Inbox' or '#shared.finance.Q2Earnings'.

An imap Host must keep track of existing and deleted mailboxes. References: rfc 2060, rfc 2193, rfc 2221

Version:
0.1 on 14 Dec 2000
Author:
Charles Benett
See Also:
FolderRecord, RecordRepository

Field Summary
static java.lang.String IMAP_HOST
           
static java.lang.String ROLE
           
 
Method Summary
 ACLMailbox createMailbox(java.lang.String user, java.lang.String mailboxName)
          Returns a reference to a newly created Mailbox.
 boolean deleteMailbox(java.lang.String user, java.lang.String mailboxName)
          Deletes an existing MailBox.
 java.lang.String getDefaultNamespace(java.lang.String username)
          Returns the namespace which should be used for this user unless they expicitly request another.
 ACLMailbox getMailbox(java.lang.String user, java.lang.String mailboxName)
          Returns a reference to an existing Mailbox.
 java.lang.String getMailboxStatus(java.lang.String username, java.lang.String mailboxName, java.util.List dataItems)
          Returns a string giving the status of a mailbox on requested criteria.
 boolean hasLocalAccess(java.lang.String username)
          Establishes if the specified user can access any mailboxes on this host.
 boolean isHomeServer(java.lang.String username)
          Establishes whether this host is the Home Server for the specified user.
 java.util.Collection listMailboxes(java.lang.String username, java.lang.String referenceName, java.lang.String mailboxName, boolean subscribedOnly)
          Returns an iterator over an unmodifiable collection of Strings representing mailboxes on this host and their attributes.
 void releaseMailbox(java.lang.String user, ACLMailbox mbox)
          Releases a reference to a mailbox, allowing Host to do any housekeeping.
 boolean renameMailbox(java.lang.String user, java.lang.String oldMailboxName, java.lang.String newMailboxName)
          Renames an existing MailBox.
 boolean subscribe(java.lang.String username, java.lang.String mailbox)
          Subscribes a user to a mailbox.
 boolean unsubscribe(java.lang.String username, java.lang.String mailbox)
          Unsubscribes from a given mailbox.
 
Methods inherited from interface org.apache.avalon.framework.configuration.Configurable
configure
 
Methods inherited from interface org.apache.avalon.framework.component.Composable
compose
 
Methods inherited from interface org.apache.avalon.framework.context.Contextualizable
contextualize
 

Field Detail

ROLE

public static final java.lang.String ROLE

IMAP_HOST

public static final java.lang.String IMAP_HOST
Method Detail

isHomeServer

public boolean isHomeServer(java.lang.String username)
Establishes whether this host is the Home Server for the specified user. Used during login to decide whether a LOGIN_REFERRAL has to be sent to the client.
Parameters:
username - an email address

hasLocalAccess

public boolean hasLocalAccess(java.lang.String username)
Establishes if the specified user can access any mailboxes on this host. Used during login process to decide what sort of LOGIN-REFERRAL must be sent to client.
Parameters:
username - an email address

getMailbox

public ACLMailbox getMailbox(java.lang.String user,
                             java.lang.String mailboxName)
                      throws AccessControlException,
                             MailboxException
Returns a reference to an existing Mailbox. The requested mailbox must already exists on this server and the requesting user must have at least lookup rights.
Parameters:
user - email address on whose behalf the request is made.
mailboxName - String name of the target.
Throws:
AccessControlException - if the user does not have at least lookup rights.
MailboxException - if mailbox does not exist locally.

createMailbox

public ACLMailbox createMailbox(java.lang.String user,
                                java.lang.String mailboxName)
                         throws AccessControlException,
                                AuthorizationException,
                                MailboxException
Returns a reference to a newly created Mailbox. The request should specify a mailbox that does not already exist on this server, that could exist on this server and that the user has rights to create. If a system allocates different namespaces to different hosts then a request to create a mailbox in a namespace not served by this host would be an error. It is an error to create a mailbox with the name of a mailbox that has been deleted, if that name is still in use.
Parameters:
user - email address on whose behalf the request is made.
mailboxName - String name of the target
Throws:
MailboxException - if mailbox already exists, locally or remotely, or if mailbox cannot be created locally.
AccessControlException - if the user does not have lookup rights for parent or any needed ancestor folder lookup rights.
AuthorizationException - if mailbox could be created locally but user does not have create rights.
See Also:
FolderRecord

deleteMailbox

public boolean deleteMailbox(java.lang.String user,
                             java.lang.String mailboxName)
                      throws MailboxException,
                             AuthorizationException
Deletes an existing MailBox. Specified mailbox must already exist on this server, and the user must have rights to delete it. (Mailbox delete rights are implementation defined, one way is if the user would have the right to create it). Implementations must track deleted mailboxes
Parameters:
user - email address on whose behalf the request is made.
mailboxName - String name of the target
Throws:
MailboxException - if mailbox does not exist locally or is any identities INBOX.
AuthorizationException - if mailbox exists locally but user does not have rights to delete it.
See Also:
FolderRecord

renameMailbox

public boolean renameMailbox(java.lang.String user,
                             java.lang.String oldMailboxName,
                             java.lang.String newMailboxName)
                      throws MailboxException,
                             AuthorizationException
Renames an existing MailBox. The specified mailbox must already exist locally, the requested name must not exist locally already but must be able to be created locally and the user must have rights to delete the existing mailbox and create a mailbox with the new name. Any inferior hierarchical names must also be renamed. If INBOX is renamed, the contents of INBOX are transferred to a new folder with the new name, but INBOX is not deleted. If INBOX has inferior mailboxes these are not renamed. It is an error to create a mailbox with the name of a mailbox that has been deleted, if that name is still in use. Implementations must track deleted mailboxes
Parameters:
user - email address on whose behalf the request is made.
oldMailboxName - String name of the existing mailbox
newMailboxName - String target new name
Throws:
MailboxException - if mailbox does not exist locally, or there is an existing mailbox with the new name.
AuthorizationException - if user does not have rights to delete the existing mailbox or create the new mailbox.
See Also:
FolderRecord

releaseMailbox

public void releaseMailbox(java.lang.String user,
                           ACLMailbox mbox)
Releases a reference to a mailbox, allowing Host to do any housekeeping.
Parameters:
username - String user who has finished with this mailbox
mbox - a non-null reference to an ACL Mailbox.

getDefaultNamespace

public java.lang.String getDefaultNamespace(java.lang.String username)
Returns the namespace which should be used for this user unless they expicitly request another.
Parameters:
username - String an email address

listMailboxes

public java.util.Collection listMailboxes(java.lang.String username,
                                          java.lang.String referenceName,
                                          java.lang.String mailboxName,
                                          boolean subscribedOnly)
                                   throws MailboxException,
                                          AccessControlException
Returns an iterator over an unmodifiable collection of Strings representing mailboxes on this host and their attributes. The specified user must have at least lookup rights for each mailbox returned. If the subscribedOnly flag is set, only mailboxes to which the specified user is currently subscribed should be returned. Implementations that may export circular hierarchies SHOULD restrict the levels of hierarchy returned. The depth suggested by rfc 2683 is 20 hierarchy levels.

The reference name must be non-empty. If the mailbox name is empty, implementations must not throw either exception but must return a single String (described below) if the reference name specifies a local mailbox accessible to the user and a one-character String containing the hierarchy delimiter of the referenced namespace, otherwise.

Each String returned should be a space seperated triple of name attributes, hierarchy delimiter and full mailbox name. The mailbox name should include the namespace and be relative to the specified user.

RFC comments: Implementations SHOULD return quickly. They SHOULD NOT go to excess trouble to calculate\Marked or \Unmarked status.

JAMES comment: By elimination, implementations should usually include \Noinferiors or \Noselect, if appropriate. Also, if the reference name and mailbox name resolve to a single local mailbox, implementations should establish all attributes.

Note that servers cannot unilaterally remove mailboxes from the subscribed list. A request with the subscribedOnly flag set that attempts to list a deleted mailbox must return that mailbox with the \Noselect attribute.

Parameters:
username - String non-empty email address of requester
referenceName - String non-empty name, including namespace, of a mailbox or level of mailbox hierarchy, relative to user.
mailboxName - String name of a mailbox possible including a wildcard.
subscribedOnly - only return mailboxes currently subscribed.
Throws:
AccessControlException - if the user does not have at least lookup rights to at least one mailbox in the set requested.
MailboxException - if the referenceName is not local or if referenceName and mailbox name resolve to a single mailbox which does not exist locally.

subscribe

public boolean subscribe(java.lang.String username,
                         java.lang.String mailbox)
                  throws MailboxException,
                         AccessControlException
Subscribes a user to a mailbox. The mailbox must exist locally and the user must have at least lookup rights to it.
Parameters:
username - String representation of an email address
mailbox - String representation of a mailbox name.
Throws:
AccessControlException - if the mailbox exists but the user does not have lookup rights.
MailboxException - if the mailbox does not exist locally.

unsubscribe

public boolean unsubscribe(java.lang.String username,
                           java.lang.String mailbox)
                    throws MailboxException,
                           AccessControlException
Unsubscribes from a given mailbox.
Parameters:
username - String representation of an email address
mailbox - String representation of a mailbox name.

getMailboxStatus

public java.lang.String getMailboxStatus(java.lang.String username,
                                         java.lang.String mailboxName,
                                         java.util.List dataItems)
                                  throws MailboxException,
                                         AccessControlException
Returns a string giving the status of a mailbox on requested criteria. Currently defined staus items are: MESSAGES - Nummber of messages in mailbox RECENT - Number of messages with \Recent flag set UIDNEXT - The UID that will be assigned to the next message entering the mailbox UIDVALIDITY - The current UIDValidity value for the mailbox UNSEEN - The number of messages which do not have the \Seen flag set.
Parameters:
username - String non-empty email address of requester
mailboxName - String name of a mailbox (no wildcards allowed).
dataItems - Vector of one or more Strings each of a single status item.
Throws:
AccessControlException - if the user does not have at least lookup rights to the mailbox requested.
MailboxException - if the mailboxName does not exist locally.


Copyright © 2001 Apache Jakarta Project. All Rights Reserved.