org.apache.geronimo.mail
Class AbstractFolder

java.lang.Object
  extended byjavax.mail.Folder
      extended byorg.apache.geronimo.mail.AbstractFolder
Direct Known Subclasses:
IMAPFolder, POP3Folder

public abstract class AbstractFolder
extends javax.mail.Folder

Apache implementation of a generic Folder. May be subclassed for optimisation for specific protocols. This stores messages using an internal List, and allows messages to be cached inside the folder. Note that the messages do not have to be present or fully loaded; it is possible that a message will only contain the message ID and be loaded dynamically on request.

Whilst it is possible for other implementations to override Folder directly, this provides common methods that allow for easier implementation. Subclasses should implement the abstract methods from Folder and the doXxxx() that this requires in order to facilitate creation of future folder types.

Version:
$Revision: 1.3 $ $Date: 2004/03/10 10:00:32 $

Field Summary
 
Fields inherited from class javax.mail.Folder
HOLDS_FOLDERS, HOLDS_MESSAGES, mode, READ_ONLY, READ_WRITE, store
 
Constructor Summary
AbstractFolder(javax.mail.Store store, javax.mail.URLName name)
          Create a new folder associated with the given Store
 
Method Summary
 void appendMessages(javax.mail.Message[] messages)
          Runs through the array of messages and appends them onto the folder using #add(Message).
 void close(boolean expunge)
          Closes the folder, and if expunge, then automatically expunges prior to closure.
 boolean delete(boolean recurse)
           
protected abstract  void doClose()
          Implemented by the provider, to close the folder.
protected abstract  void doDelete(int id)
          Implemented by subclasses to actually delete a message from the store.
protected abstract  javax.mail.Message doGetMessage(int id)
          Implemented by subclasses to actually load a message from the store.
protected abstract  void doOpen(int newMode)
          Implemented by subclasses to perform a rename operation.
protected abstract  boolean doRenameTo(javax.mail.Folder newName)
          Implemented by subclasses to perform a rename operation.
protected abstract  void doRenumberMessageTo(javax.mail.Message message, int id)
          Renumber message with new ID after an expunge occurs.
 javax.mail.Message[] expunge()
          Runs through a list of messages, and removes them from the internal list of messages.
 String getFullName()
          Returns the full URLName of this folder
 javax.mail.Message getMessage(int id)
           
 String getName()
          Returns just the name portion of the URLName
 char getSeparator()
          Uses '/' as the separator.
 int getType()
          Returns HOLDS_MESSAGES.
 boolean hasNewMessages()
           
 javax.mail.Folder[] list(String pattern)
           
 void open(int newMode)
           
 boolean renameTo(javax.mail.Folder newName)
           
 
Methods inherited from class javax.mail.Folder
addConnectionListener, addFolderListener, addMessageChangedListener, addMessageCountListener, copyMessages, create, exists, fetch, finalize, getDeletedMessageCount, getFolder, getMessageCount, getMessages, getMessages, getMessages, getMode, getNewMessageCount, getParent, getPermanentFlags, getStore, getUnreadMessageCount, getURLName, isOpen, isSubscribed, list, listSubscribed, listSubscribed, notifyConnectionListeners, notifyFolderListeners, notifyFolderRenamedListeners, notifyMessageAddedListeners, notifyMessageChangedListeners, notifyMessageRemovedListeners, removeConnectionListener, removeFolderListener, removeMessageChangedListener, removeMessageCountListener, search, search, setFlags, setFlags, setFlags, setSubscribed, toString
 
Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

AbstractFolder

public AbstractFolder(javax.mail.Store store,
                      javax.mail.URLName name)
Create a new folder associated with the given Store

Parameters:
store - the Store this folder is associated with
name - the name of this folder
Method Detail

appendMessages

public void appendMessages(javax.mail.Message[] messages)
                    throws javax.mail.MessagingException
Runs through the array of messages and appends them onto the folder using #add(Message).

Parameters:
messages - the array of messages to add.
Throws:
javax.mail.MessagingException

close

public void close(boolean expunge)
           throws javax.mail.MessagingException
Closes the folder, and if expunge, then automatically expunges prior to closure. Afterwards calls doClose() as a hook to the underlying implementation to do the real close operation.

Throws:
javax.mail.MessagingException

delete

public boolean delete(boolean recurse)
               throws javax.mail.MessagingException
Throws:
javax.mail.MessagingException

doClose

protected abstract void doClose()
                         throws javax.mail.MessagingException
Implemented by the provider, to close the folder. An expunge will already have been performed if required.

Throws:
javax.mail.MessagingException - if an error occurs during closure.

doDelete

protected abstract void doDelete(int id)
                          throws javax.mail.MessagingException
Implemented by subclasses to actually delete a message from the store. This is then removed from the folder's message cache.

Parameters:
id - the message number to delete
Returns:
the newly-created message from the store
Throws:
javax.mail.MessagingException - in case of any error

doGetMessage

protected abstract javax.mail.Message doGetMessage(int id)
                                            throws javax.mail.MessagingException
Implemented by subclasses to actually load a message from the store. This is then cached in the itnernal folder. Note that the message returned does not need to be fully loaded; it can be a placeholder with the message id only and dynamically access the rest of the message when required.

Parameters:
id - the message number to use
Returns:
the newly-created message from the store
Throws:
javax.mail.MessagingException - in case of any error

doOpen

protected abstract void doOpen(int newMode)
                        throws javax.mail.MessagingException
Implemented by subclasses to perform a rename operation. Called by renameTo(), and if successful, the name is update.

Throws:
javax.mail.MessagingException

doRenameTo

protected abstract boolean doRenameTo(javax.mail.Folder newName)
Implemented by subclasses to perform a rename operation. Called by renameTo(), and if successful, the name is update.

Parameters:
newName - the new name to use
Returns:
true if the folder is renamed; false otherwise.

doRenumberMessageTo

protected abstract void doRenumberMessageTo(javax.mail.Message message,
                                            int id)
                                     throws javax.mail.MessagingException
Renumber message with new ID after an expunge occurs. Since the Message#setMessageNumber is protected, there cannot be an implementation that provides it. However, subclasses that use their own implementation of Message (e.g. POP3Message) can set up the setMessageNumber to be protected, and thus available in the local package. This method implementation is likely to look like:
   protected void doRenumberMessageTo(Message message, int id) throws MessagingException {
     ((POP3Message)message).setMessageNumber(id);
   }
 
Note that this cannot be done generically in the superclass since there is no way of making the setMessageNumber() method visible to this class without violating the JavaMail spec.

Parameters:
message - the message to renumber
id - the message id
Throws:
javax.mail.MessagingException

expunge

public javax.mail.Message[] expunge()
                             throws javax.mail.MessagingException
Runs through a list of messages, and removes them from the internal list of messages. Calls

Throws:
javax.mail.MessagingException

getFullName

public String getFullName()
Returns the full URLName of this folder

Returns:
the full URLName of this folder

getMessage

public javax.mail.Message getMessage(int id)
                              throws javax.mail.MessagingException
Throws:
javax.mail.MessagingException

getName

public String getName()
Returns just the name portion of the URLName


getSeparator

public char getSeparator()
                  throws javax.mail.MessagingException
Uses '/' as the separator. This may be overriden by subclases, but is a sensible default.

Throws:
javax.mail.MessagingException

getType

public int getType()
            throws javax.mail.MessagingException
Returns HOLDS_MESSAGES. Override if the server supports folders HOLDS_FOLDERS instead/as well.

Throws:
javax.mail.MessagingException

hasNewMessages

public boolean hasNewMessages()
                       throws javax.mail.MessagingException
Throws:
javax.mail.MessagingException

list

public javax.mail.Folder[] list(String pattern)
                         throws javax.mail.MessagingException
Throws:
javax.mail.MessagingException

open

public void open(int newMode)
          throws javax.mail.MessagingException
Throws:
javax.mail.MessagingException

renameTo

public boolean renameTo(javax.mail.Folder newName)
                 throws javax.mail.MessagingException
Throws:
javax.mail.MessagingException


Copyright © 2003-2005 Apache Software Foundation. All Rights Reserved.