/**
    * Licensed to the Apache Software Foundation (ASF) under one or more
    * contributor license agreements.  See the NOTICE file distributed with
    * this work for additional information regarding copyright ownership.
    * The ASF licenses this file to You under the Apache License, Version 2.0
    * (the "License"); you may not use this file except in compliance with
    * the License.  You may obtain a copy of the License at
    *
    *     http://www.apache.org/licenses/LICENSE-2.0
   *
   * Unless required by applicable law or agreed to in writing, software
   * distributed under the License is distributed on an "AS IS" BASIS,
   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   * See the License for the specific language governing permissions and
   * limitations under the License.
   */
  
  package org.apache.geronimo.javamail.store.imap;
  
  import java.io.ByteArrayOutputStream;
  import java.io.IOException;
  import java.util.ArrayList;
  import java.util.Date;
  import java.util.HashMap;
  import java.util.Iterator;
  import java.util.LinkedList;
  import java.util.List;
  import java.util.Map;
  import java.util.NoSuchElementException;
  import java.util.Vector;
  
  import javax.mail.*;
  import javax.mail.event.ConnectionEvent;
  import javax.mail.event.FolderEvent;
  import javax.mail.event.MessageChangedEvent;
  import javax.mail.search.FlagTerm;
  import javax.mail.search.SearchTerm;
  
  import org.apache.geronimo.javamail.store.imap.connection.IMAPConnection;
  import org.apache.geronimo.javamail.store.imap.connection.IMAPFetchDataItem;
  import org.apache.geronimo.javamail.store.imap.connection.IMAPFetchResponse;
  import org.apache.geronimo.javamail.store.imap.connection.IMAPFlags;
  import org.apache.geronimo.javamail.store.imap.connection.IMAPListResponse;
  import org.apache.geronimo.javamail.store.imap.connection.IMAPMailboxStatus;
  import org.apache.geronimo.javamail.store.imap.connection.IMAPSizeResponse;
  import org.apache.geronimo.javamail.store.imap.connection.IMAPUid;
  import org.apache.geronimo.javamail.store.imap.connection.IMAPUntaggedResponse;
  import org.apache.geronimo.javamail.store.imap.connection.IMAPUntaggedResponseHandler;
  
  /**
   * The base IMAP implementation of the javax.mail.Folder
   * This is a base class for both the Root IMAP server and each IMAP group folder.
   * @see javax.mail.Folder
   *
   * @version $Rev: 594520 $
   */
  public class IMAPFolder extends Folder implements UIDFolder, IMAPUntaggedResponseHandler {
  
      /**
       * Special profile item used for fetching SIZE and HEADER information.
       * These items are extensions that Sun has added to their IMAPFolder immplementation. 
       * We're supporting the same set. 
       */
      public static class FetchProfileItem extends FetchProfile.Item {
          public static final FetchProfileItem HEADERS = new FetchProfileItem("HEADERS");
          public static final FetchProfileItem SIZE = new FetchProfileItem("SIZE");
  
          protected FetchProfileItem(String name) {
              super(name);
          }
      }
      
      // marker that we don't know the separator yet for this folder. 
      // This occurs when we obtain a folder reference from the 
      // default folder.  At that point, we've not queried the 
      // server for specifics yet. 
      static final protected char UNDETERMINED = 0; 
      
      // our attached session
      protected Session session;
      // retrieved messages, mapped by sequence number.
      protected LinkedList messages;
      // mappings of UIDs to retrieved messages.
      protected Map uidCache;
  
      // the separator the server indicates is used as the hierarchy separator
      protected char separator;
      // the "full" name of the folder.  This is the fully qualified path name for the folder returned by
      // the IMAP server.  Elements of the hierarchy are delimited by "separator" characters.
      protected String fullname;
      // the name of this folder.  The is the last element of the fully qualified name.
      protected String name;
      // the folder open state
  	protected boolean folderOpen = false;
      // the type information on what the folder can hold
      protected int folderType;
      // the subscription status
      protected boolean subscribed = false;
  
     // the message identifier ticker, used to assign message numbers. 
     protected int nextMessageID = 1; 
     // the current count of messages in our cache. 
     protected int maxSequenceNumber = 0;  
     // the reported count of new messages (updated as a result of untagged message resposes)
     protected int recentMessages = -1;
     // the reported count of unseen messages
     protected int unseenMessages = 0;
     // the uidValidity value reported back from the server
     protected long uidValidity = 0;
     // the uidNext value reported back from the server
     protected long uidNext = 0;
     // the persistent flags we save in the store
     protected Flags permanentFlags;
     // the settable flags the server reports back to us
     protected Flags availableFlags;
     // Our cached status information.  We will only hold this for the timeout interval.
     protected IMAPMailboxStatus cachedStatus;
     // Folder information retrieved from the server.  Good info here indicates the 
     // folder exists. 
     protected IMAPListResponse listInfo; 
     // the configured status cache timeout value.
     protected long statusCacheTimeout;
     // the last time we took a status snap shot.
     protected long lastStatusTimeStamp;
     // Our current connection.  We get one of these when opened, and release it when closed. 
     // We do this because for any folder (and message) operations, the folder must be selected on 
     // the connection.  
     // Note, however, that there are operations which will require us to borrow a connection 
     // temporarily because we need to touch the server when the folder is not open.  In those 
     // cases, we grab a connection, then immediately return it to the pool. 
     protected IMAPConnection currentConnection; 
     
     
 
     /**
      * Super class constructor the base IMAPFolder class.
      * 
      * @param store     The javamail store this folder is attached to.
      * @param fullname  The fully qualified name of this folder.
      * @param separator The separtor character used to delimit the different
      *                  levels of the folder hierarchy.  This is used to
      *                  decompose the full name into smaller parts and
      *                  create the names of subfolders.
      */
 	protected IMAPFolder(IMAPStore store, String fullname, char separator) {
 		super(store);
 		this.session = store.getSession();
         this.fullname = fullname;
         this.separator = separator;
         // get the status timeout value from the folder. 
         statusCacheTimeout = store.statusCacheTimeout; 
 	}
 
     /**
      * Retrieve the folder name.  This is the simple folder
      * name at the its hiearchy level.  This can be invoked when the folder is closed.
      * 
      * @return The folder's name.
      */
 	public String getName() {
         // At the time we create the folder, we might not know the separator character yet. 
         // Because of this we need to delay creating the name element until 
         // it's required.  
         if (name == null) {
             // extract the name from the full name
             int lastLevel = -1; 
             try {
                 lastLevel = fullname.lastIndexOf(getSeparator());
             } catch (MessagingException e) {
                 // not likely to occur, but the link could go down before we 
                 // get this.  Just assume a failure to locate the character 
                 // occurred. 
             }
             if (lastLevel == -1) {
                 name = fullname;
             }
             else {
                 name = fullname.substring(lastLevel + 1);
             }
         }
         return name;
 	}
 
     /**
      * Retrieve the folder's full name (including hierarchy information).
      * This can be invoked when the folder is closed.
      *
      * @return The full name value.
      */
 	public String getFullName() {
         return fullname;
 	}
 
 
 
     /**
      * Return the parent for this folder; if the folder is at the root of a heirarchy
      * this returns null.
      * This can be invoked when the folder is closed.
      *
      * @return this folder's parent
      * @throws MessagingException
      */
 	public Folder getParent() throws MessagingException {
         // NB:  We need to use the method form because the separator 
         // might not have been retrieved from the server yet. 
         char separator = getSeparator(); 
         // we don't hold a reference to the parent folder, as that would pin the instance in memory 
         // as long as any any leaf item in the hierarchy is still open.  
         int lastLevel = fullname.lastIndexOf(separator);
         // no parent folder?  Get the root one from the Store.
         if (lastLevel == -1) {
             return ((IMAPStore)store).getDefaultFolder();
         }
         else {
             // create a folder for the parent.
             return new IMAPFolder((IMAPStore)store, fullname.substring(0, lastLevel), separator);
         }
 	}
 
 
     /**
      * Check to see if this folder physically exists in the store.
      * This can be invoked when the folder is closed.
      *
      * @return true if the folder really exists
      * @throws MessagingException if there was a problem accessing the store
      */
     public synchronized boolean exists() throws MessagingException {
         IMAPConnection connection = getConnection(); 
         try {
             return checkExistance(connection); 
         } finally {
             releaseConnection(connection); 
         }
     }
     
     /**
      * Internal routine for checking existance using an 
      * already obtained connection.  Used for situations
      * where the list information needs updating but 
      * we'd end up acquiring a new connection because 
      * the folder isn't open yet. 
      * 
      * @param connection The connection to use.
      * 
      * @return true if the folder exists, false for non-existence.
      * @exception MessagingException
      */
     private boolean checkExistance(IMAPConnection connection) throws MessagingException {
         // get the list response for this folder.
         List responses = connection.list("", fullname);
         // NB, this grabs the latest information and updates 
         // the type information also.  Note also that we need to  
         // use the mailbox name, not the full name.  This is so 
         // the namespace folders will return the correct response. 
         listInfo = findListResponse(responses, getMailBoxName());
 
         if (listInfo == null) {
             return false;
         }
 
         // update the type information from the status.
         folderType = 0;
         if (!listInfo.noinferiors) {
             folderType |= HOLDS_FOLDERS;
         }
         if (!listInfo.noselect) {
             folderType |= HOLDS_MESSAGES;
         }
 
         // also update the separator information.  This will allow 
         // use to skip a call later 
         separator = listInfo.separator;
         // this can be omitted in the response, so assume a default 
         if (separator == '\0') {
             separator = '/';
         }
 
         // updated ok, so it must be there.
         return true;
     }
     
 
 
     /**
      * Return a list of folders from this Folder's namespace that match the supplied pattern.
      * Patterns may contain the following wildcards:
      * <ul><li>'%' which matches any characater except hierarchy delimiters</li>
      * <li>'*' which matches any character including hierarchy delimiters</li>
      * </ul>
      * This can be invoked when the folder is closed.
      * 
      * @param pattern the pattern to search for
      * 
      * @return a possibly empty array containing Folders that matched the pattern
      * @throws MessagingException
      *                if there was a problem accessing the store
      */
     public synchronized Folder[] list(String pattern) throws MessagingException {
         // go filter the folders based on the pattern.  The server does most of the
         // heavy lifting on the pattern matching.
         return filterFolders(pattern, false);
     }
 
 
     /**
      * Return a list of folders to which the user is subscribed and which match the supplied pattern.
      * If the store does not support the concept of subscription then this should match against
      * all folders; the default implementation of this method achieves this by defaulting to the
      * {@link #list(String)} method.
      * 
      * @param pattern the pattern to search for
      * 
      * @return a possibly empty array containing subscribed Folders that matched the pattern
      * @throws MessagingException
      *                if there was a problem accessing the store
      */
     public synchronized Folder[] listSubscribed(String pattern) throws MessagingException {
         // go filter the folders based on the pattern.  The server does most of the
         // heavy lifting on the pattern matching.
         return filterFolders(pattern, true);
     }
 
 
     /**
      * Return the character used by this folder's Store to separate path components.
      *
      * @return the name separater character
      * @throws MessagingException if there was a problem accessing the store
      */
 	public synchronized char getSeparator() throws MessagingException {
         // not determined yet, we need to ask the server for the information 
         if (separator == UNDETERMINED) {
             IMAPConnection connection = getConnection(); 
             try {
                 List responses = connection.list("", fullname);
                 IMAPListResponse info = findListResponse(responses, fullname);
 
                 // if we didn't get any hits, then we just assume a reasonable default. 
                 if (info == null) {
                     separator = '/';
                 }
                 else {
                     separator = info.separator;
                     // this can be omitted in the response, so assume a default 
                     if (separator == '\0') {
                         separator = '/';
                     }
                 }
             } finally {
                 releaseConnection(connection); 
             }
         }
         return separator;
 	}
 
 
     /**
      * Return whether this folder can hold just messages or also
      * subfolders.  
      *
      * @return The combination of Folder.HOLDS_MESSAGES and Folder.HOLDS_FOLDERS, depending 
      * on the folder capabilities. 
      * @exception MessagingException
      */
 	public int getType() throws MessagingException {
         // checking the validity will update the type information 
         // if it succeeds. 
         checkFolderValidity();
 		return folderType;
 	}
     
 
     /**
      * Create a new folder capable of containing subfolder and/or messages as
      * determined by the type parameter. Any hierarchy defined by the folder
      * name will be recursively created.
      * If the folder was sucessfully created, a {@link FolderEvent#CREATED CREATED FolderEvent}
      * is sent to all FolderListeners registered with this Folder or with the Store.
      * 
      * @param newType the type, indicating if this folder should contain subfolders, messages or both
      * 
      * @return true if the folder was sucessfully created
      * @throws MessagingException
      *                if there was a problem accessing the store
      */
 	public synchronized boolean create(int newType) throws MessagingException {
         IMAPConnection connection = getConnection(); 
         try {
 
             // by default, just create using the fullname.  
             String newPath = fullname;
 
             // if this folder is expected to only hold additional folders, we need to
             // add a separator on to the end when we create this.
             if ((newType & HOLDS_MESSAGES) == 0) {
                 newPath = fullname + separator;
             }
             try {
                 // go create this
                 connection.createMailbox(newPath);
                 // verify this exists...also updates some of the status 
                 boolean reallyCreated = checkExistance(connection); 
                 // broadcast a creation event.
                 notifyFolderListeners(FolderEvent.CREATED);
                 return reallyCreated; 
             } catch (MessagingException e) {
                 //TODO add folder level debug logging.
             }
             // we have a failure
             return false;
         } finally {
             releaseConnection(connection); 
         }
 	}
     
 
     /**
      * Return the subscription status of this folder.
      *
      * @return true if the folder is marked as subscribed, false for
      *         unsubscribed.
      */
     public synchronized boolean isSubscribed() {
         try {
             IMAPConnection connection = getConnection(); 
             try {
                 // get the lsub response for this folder.
                 List responses = connection.listSubscribed("", fullname);
 
                 IMAPListResponse response = findListResponse(responses, fullname);
                 if (response == null) {
                     return false;
                 }
                 else {
                     // a NOSELECT flag response indicates the mailbox is no longer 
                     // selectable, so it's also no longer subscribed to. 
                     return !response.noselect; 
                 }
             } finally {
                 releaseConnection(connection); 
             }
         } catch (MessagingException e) {
             // Can't override to throw a MessagingException on this method, so 
             // just swallow any exceptions and assume false is the answer. 
         }
         return false; 
     }
 
 
     /**
      * Set or clear the subscription status of a file.
      *
      * @param flag
      *            The new subscription state.
      */
     public synchronized void setSubscribed(boolean flag) throws MessagingException {
         IMAPConnection connection = getConnection(); 
         try {             
             if (flag) {
                 connection.subscribe(fullname);
             }
             else {
                 connection.unsubscribe(fullname);
             }
         } finally {
             releaseConnection(connection); 
         }
     }
 
     /**
      * Check to see if this Folder conatins messages with the {@link Flag.RECENT} flag set.
      * This can be used when the folder is closed to perform a light-weight check for new mail;
      * to perform an incremental check for new mail the folder must be opened.
      *
      * @return true if the Store has recent messages
      * @throws MessagingException if there was a problem accessing the store
      */
 	public synchronized boolean hasNewMessages() throws MessagingException {
         // the folder must exist for this to work.
         checkFolderValidity();
         
         // get the freshest status information.
         refreshStatus(true);
         // return the indicator from the message state.
         return recentMessages > 0;
 	}
 
     /**
      * Get the Folder determined by the supplied name; if the name is relative
      * then it is interpreted relative to this folder. This does not check that
      * the named folder actually exists.
      *
      * @param name the name of the folder to return
      * @return the named folder
      * @throws MessagingException if there was a problem accessing the store
      */
     public Folder getFolder(String name) throws MessagingException {
         // this must be a real, valid folder to hold a subfolder
         checkFolderValidity(); 
         if (!holdsFolders()) {
             throw new MessagingException("Folder " + fullname + " cannot hold subfolders"); 
         }
         // our separator does not get determined until we ping the server for it.  We 
         // might need to do that now, so we need to use the getSeparator() method to retrieve this. 
         char separator = getSeparator(); 
         
         return new IMAPFolder((IMAPStore)store, fullname + separator + name, separator);
     }
     
 
     /**
      * Delete this folder and possibly any subfolders. This operation can only be
      * performed on a closed folder.
      * If recurse is true, then all subfolders are deleted first, then any messages in
      * this folder are removed and it is finally deleted; {@link FolderEvent#DELETED}
      * events are sent as appropriate.
      * If recurse is false, then the behaviour depends on the folder type and store
      * implementation as followd:
      * <ul>
      * <li>If the folder can only conrain messages, then all messages are removed and
      * then the folder is deleted; a {@link FolderEvent#DELETED} event is sent.</li>
      * <li>If the folder can onlu contain subfolders, then if it is empty it will be
      * deleted and a {@link FolderEvent#DELETED} event is sent; if the folder is not
      * empty then the delete fails and this method returns false.</li>
      * <li>If the folder can contain both subfolders and messages, then if the folder
      * does not contain any subfolders, any messages are deleted, the folder itself
      * is deleted and a {@link FolderEvent#DELETED} event is sent; if the folder does
      * contain subfolders then the implementation may choose from the following three
      * behaviors:
      * <ol>
      * <li>it may return false indicting the operation failed</li>
      * <li>it may remove all messages within the folder, send a {@link FolderEvent#DELETED}
      * event, and then return true to indicate the delete was performed. Note this does
      * not delete the folder itself and the {@link #exists()} operation for this folder
      * will return true</li>
      * <li>it may remove all messages within the folder as per the previous option; in
      * addition it may change the type of the Folder to only HOLDS_FOLDERS indictaing
      * that messages may no longer be added</li>
      * </li>
      * </ul>
      * FolderEvents are sent to all listeners registered with this folder or
      * with the Store.
      *
      * @param recurse whether subfolders should be recursively deleted as well
      * @return true if the delete operation succeeds
      * @throws MessagingException if there was a problem accessing the store
      */
 	public synchronized boolean delete(boolean recurse) throws MessagingException {
         // we must be in the closed state.
         checkClosed();
 
         // if recursive, get the list of subfolders and delete them first.
         if (recurse) {
 
             Folder[] subfolders = list();
             for (int i = 0; i < subfolders.length; i++) {
                 // this is a recursive delete also
                 subfolders[i].delete(true);
             }
         }
 
         IMAPConnection connection = getConnection(); 
         try {
             // delete this one now.
             connection.deleteMailbox(fullname);
             // this folder no longer exists on the server.
             listInfo = null;
 
             // notify interested parties about the deletion.
             notifyFolderListeners(FolderEvent.DELETED);
             return true;
 
         } catch (MessagingException e) {
             // ignored
         } finally {
             releaseConnection(connection); 
         }
         return false;
 	}
 
 
     /**
      * Rename this folder; the folder must be closed.
      * If the rename is successfull, a {@link FolderEvent#RENAMED} event is sent to
      * all listeners registered with this folder or with the store.
      *
      * @param newName the new name for this folder
      * @return true if the rename succeeded
      * @throws MessagingException if there was a problem accessing the store
      */
 	public synchronized boolean renameTo(Folder f) throws MessagingException {
         // we must be in the closed state.
         checkClosed();
         // but we must also exist
         checkFolderValidity();
 
         IMAPConnection connection = getConnection(); 
         try {
             // delete this one now.
             connection.renameMailbox(fullname, f.getFullName());
             // we renamed, so get a fresh set of status 
             refreshStatus(false); 
 
             // notify interested parties about the deletion.
             notifyFolderRenamedListeners(f);
             return true;
         } catch (MessagingException e) {
             // ignored
         } finally {
             releaseConnection(connection); 
         }
         return false;
 	}
 
 
     /**
      * Open this folder; the folder must be able to contain messages and
      * must currently be closed. If the folder is opened successfully then
      * a {@link ConnectionEvent#OPENED} event is sent to listeners registered
      * with this Folder.
      * <p/>
      * Whether the Store allows multiple connections or if it allows multiple
      * writers is implementation defined.
      *
      * @param mode READ_ONLY or READ_WRITE
      * @throws MessagingException if there was a problem accessing the store
      */
 	public synchronized void open(int mode) throws MessagingException {
 
         // we use a synchronized block rather than use a synchronized method so that we
         // can notify the event listeners while not holding the lock.
         synchronized(this) {
             // can only be performed on a closed folder
             checkClosed();
             // ask the store to kindly hook us up with a connection.
             // We're going to hang on to this until we're closed, so store it in 
             // the Folder field.  We need to make sure our mailbox is selected while 
             // we're working things. 
             currentConnection = ((IMAPStore)store).getFolderConnection(this); 
             // we need to make ourselves a handler of unsolicited responses 
             currentConnection.addResponseHandler(this); 
             // record our open mode
             this.mode = mode;
 
 
             try {
                 // try to open, which gives us a lot of initial mailbox state.
                 IMAPMailboxStatus status = currentConnection.openMailbox(fullname, mode == Folder.READ_ONLY);
 
                 // not available in the requested mode?
                 if (status.mode != mode) {
                     // trying to open READ_WRITE and this isn't available?
                     if (mode == READ_WRITE) {
                         throw new ReadOnlyFolderException(this, "Cannot open READ_ONLY folder in READ_WRITE mode");
                     }
                 }
                 
                 // save this status and when we got it for later updating. 
                 cachedStatus = status; 
                 // mark when we got this
                 lastStatusTimeStamp = System.currentTimeMillis();
 
                 // now copy the status information over and flip over the open sign.
                 this.mode = status.mode;
                 maxSequenceNumber = status.messages;
                 recentMessages = status.recentMessages;
                 uidValidity = status.uidValidity;
                 uidNext = status.uidNext;
 
                 availableFlags = status.availableFlags;
                 permanentFlags = status.permanentFlags;
 
                 // create a our caches
                 messages = new LinkedList(); 
                 uidCache = new HashMap();
                 // this is a real pain, but because we need to track updates 
                 // to message sequence numbers while the folder is open, the 
                 // messages list needs to be populated with Message objects 
                 // to keep track of things.  The IMAPMessage objects will not 
                 // retrieve information from the server until required, so they're
                 // relatively lightweight at this point. 
                 populateMessageCache(); 
 
                 // we're open for business folks!
                 folderOpen = true;
                 notifyConnectionListeners(ConnectionEvent.OPENED);
             } finally {
                 // NB:  this doesn't really release this, but it does drive 
                 // the processing of any unsolicited responses. 
                 releaseConnection(currentConnection); 
             }
         }
 	}
     
     
     /**
      * Populate the message cache with dummy messages, ensuring we're filled 
      * up to the server-reported number of messages. 
      * 
      * @exception MessagingException
      */
     protected void populateMessageCache() {
         // spin through the server-reported number of messages and add a dummy one to 
         // the cache.  The message number is assigned from the id counter, the 
         // sequence number is the cache position + 1. 
         for (int i = messages.size(); i < maxSequenceNumber; i++) {
             messages.add(new IMAPMessage(this, ((IMAPStore)store), nextMessageID++, i+1));  
         }
     }
     
 
     /**
      * Close this folder; it must already be open.
      * A  @link ConnectionEvent#CLOSED} event is sent to all listeners registered
      {* 
      * with this folder.
      *
      * @param expunge whether to expunge all deleted messages
      * @throws MessagingException if there was a problem accessing the store; the folder is still closed
      */
 	public synchronized void close(boolean expunge) throws MessagingException {
 		// Can only be performed on an open folder
 		checkOpen();
         cleanupFolder(expunge, false); 
 	}
     
     
     /**
      * Do folder cleanup.  This is used both for normal
      * close operations, and adnormal closes where the
      * server has sent us a BYE message.
      * 
      * @param expunge Indicates whether open messages should be expunged.
      * @param disconnected
      *                The disconnected flag.  If true, the server has cut
      *                us off, which means our connection can not be returned
      *                to the connection pool.
      * 
      * @exception MessagingException
      */
     protected void cleanupFolder(boolean expunge, boolean disconnected) throws MessagingException {
 		folderOpen = false;
         uidCache = null; 
         messages = null; 
         // if we have a connection active at the moment
         if (currentConnection != null) {
             // was this a forced disconnect by the server?
             if (disconnected) {
                 currentConnection.setClosed(); 
             }
             else {
                 // The CLOSE operation depends on what mode was used to select the mailbox.  
                 // If we're open in READ-WRITE mode, we used a SELECT operation.  When CLOSE 
                 // is issued, any deleted messages will be expunged.  If we've been asked not 
                 // to expunge the messages, we have a problem.  The solution is to reselect the 
                 // mailbox using EXAMINE, which will not expunge messages when closed.  
                 if (mode == READ_WRITE && !expunge) {
                     // we can ignore the result...we're just switching modes. 
                     currentConnection.openMailbox(fullname, true);
                 }
                 
                 // have this close the selected mailbox 
                 currentConnection.closeMailbox(); 
             }
             currentConnection.removeResponseHandler(this); 
             // we need to release the connection to the Store once we're closed 
             ((IMAPStore)store).releaseFolderConnection(this, currentConnection); 
             currentConnection = null; 
         }
 		notifyConnectionListeners(ConnectionEvent.CLOSED);
     }
 
     
     /**
      * Tests the open status of the folder.
      *
      * @return true if the folder is open, false otherwise.
      */
 	public boolean isOpen() {
 		return folderOpen;
 	}
 
     /**
      * Get the permanentFlags
      *
      * @return The set of permanent flags we support (only SEEN).
      */
 	public synchronized Flags getPermanentFlags() {
         if (permanentFlags != null) {
             // we need a copy of our master set.
             return new Flags(permanentFlags);
         }
         else {
             // a null return is expected if not there. 
             return null; 
         }
 	}
 
 
     /**
      * Return the number of messages this folder contains.
      * If this operation is invoked on a closed folder, the implementation
      * may choose to return -1 to avoid the expense of opening the folder.
      *
      * @return the number of messages, or -1 if unknown
      * @throws MessagingException if there was a problem accessing the store
      */
 	public synchronized int getMessageCount() throws MessagingException {
         checkFolderValidity();
 
         // if we haven't opened the folder yet, we might not have good status information.
         // go request some, which updates the folder fields also.
         refreshStatus(false);
 		return maxSequenceNumber;
 	}
 
     /**
      * Return the numbew of messages in this folder that have the {@link Flag.RECENT} flag set.
      * If this operation is invoked on a closed folder, the implementation
      * may choose to return -1 to avoid the expense of opening the folder.
      * The default implmentation of this method iterates over all messages
      * in the folder; subclasses should override if possible to provide a more
      * efficient implementation.
      * 
      * NB:  This is an override of the default Folder implementation, which 
      * examines each of the messages in the folder.  IMAP has more efficient 
      * mechanisms for grabbing the information. 
      *
      * @return the number of new messages, or -1 if unknown
      * @throws MessagingException if there was a problem accessing the store
      */
     public synchronized int getNewMessageCount() throws MessagingException {
         // the folder must be a real one for this to work. 
         checkFolderValidity(); 
         // now get current status from the folder 
         refreshStatus(false); 
         // this should be current now. 
         return recentMessages; 
     }
 
 
 
     /**
      * Return the number of messages in this folder that do not have the {@link Flag.SEEN} flag set.
      * If this operation is invoked on a closed folder, the implementation
      * may choose to return -1 to avoid the expense of opening the folder.
      * The default implmentation of this method iterates over all messages
      * in the folder; subclasses should override if possible to provide a more
      * efficient implementation.
      * 
      * NB:  This is an override of the default Folder implementation, which 
      * examines each of the messages in the folder.  IMAP has more efficient 
      * mechanisms for grabbing the information. 
      *
      * @return the number of new messages, or -1 if unknown
      * @throws MessagingException if there was a problem accessing the store
      */
 	public synchronized int getUnreadMessageCount() throws MessagingException {
         checkFolderValidity();
         // if we haven't opened the folder yet, we might not have good status information.
         // go request some, which updates the folder fields also.
         if (!folderOpen) {
             refreshStatus(false);
         }
         else {
             // if we have an open connection, then search the folder for any messages
             // marked UNSEEN.
 
             // UNSEEN is a false test on SEEN using the search criteria.
             SearchTerm criteria = new FlagTerm(new Flags(Flags.Flag.SEEN), false);
             
             // ask the store to kindly hook us up with a connection.
             IMAPConnection connection = getConnection(); 
             try {
                 // search using the connection directly rather than calling our search() method so we don't
                 // need to instantiate each of the matched messages.  We're really only interested in the count
                 // right now.
                 int[] matches = connection.searchMailbox(criteria);
                 // update the unseen count.
                 unseenMessages = matches == null ? 0 : matches.length;
             } finally {
                 releaseConnection(connection); 
             }
         }
         // return our current message count.
 		return unseenMessages;
 	}
 
 
 
     /**
      * Return the number of messages in this folder that have the {@link Flag.DELETED} flag set.
      * If this operation is invoked on a closed folder, the implementation
      * may choose to return -1 to avoid the expense of opening the folder.
      * The default implmentation of this method iterates over all messages
      * in the folder; subclasses should override if possible to provide a more
      * efficient implementation.
      *
      * @return the number of new messages, or -1 if unknown
      * @throws MessagingException if there was a problem accessing the store
      */
 	public synchronized int getDeletedMessageCount() throws MessagingException {
         checkFolderValidity();
 
         // if we haven't opened the folder yet, we might not have good status information.
         // go request some, which updates the folder fields also.
         if (!folderOpen) {
             // the status update doesn't return deleted messages.  These can only be obtained by
             // searching an open folder.  Just return a bail-out response
             return -1;
         }
         else {
             // if we have an open connection, then search the folder for any messages
             // marked DELETED.
 
             // UNSEEN is a false test on SEEN using the search criteria.
             SearchTerm criteria = new FlagTerm(new Flags(Flags.Flag.DELETED), true);
             
             // ask the store to kindly hook us up with a connection.
             IMAPConnection connection = getConnection(); 
             try {
                 // search using the connection directly rather than calling our search() method so we don't
                 // need to instantiate each of the matched messages.  We're really only interested in the count
                 // right now.
                 int[] matches = connection.searchMailbox(criteria);
                 return matches == null ? 0 : matches.length;
             } finally {
                 releaseConnection(connection); 
             }
         }
 	}
 
 
     /**
      * Retrieve the message with the specified index in this Folder;
      * messages indices start at 1 not zero.
      * Clients should note that the index for a specific message may change
      * if the folder is expunged; {@link Message} objects should be used as
      * references instead.
      * 
      * @param msgNum The message sequence number of the target message.
      * 
      * @return the message
      * @throws MessagingException
      *                if there was a problem accessing the store
      */
     public synchronized Message getMessage(int msgNum) throws MessagingException {
         // Can only be performed on an Open folder
         checkOpen();
         // Check the validity of the message number.  This may require pinging the server to
         // see if there are new messages in the folder.
         checkMessageValidity(msgNum);
         // ok, if the message number is within range, we should have this in the 
         // messages list.  Just return the element. 
         return (Message)messages.get(msgNum - 1); 
     }
 
 
     /**
      * Retrieve a range of messages for this folder.
      * messages indices start at 1 not zero.
      * 
      * @param start  Index of the first message to fetch, inclusive.
      * @param end    Index of the last message to fetch, inclusive.
      * 
      * @return An array of the fetched messages.
      * @throws MessagingException
      *                if there was a problem accessing the store
      */
     public synchronized Message[] getMessages(int start, int end) throws MessagingException {
         // Can only be performed on an Open folder
         checkOpen();
         Message[] messageRange = new Message[end - start + 1];
         
         for (int i = 0; i < messageRange.length; i++) {
             // NB:  getMessage() requires values that are origin 1, so there's 
             // no need to adjust the value by other than the start position. 
             messageRange[i] = getMessage(start + i);
         }
         return messageRange; 
     }
 
 
     /**
      * Append the supplied messages to this folder. A {@link MessageCountEvent} is sent
      * to all listeners registered with this folder when all messages have been appended.
      * If the array contains a previously expunged message, it must be re-appended to the Store
      * and implementations must not abort this operation.
      * 
      * @param msgs   The array of messages to append to the folder.
      * 
      * @throws MessagingException
      *                if there was a problem accessing the store
      */
 	public synchronized void appendMessages(Message[] msgs) throws MessagingException {
         checkFolderValidity(); 
         for (int i = 0; i < msgs.length; i++) {
             Message msg = msgs[i]; 
             
             appendMessage(msg); 
         }
 	}
 
     /**
      * Hint to the store to prefetch information on the supplied messages.
      * Subclasses should override this method to provide an efficient implementation;
      * the default implementation in this class simply returns.
      *
      * @param messages messages for which information should be fetched
      * @param profile  the information to fetch
      * @throws MessagingException if there was a problem accessing the store
      * @see FetchProfile
      */
     public void fetch(Message[] messages, FetchProfile profile) throws MessagingException {
         
         // we might already have the information being requested, so ask each of the 
         // messages in the list to evaluate itself against the profile.  We'll only ask 
         // the server to send information that's required. 
         List fetchSet = new ArrayList(); 
         
         for (int i = 0; i < messages.length; i++) {
             Message msg = messages[i]; 
             // the message is missing some of the information still.  Keep this in the list. 
             // even if the message is only missing one piece of information, we still fetch everything. 
             if (((IMAPMessage)msg).evaluateFetch(profile)) {
                 fetchSet.add(msg); 
             }
         }
         
         // we've got everything already, no sense bothering the server 
         if (fetchSet.isEmpty()) {
             return;
         }
         // ask the store to kindly hook us up with a connection.
         IMAPConnection connection = getConnection(); 
         try {
             // ok, from this point onward, we don't want any threads messing with the 
             // message cache.  A single processed EXPUNGE could make for a very bad day 
             synchronized(this) {
                 // get the message set for this 
                 String messageSet = generateMessageSet(fetchSet); 
                 // fetch all of the responses 
                 List responses = connection.fetch(messageSet, profile); 
                 
                 // IMPORTANT:  We must do our updates while synchronized to keep the 
                 // cache from getting updated underneath us.   This includes 
                 // not releasing the connection until we're done to delay processing any 
                 // pending expunge responses.  
                 for (int i = 0; i < responses.size(); i++) {
                     IMAPFetchResponse response = (IMAPFetchResponse)responses.get(i); 
                     Message msg = getMessage(response.getSequenceNumber()); 
                     // Belt and Braces.  This should never be false. 
                     if (msg != null) {
                         // have the message apply this to itself. 
                         ((IMAPMessage)msg).updateMessageInformation(response); 
                     }
                 }
             }
         } finally {
             releaseConnection(connection); 
         }
         return;
     }
 
     /**
      * Set flags on the messages to the supplied value; all messages must belong to this folder.
      * This method may be overridden by subclasses that can optimize the setting
      * of flags on multiple messages at once; the default implementation simply calls
      * {@link Message#setFlags(Flags, boolean)} for each supplied messages.
      * 
      * @param messages whose flags should be set
      * @param flags    the set of flags to modify
      * @param set      Indicates whether the flags should be set or cleared.
      * 
      * @throws MessagingException
      *                if there was a problem accessing the store
      */
     public void setFlags(Message[] messages, Flags flags, boolean set) throws MessagingException {
         // this is a list of messages for the change broadcast after the update 
         List updatedMessages = new ArrayList(); 
         
         synchronized(this) {
             // the folder must be open and writeable.
             checkOpenReadWrite();
 
             // now make sure these are settable flags.
             if (!availableFlags.contains(flags))
             {
                 throw new MessagingException("The IMAP server does not support changing of this flag set");
             }
 
             // turn this into a set of message numbers
             String messageSet = generateMessageSet(messages);
             // if all of the messages have been expunged, nothing to do.
             if (messageSet == null) {
                 return;
             }
             // ask the store to kindly hook us up with a connection.
             IMAPConnection connection = getConnection(); 
 
             try {
                 // and have the connection set this
                 List responses = connection.setFlags(messageSet, flags, set);
                 // retrieve each of the messages from our cache, and do the flag update.
                 // we need to keep the list so we can broadcast a change update event 
                 // when we're finished. 
                 for (int i = 0; i < responses.size(); i++) {
                     IMAPFetchResponse response = (IMAPFetchResponse)responses.get(i); 
 
                     // get the updated message and update the internal state. 
                     Message message = getMessage(response.sequenceNumber); 
                     // this shouldn't happen, but it might have been expunged too. 
                     if (message != null) {
                         ((IMAPMessage)message).updateMessageInformation(response); 
                         updatedMessages.add(message); 
                     }     
                 }
             } finally {
                 releaseConnection(connection); 
             }
         }
         
         // ok, we're no longer holding the lock.  Now go broadcast the update for each 
         // of the affected messages. 
         for (int i = 0; i < updatedMessages.size(); i++) {
             Message message = (Message)updatedMessages.get(i); 
             notifyMessageChangedListeners(MessageChangedEvent.FLAGS_CHANGED, message);
         }
     }
 
     
     /**
      * Set flags on a range of messages to the supplied value.
      * This method may be overridden by subclasses that can optimize the setting
      * of flags on multiple messages at once; the default implementation simply
      * gets each message and then calls {@link Message#setFlags(Flags, boolean)}.
      * 
      * @param start  first message end set
      * @param end    last message end set
      * @param flags  the set of flags end modify
      * @param value  Indicates whether the flags should be set or cleared.
      * 
      * @throws MessagingException
      *                if there was a problem accessing the store
      */
     public synchronized void setFlags(int start, int end, Flags flags, boolean value) throws MessagingException {
         Message[] msgs = new Message[end - start + 1]; 
         
         for (int i = start; i <= end; i++) {
             msgs[i] = getMessage(i);
         }
         // go do a bulk set operation on these messages 
         setFlags(msgs, flags, value); 
     }
 
     /**
      * Set flags on a set of messages to the supplied value.
      * This method may be overridden by subclasses that can optimize the setting
      * of flags on multiple messages at once; the default implementation simply
      * gets each message and then calls {@link Message#setFlags(Flags, boolean)}.
      * 
      * @param ids    the indexes of the messages to set
      * @param flags  the set of flags end modify
      * @param value  Indicates whether the flags should be set or cleared.
      * 
      * @throws MessagingException
      *                if there was a problem accessing the store
      */
     public synchronized void setFlags(int ids[], Flags flags, boolean value) throws MessagingException {
         Message[] msgs = new Message[ids.length]; 
         
         for (int i = 0; i <ids.length; i++) {
             msgs[i] = getMessage(ids[i]);
         }
         // go do a bulk set operation on these messages 
         setFlags(msgs, flags, value); 
     }
 
     
     /**
      * Copy the specified messages to another folder.
      * The default implementation simply appends the supplied messages to the
      * target folder using {@link #appendMessages(Message[])}.
      * @param messages the messages to copy
      * @param folder the folder to copy to
      * @throws MessagingException if there was a problem accessing the store
      */
     public synchronized void copyMessages(Message[] messages, Folder folder) throws MessagingException {
         // the default implementation just appends the messages to the target.  If 
         // we're copying between two folders of the same store, we can get the server to 
         // do most of the work for us without needing to fetch all of the message data.  
         // If we're dealing with two different Store instances, we need to do this the 
         // hardway.
         if (getStore() != folder.getStore()) {
             super.copyMessages(messages, folder); 
             return; 
         }
 
         // turn this into a set of message numbers
         String messageSet = generateMessageSet(messages);
         // if all of the messages have been expunged, nothing to do.
         if (messageSet == null) {
             return;
         }
         // ask the store to kindly hook us up with a connection.
         IMAPConnection connection = getConnection(); 
 
         try {
             // ask the server to copy this information over to the other mailbox. 
             connection.copyMessages(messageSet, folder.getFullName()); 
         } finally {
             releaseConnection(connection); 
         }
     }
 
     
 
     /**
      * Permanently delete all supplied messages that have the DELETED flag set from the Store.
      * The original message indices of all messages actually deleted are returned and a
      * {@link MessageCountEvent} event is sent to all listeners with this folder. The expunge
      * may cause the indices of all messaged that remain in the folder to change.
      *
      * @return the original indices of messages that were actually deleted
      * @throws MessagingException if there was a problem accessing the store
      */
 	public synchronized Message[] expunge() throws MessagingException {
         // must be open to do this.
         checkOpen();
         // and changes need to be allowed
         checkReadWrite();
 
         // ask the store to kindly hook us up with a connection.
         IMAPConnection connection = getConnection(); 
         List expunges = null;
 
         try {
             // send the expunge notification.  This operation results in "nn EXPUNGE" responses getting returned
             // for each expunged messages.  These will be dispatched to our response handler, which will process
             // the expunge operation.  We could process this directly, but we may have received asynchronous
             // expunge messages that also marked messages as expunged.
             expunges = connection.expungeMailbox();
         } finally {
             releaseConnection(connection); 
         }
 
         // we get one EXPUNGE message for each message that's expunged.  They MUST be processed in 
         // order, as the message sequence numbers represent a relative position that takes into account 
         // previous expunge operations.  For example, if message sequence numbers 5, 6, and 7 are 
         // expunged, we receive 3 expunge messages, all indicating that message 5 has been expunged. 
         Message[] messages = new Message[expunges.size()]; 
 
         // now we need to protect the internal structures
         synchronized (this) {
             // expunge all of the messages from the message cache.  This keeps the sequence 
             // numbers up to-date. 
             for (int i = 0; i < expunges.size(); i++) {
                 IMAPSizeResponse response = (IMAPSizeResponse)expunges.get(i); 
                 messages[i] = expungeMessage(response.getSize()); 
             }
         }
         // if we have messages that have been removed, broadcast the notification.
         if (messages.length > 0) {
             notifyMessageRemovedListeners(true, messages);
         }
 
         // note, we're expected to return an array in all cases, even if the expunged count was zero.
         return messages;
 	}
 
 
 
     /**
      * Search the supplied messages for those that match the supplied criteria;
      * messages must belong to this folder.
      * The default implementation iterates through the messages, returning those
      * whose {@link Message#match(javax.mail.search.SearchTerm)} method returns true;
      * subclasses may provide a more efficient implementation.
      *
      * @param term the search criteria
      * @param messages the messages to search
      * @return an array containing messages that match the criteria
      * @throws MessagingException if there was a problem accessing the store
      */
     public synchronized Message[] search(SearchTerm term) throws MessagingException {
         // only allowed on open folders
         checkOpen();
 
         // ask the store to kindly hook us up with a connection.
         IMAPConnection connection = getConnection(); 
 
         try {
             // just search everything
             int[] messageNumbers = connection.searchMailbox(term);
             return resolveMessages(messageNumbers);
         } finally {
             releaseConnection(connection); 
         }
     }
 
 
 
     /**
      * Search the supplied messages for those that match the supplied criteria;
      * messages must belong to this folder.
      * The default implementation iterates through the messages, returning those
      * whose {@link Message#match(javax.mail.search.SearchTerm)} method returns true;
      * subclasses may provide a more efficient implementation.
      *
      * @param term the search criteria
      * @param messages the messages to search
      * @return an array containing messages that match the criteria
      * @throws MessagingException if there was a problem accessing the store
      */
     public synchronized Message[] search(SearchTerm term, Message[] messages) throws MessagingException {
         // only allowed on open folders
         checkOpen();
 
         // turn this into a string specifier for these messages.  We'll weed out the expunged messages first.
         String messageSet = generateMessageSet(messages);
 
         // If we have no "live" messages to search, just return now.  We're required to return a non-null
         // value, so give an empy array back.
         if (messageSet == null) {
             return new Message[0];
         }
 
         // ask the store to kindly hook us up with a connection.
         IMAPConnection connection = getConnection(); 
 
         try {
 
             // now go do the search.
             int[] messageNumbers = connection.searchMailbox(messageSet, term);
             return resolveMessages(messageNumbers);
         } finally {
             releaseConnection(connection); 
         }
     }
 
     /**
      * Get the UID validity value for this Folder.
      * 
      * @return The current UID validity value, as a long. 
      * @exception MessagingException
      */
     public synchronized long getUIDValidity() throws MessagingException
     {
         // get the latest status to make sure we have the  
         // most current. 
         refreshStatus(true); 
         return uidValidity; 
     }
 
     /**
      * Retrieve a message using the UID rather than the 
      * message sequence number.  Returns null if the message
      * doesn't exist.
      * 
      * @param uid    The target UID.
      * 
      * @return the Message object.  Returns null if the message does
      *         not exist.
      * @exception MessagingException
      */
     public synchronized Message getMessageByUID(long uid) throws MessagingException
     {
         // only allowed on open folders
         checkOpen();
         
         Long key = new Long(uid); 
         // first check to see if we have a cached value for this 
         synchronized(messages) {
             Message msg = (Message)uidCache.get(key); 
             if (msg != null) {
                 return msg; 
             }
         }
 
         // ask the store to kindly hook us up with a connection.
         IMAPConnection connection = getConnection(); 
 
         try {
             // locate the message identifier 
             IMAPUid imapuid = connection.getSequenceNumberForUid(uid);
             // if nothing is returned, the message doesn't exist 
             if (imapuid == null) {
                 return null; 
             }
             
             
             // retrieve the actual message object and place this in the UID cache
             return retrieveMessageByUid(key, imapuid.messageNumber); 
         } finally {
             releaseConnection(connection); 
         }
     }
 
     /**
      * Get a series of messages using a UID range.  The 
      * special value LASTUID can be used to mark the 
      * last available message.
      * 
      * @param start  The start of the UID range.
      * @param end    The end of the UID range.  The special value
      *               LASTUID can be used to request all messages up
      *               to the last UID.
      * 
      * @return An array containing all of the messages in the 
      *         range.
      * @exception MessagingException
      */
     public synchronized Message[] getMessagesByUID(long start, long end) throws MessagingException
     {
         // only allowed on open folders
         checkOpen();
         // ask the store to kindly hook us up with a connection.
         IMAPConnection connection = getConnection(); 
 
         try {
             // locate the message identifier 
             List uids = connection.getSequenceNumbersForUids(start, end);
             Message[] msgs = new Message[uids.size()];
             
             // fill in each of the messages based on the returned value 
             for (int i = 0; i < msgs.length; i++) {
                 IMAPUid uid = (IMAPUid)uids.get(i); 
                 msgs[i] = retrieveMessageByUid(new Long(uid.uid), uid.messageNumber);
             }
             
             return msgs; 
         } finally {
             releaseConnection(connection); 
         }
         
         
     }
 
     /**
      * Retrieve a set of messages by explicit UIDs.  If 
      * any message in the list does not exist, null 
      * will be returned for the corresponding item.
      * 
      * @param ids    An array of UID values to be retrieved.
      * 
      * @return An array of Message items the same size as the ids
      *         argument array.  This array will contain null
      *         entries for any UIDs that do not exist.
      * @exception MessagingException
      */
     public synchronized Message[] getMessagesByUID(long[] ids) throws MessagingException
     {
         // only allowed on open folders
         checkOpen();
         
         Message[] msgs = new Message[ids.length];
         
         for (int i = 0; i < msgs.length; i++) {
             msgs[i] = getMessageByUID(ids[i]); 
         }
         
         return msgs; 
     }
 
     /**
      * Retrieve the UID for a message from this Folder.
      * The argument Message MUST belong to this Folder
      * instance, otherwise a NoSuchElementException will 
      * be thrown.
      * 
      * @param message The target message.
      * 
      * @return The UID associated with this message.
      * @exception MessagingException
      */
     public synchronized long getUID(Message message) throws MessagingException
     {
         // verify this actually is in this folder. 
         checkMessageFolder(message); 
         IMAPMessage msg = (IMAPMessage)message; 
         
         // we might already know this bit of information 
         if (msg.getUID() != -1) {
             return msg.getUID(); 
         }
 
         // ask the store to kindly hook us up with a connection.
         IMAPConnection connection = getConnection(); 
 
         try {
             // locate the message identifier 
             IMAPUid imapuid = connection.getUidForSequenceNumber(msg.getMessageNumber());
             // if nothing is returned, the message doesn't exist 
             if (imapuid == null) {
                 return -1;
             }
             // cache this information now that we've gotten it. 
             addToUidCache(new Long(imapuid.uid), getMessage(imapuid.messageNumber));
             // return the UID information. 
             return imapuid.uid; 
         } finally {
             releaseConnection(connection); 
         }
     }
     
     /**
      * Retrieve a message from a UID/message mapping.
      * 
      * @param key       The UID key used for the mapping.
      * @param msgNumber The message sequence number.
      * 
      * @return The Message object corresponding to the message.
      * @exception MessagingException
      */
     protected synchronized Message retrieveMessageByUid(Long key, int msgNumber) throws MessagingException
     {
         synchronized (messages) {
             // first check the cache...this might have already been added. 
             Message msg = (Message)uidCache.get(key); 
             if (msg != null) {
                 return msg; 
             }
             
             // retrieve the message by sequence number 
             msg = getMessage(msgNumber); 
             // add this to our UID mapping cache. 
             addToUidCache(key, msg); 
             return msg; 
         }
     }
     
     
     /**
      * Add a message to the UID mapping cache, ensuring that 
      * the UID value is updated.
      * 
      * @param key    The UID key.
      * @param msg    The message to add.
      */
     protected void addToUidCache(Long key, Message msg) {  
         synchronized (messages) {
             ((IMAPMessage)msg).setUID(key.longValue());  
             uidCache.put(key, msg); 
         }
     }
     
     
     /**
      * Append a single message to the IMAP Folder.
      * 
      * @param msg    The message to append.
      * 
      * @exception MessagingException
      */
     protected synchronized void appendMessage(Message msg) throws MessagingException 
     {
         // sort out the dates.  If no received date, use the sent date. 
         Date date = msg.getReceivedDate(); 
         if (date == null) {
             date = msg.getSentDate(); 
         }
         
         Flags flags = msg.getFlags(); 
         
         // convert the message into an array of bytes we can attach as a literal. 
         ByteArrayOutputStream out = new ByteArrayOutputStream(); 
         
         try {
             msg.writeTo(out); 
         } catch (IOException e) {
         }
         
         // now issue the append command 
         IMAPConnection connection = getConnection(); 
         try {
             connection.appendMessage(getFullName(), date, flags, out.toByteArray()); 
         } finally {
             releaseConnection(connection); 
         }
     }
 
     
     /**
      * Retrieve the list of matching groups from the IMAP server using the LIST
      * or LSUB command. The server does the wildcard matching for us.
      *
      * @param pattern
      *            The pattern string (in wildmat format) used to match.
      *
      * @return An array of folders for the matching groups.
      */
     protected synchronized Folder[] filterFolders(String pattern, boolean subscribed) throws MessagingException {
         IMAPConnection connection = getConnection(); 
         // this is used to filter out our own folder from the search 
         String root = fullname + getSeparator();
         
         List responses = null;
         try {             
 
 
             if (subscribed) {
                 // get the lsub response for this folder.
                 responses = connection.listSubscribed(root, pattern);
             }
             else {
                 // grab using the LIST command.
                 responses = connection.list(root, pattern);
             }
         } finally {
             releaseConnection(connection); 
         }
 
         List folders = new ArrayList();
 
         for (int i = 0; i < responses.size(); i++) {
             IMAPListResponse response = (IMAPListResponse)responses.get(i);
             // if a full wildcard is specified, the root folder can be returned too.  Make sure we
             // filter that one out.
             if (!response.mailboxName.equals(root)) {
                 IMAPFolder folder = new IMAPFolder((IMAPStore)store, response.mailboxName, response.separator);
                 folders.add(folder);
             }
         }
 
         // convert into an array and return
         return (Folder[])folders.toArray(new Folder[folders.size()]);
     }
 
 
     /**
      * Test if a folder can hold sub folders.
      *
      * @return True if the folder is allowed to have subfolders.
      */
     protected synchronized boolean holdsFolders() throws MessagingException {
         checkFolderValidity();
         return (folderType & HOLDS_FOLDERS) != 0;
     }
 
 
     /**
      * Validate that a target message number is considered valid
      * by the IMAP server.  If outside of the range we currently
      * are a ware of, we'll ping the IMAP server to see if there
      * have been any updates.
      *
      * @param messageNumber
      *               The message number we're checking.
      *
      * @exception MessagingException
      */
     protected void checkMessageValidity(int messageNumber) throws MessagingException {
         // lower range for a message is 1.
         if (messageNumber < 1) {
             throw new MessagingException("Invalid message number for IMAP folder: " + messageNumber);
         }
         // if within our current known range, we'll accept this
         if (messageNumber <= maxSequenceNumber) {
             return;
         }
         
         IMAPConnection connection = getConnection(); 
 
         synchronized (this) {
             try {
                 // ping the server to see if there's any updates to process.  The updates are handled
                 // by the response handlers.
                 connection.updateMailboxStatus();
             } finally {
                 releaseConnection(connection); 
             }
         }
 
         // still out of range?
         if (messageNumber > maxSequenceNumber) {
             throw new MessagingException("Message " + messageNumber + " does not exist on server");
         }
     }
 
 
 	/**
 	 * Below is a list of convenience methods that avoid repeated checking for a
 	 * value and throwing an exception
 	 */
 
     /**
      * Ensure the folder is open.  Throws a MessagingException
      * if not in the correct state for the operation.
      * 
      * @exception IllegalStateException
      */
     protected void checkOpen() throws IllegalStateException {
 		if (!folderOpen){
 		    throw new IllegalStateException("Folder is not Open");
 		}
     }
 
     /**
      * Ensure the folder is not open for operations
      * that require the folder to be closed.
      * 
      * @exception IllegalStateException
      */
     protected void checkClosed() throws IllegalStateException {
 		if (folderOpen){
 		    throw new IllegalStateException("Folder is Open");
 		}
     }
 
     /**
      * Ensure that the folder is open for read/write mode before doing
      * an operation that would make a change.
      *
      * @exception IllegalStateException
      */
     protected void checkReadWrite() throws IllegalStateException {
         if (mode != READ_WRITE) {
 		    throw new IllegalStateException("Folder is opened READY_ONLY");
         }
     }
 
 
     /**
      * Check that the folder is open and in read/write mode.
      *
      * @exception IllegalStateException
      */
     protected void checkOpenReadWrite() throws IllegalStateException {
         checkOpen();
         checkReadWrite();
     }
 
 
 
     /**
      * Notify the message changed listeners that a 
      * message contained in the folder has been updated.
      * 
      * @param type   The type of update made to the message.
      * @param m      The message that was updated.
      * 
      * @see javax.mail.Folder#notifyMessageChangedListeners(int, javax.mail.Message)
      */
     public void notifyMessageChangedListeners(int type, Message m) {
     	super.notifyMessageChangedListeners(type, m);
     }
 
     
     /**
      * Retrieve the connection attached to this folder.  Throws an
      * exception if we don't have an active connection.
      *
      * @return The current connection object.
      * @exception MessagingException
      */
     protected synchronized IMAPConnection getConnection() throws MessagingException {
         // don't have an open connection yet?  Just request a pool connection. 
         if (currentConnection == null) {
             // request a connection from the central store. 
             IMAPConnection connection = ((IMAPStore)store).getFolderConnection(this);  
             // we need to make ourselves a handler of unsolicited responses 
             connection.addResponseHandler(this); 
             return connection;
         }
         // we have a connection for our use.  Just return it. 
         return currentConnection; 
     }
     
     
     /**
      * Release our connection back to the Store.
      * 
      * @param connection The connection to release.
      * 
      * @exception MessagingException
      */
     protected void releaseConnection(IMAPConnection connection) throws MessagingException {
         // This is a bit of a pain.  We need to delay processing of the 
         // unsolicited responses until after each user of the connection has 
         // finished processing the expected responses.  We need to do this because 
         // the unsolicited responses may include EXPUNGED messages.  The EXPUNGED 
         // messages will alter the message sequence numbers for the messages in the 
         // cache.  Processing the EXPUNGED messages too early will result in 
         // updates getting applied to the wrong message instances.  So, as a result, 
         // we delay that stage of the processing until all expected responses have 
         // been handled.  
         
         // process any pending messages before returning. 
         connection.processPendingResponses(); 
         // if no cached connection or this is somehow different from the cached one, just 
         // return it. 
         if (currentConnection == null || connection != currentConnection) {
             connection.removeResponseHandler(this); 
             ((IMAPStore)store).releaseFolderConnection(this, connection);  
         }
         // if we're open, then we don't have to worry about returning this connection 
         // to the Store.  This is set up perfectly for our use right now. 
     }
     
     
     /**
      * Obtain a connection object for a Message attached to this Folder.  This 
      * will be the Folder's connection, which is only available if the Folder 
      * is currently open.
      * 
      * @return The connection object for the Message instance to use. 
      * @exception MessagingException
      */
     synchronized IMAPConnection getMessageConnection() throws MessagingException {
         // if we're not open, the messages can't communicate either
         if (currentConnection == null) {
             throw new FolderClosedException(this, "No Folder connections available"); 
         }
         // return the current Folder connection.  At this point, we'll be sharing the 
         // connection between the Folder and the Message (and potentially, other messages).  The 
         // command operations on the connection are synchronized so only a single command can be 
         // issued at one time. 
         return currentConnection; 
     }
     
     
     /**
      * Release the connection object back to the Folder instance.  
      * 
      * @param connection The connection being released.
      * 
      * @exception MessagingException
      */
     void releaseMessageConnection(IMAPConnection connection) throws MessagingException {
         // release it back to ourselves...this will drive unsolicited message processing. 
         releaseConnection(connection); 
     }
 
 
     /**
      * Refresh the status information on this folder.
      * 
      * @param force  Force a status refresh always.
      * 
      * @exception MessagingException
      */
     protected void refreshStatus(boolean force) throws MessagingException {
         // first check that any cached status we've received has gotten a little moldy.
         if (cachedStatus != null) {
             // if not forcing, check the time out. 
             if (!force) {
                 if (statusCacheTimeout > 0) {
                     long age = System.currentTimeMillis() - lastStatusTimeStamp;
                     if (age < statusCacheTimeout) {
                         return;                 
                     }
                 }
             }
             // make sure the stale information is cleared out.
             cachedStatus = null;
         }
         
         IMAPConnection connection = getConnection(); 
         try {
             // ping the server for the list information for this folder
             cachedStatus = connection.getMailboxStatus(fullname);
             // mark when we got this
             lastStatusTimeStamp = System.currentTimeMillis();
         } finally {
             releaseConnection(connection); 
         }
 
         // refresh the internal state from the message information
         maxSequenceNumber = cachedStatus.messages;
         recentMessages = cachedStatus.recentMessages;
         unseenMessages = cachedStatus.unseenMessages;
         uidValidity = cachedStatus.uidValidity;
     }
 
 
     /**
      * Process an EXPUNGE response for a message, removing the
      * message from the message cache.
      * 
      * @param sequenceNumber
      *               The sequence number for the expunged message.
      * 
      * @return The Message object corresponding to this expunged
      *         message.
      * @exception MessagingException
      */
     protected synchronized Message expungeMessage(int sequenceNumber) throws MessagingException {
         // we need to remove this from our message list.  Deletion of a message by 
         // sequence number shifts the sequence numbers of every message after 
         // the target.  So we, need to remove the message, update its status, then 
         // update the sequence numbers of every message after that.  This is a serious 
         // pain!
         
         Message expungedMessage = (Message)messages.remove(sequenceNumber - 1); 
         // mark the message as expunged. 
         ((IMAPMessage)expungedMessage).setExpunged(true); 
         
         // update the message sequence numbers for every message after the 
         // expunged one.  NB.  The sequence number is the cache index + 1
         for (int i = sequenceNumber - 1; i < messages.size(); i++) {
             IMAPMessage message = (IMAPMessage)messages.get(i); 
             message.setSequenceNumber(i + 1); 
         }
         
         // have we retrieved a UID for this message?  If we have, then it's in the UID cache and
         // needs removal from there also
         long uid = ((IMAPMessage)expungedMessage).getUID();
         if (uid >= 0) {
             uidCache.remove(new Long(uid));
         }
 
         // adjust the message count downward
         maxSequenceNumber--;
         return expungedMessage; 
     }
 
 
     /**
      * Resolve an array of message numbers into an array of the
      * referenced messages.
      *
      * @param messageNumbers
      *               The array of message numbers (can be null).
      *
      * @return An array of Message[] containing the resolved messages from
      *         the list.  Returns a zero-length array if there are no
      *         messages to resolve.
      * @exception MessagingException
      */
     protected Message[] resolveMessages(int[] messageNumbers) throws MessagingException {
         // the connection search returns a null pointer if nothing was found, just convert this into a
         // null array.
         if (messageNumbers == null) {
             return new Message[0];
         }
 
         Message[] messages = new Message[messageNumbers.length];
 
         // retrieve each of the message numbers in turn.
         for (int i = 0; i < messageNumbers.length; i++) {
             messages[i] = getMessage(messageNumbers[i]);
         }
 
         return messages;
     }
     
     /**
      * Generate a message set string from a List of messages rather than an 
      * array.
      * 
      * @param messages The List of messages.
      * 
      * @return The evaluated message set string. 
      * @exception MessagingException
      */
     protected String generateMessageSet(List messages) throws MessagingException {
         Message[] msgs = (Message[])messages.toArray(new Message[messages.size()]); 
         return generateMessageSet(msgs); 
     }
 
 
     /**
      * Take an array of messages and generate a String <message set>
      * argument as specified by RFC 2060.  The message set argument
      * is a comma-separated list of message number ranges.  A
      * single element range is just one number.  A longer range is
      * a pair of numbers separated by a ":".  The generated string
      * should not have any blanks.  This will attempt to locate
      * consequetive ranges of message numbers, but will only do this
      * for messages that are already ordered in the array (i.e., we
      * don't try to sort).  Expunged messages are excluded from the
      * search, since they don't exist anymore.  A valid search string
      * will look something like this:
      *
      *    "3,6:10,15,21:35"
      *
      * @param messages The array of messages we generate from.
      *
      * @return A string formatted version of these message identifiers that
      *         can be used on an IMAP command.
      */
     protected String generateMessageSet(Message[] messages) throws MessagingException {
         StringBuffer set = new StringBuffer();
 
         for (int i = 0; i < messages.length; i++) {
             // first scan the list looking for a "live" message.
             IMAPMessage start = (IMAPMessage)messages[i];
             if (!start.isExpunged()) {
 
                 // we can go ahead and add this to the list now.  If we find this is the start of a
                 // range, we'll tack on the ":end" bit once we find the last message in the range.
                 if (set.length() != 0) {
                     // only append the comma if not the first element of the list
                     set.append(',');
                 }
 
                 // append the first number.  NOTE:  We append this directly rather than 
                 // use appendInteger(), which appends it using atom rules. 
                 set.append(Integer.toString(start.getSequenceNumber()));
 
                 // ok, we have a live one.  Now scan the list from here looking for the end of
                 // a range of consequetive messages.
                 int endIndex = -1; ;
                 // get the number we're checking against.
                 int previousSequence = start.getSequenceNumber();
                 for (int j = i + 1; j < messages.length; j++) {
                     IMAPMessage message = (IMAPMessage)messages[j];
                     if (!message.isExpunged()) {
                         // still consequetive?
                         if (message.getSequenceNumber() == previousSequence + 1) {
                             // step this for the next check.
                             previousSequence++;
                             // record this as the current end of the range.
                             endIndex = j;
                         }
                         else {
                             // found a non-consequetive one, stop here
                             break;
                         }
                     }
                 }
 
                 // have a range end point?  Add the range specifier and step the loop index point
                 // to skip over this
                 if (endIndex != -1) {
                     // pick up the scan at the next location
                     i = endIndex;
 
                     set.append(':');
                     set.append(Integer.toString(((IMAPMessage)messages[endIndex]).getSequenceNumber()));
                 }
             }
         }
 
         // return null for an empty list. This is possible because either an empty array has been handed to
         // us or all of the messages in the array have been expunged.
         if (set.length() == 0) {
             return null;
         }
         return set.toString();
     }
     
     /**
      * Verify that this folder exists on the server before 
      * performning an operation that requires a valid 
      * Folder instance. 
      * 
      * @exception MessagingException
      */
     protected void checkFolderValidity() throws MessagingException {
         // if we are holding a current listinfo response, then 
         // we have chached existance information.  In that case, 
         // all of our status is presumed up-to-date and we can go 
         // with that.  If we don't have the information, then we 
         // ping the server for it. 
         if (listInfo == null && !exists()) {
             throw new FolderNotFoundException(this, "Folder " + fullname + " not found on server"); 
         }
     }
     
     
     /**
      * Check if a Message is properly within the target 
      * folder. 
      * 
      * @param msg    The message we're checking.
      * 
      * @exception MessagingException
      */
     protected void checkMessageFolder(Message msg) throws MessagingException {
         if (msg.getFolder() != this) {
             throw new NoSuchElementException("Message is not within the target Folder"); 
         }
     }
 
 
     /**
      * Search a list of LIST responses for one containing information
      * for a particular mailbox name.
      *
      * @param responses The list of responses.
      * @param name      The desired mailbox name.
      *
      * @return The IMAPListResponse information for the requested name.
      */
     protected IMAPListResponse findListResponse(List responses, String name) {
         for (int i = 0; i < responses.size(); i++) {
             IMAPListResponse response = (IMAPListResponse)responses.get(i);
             if (response.mailboxName.equals(name)) {
                 return response;
             }
         }
         return null;
     }
     
     
     /**
      * Protected class intended for subclass overrides.  For normal folders, 
      * the mailbox name is fullname.  For Namespace root folders, the mailbox
      * name is the prefix + separator.  
      * 
      * @return The string name to use as the mailbox name for exists() and issubscribed() 
      *         calls.
      */
     protected String getMailBoxName() {
         return fullname; 
     }
     
     /**
      * Handle an unsolicited response from the server.  Most unsolicited responses 
      * are replies to specific commands sent to the server.  The remainder must 
      * be handled by the Store or the Folder using the connection.  These are 
      * critical to handle, as events such as expunged messages will alter the 
      * sequence numbers of the live messages.  We need to keep things in sync.
      * 
      * @param response The UntaggedResponse to process.
      * 
      * @return true if we handled this response and no further handling is required.  false
      *         means this one wasn't one of ours.
      */
     public boolean handleResponse(IMAPUntaggedResponse response) {
         // "you've got mail".  The message count has been updated.  There 
         // are two posibilities.  Either there really are new messages, or 
         // this is an update following an expunge.  If there are new messages, 
         // we need to update the message cache and broadcast the change to 
         // any listeners.
         if (response.isKeyword("EXISTS")) {
             // we need to update our cache, and also retrieve the new messages and 
             // send them out in a broadcast update. 
             int oldCount = maxSequenceNumber; 
             maxSequenceNumber = ((IMAPSizeResponse)response).getSize(); 
             populateMessageCache();  
             // has the size grown?  We have to send the "you've got mail" announcement. 
             if (oldCount < maxSequenceNumber) {
                 try {
                     Message[] messages = getMessages(oldCount + 1, maxSequenceNumber); 
                     notifyMessageAddedListeners(messages); 
                 } catch (MessagingException e) {
                     // should never happen in this context 
                 }
             }
             return true; 
         }
         // "you had mail".  A message was expunged from the server.  This MUST 
         // be processed immediately, as any subsequent expunge messages will 
         // shift the message numbers as a result of previous messages getting 
         // removed.  We need to keep our internal cache in sync with the server. 
         else if (response.isKeyword("EXPUNGE")) {
             int messageNumber = ((IMAPSizeResponse)response).getSize(); 
             try {
                 Message message = expungeMessage(messageNumber); 
 
                 // broadcast the message update. 
                 notifyMessageRemovedListeners(false, new Message[] {message}); 
             } catch (MessagingException e) {
             }
             // we handled this one. 
             return true; 
         }
         // just an update of recently arrived stuff?  Just update the field. 
         else if (response.isKeyword("RECENT")) {
             recentMessages = ((IMAPSizeResponse)response).getSize();  
             return true; 
         }
         // The spec is not particularly clear what types of unsolicited 
         // FETCH response can be sent.  The only one that is specifically 
         // spelled out is flag updates.  If this is one of those, then 
         // handle it. 
         else if (response.isKeyword("FETCH")) {
             IMAPFetchResponse fetch = (IMAPFetchResponse)response;            
             IMAPFlags flags = (IMAPFlags)fetch.getDataItem(IMAPFetchDataItem.FLAGS); 
             // if this is a flags response, get the message and update 
             if (flags != null) {
                 try {
                     // get the updated message and update the internal state. 
                     IMAPMessage message = (IMAPMessage)getMessage(fetch.sequenceNumber); 
                     // this shouldn't happen, but it might have been expunged too. 
                     if (message != null) {
                         message.updateMessageInformation(fetch); 
                     }
                     notifyMessageChangedListeners(MessageChangedEvent.FLAGS_CHANGED, message);
                 } catch (MessagingException e) {
                 }
                 return true; 
             }
         }
         // this is a BYE response on our connection.  This forces us to close, but 
         // when we return the connection, the pool needs to get rid of it. 
         else if (response.isKeyword("BYE")) {
             // this is essentially a close event.  We need to clean everything up 
             // and make sure our connection is not returned to the general pool. 
             try {
                 cleanupFolder(false, true); 
             } catch (MessagingException e) {
             }
             return true; 
         }
         
         // not a response the folder knows how to deal with. 
         return false; 
     }
     
 // The following set of methods are extensions that exist in the Sun implementation.  They     
 // match the Sun version in intent, but are not 100% compatible because the Sun implementation     
 // uses com.sun.* class instances as opposed to the org.apache.geronimo.* classes.     
     
     
     
     /**
      *   Remove an entry from the access control list for this folder.
      * 
      * @param acl    The ACL element to remove.
      * 
      * @exception MessagingException
      */
     public synchronized void removeACL(ACL acl) throws MessagingException {
         // ask the store to kindly hook us up with a connection.
         IMAPConnection connection = getConnection(); 
 
         try {
             // the connection does the heavy lifting 
             connection.removeACLRights(fullname, acl); 
         } finally {
             releaseConnection(connection); 
         }
     }
     
     
     /**
      *   Add an entry to the access control list for this folder.
      * 
      * @param acl    The new ACL to add.
      */
     public synchronized void addACL(ACL acl) throws MessagingException {
         // ask the store to kindly hook us up with a connection.
         IMAPConnection connection = getConnection(); 
 
         try {
             // the connection does the heavy lifting 
             connection.setACLRights(fullname, acl); 
         } finally {
             releaseConnection(connection); 
         }
     }
     
     
     /**
      * Add Rights to a given ACL entry.
      * 
      * @param acl    The target ACL to update.
      * 
      * @exception MessagingException
      */
     public synchronized void addRights(ACL acl) throws MessagingException {
         // ask the store to kindly hook us up with a connection.
         IMAPConnection connection = getConnection(); 
 
         try {
             // the connection does the heavy lifting 
             connection.addACLRights(fullname, acl); 
         } finally {
             releaseConnection(connection); 
         }
     }
     
     
     /**
      * Remove ACL Rights from a folder.
      * 
      * @param acl    The ACL describing the Rights to remove.
      * 
      * @exception MessagingException
      */
     public synchronized void removeRights(ACL acl) throws MessagingException {
         // ask the store to kindly hook us up with a connection.
         IMAPConnection connection = getConnection(); 
 
         try {
             // the connection does the heavy lifting 
             connection.removeACLRights(fullname, acl); 
         } finally {
             releaseConnection(connection); 
         }
     }
     
     
     /**
      *   List the rights associated with a given name.
      * 
      * @param name   The user name for the Rights.
      * 
      * @return The set of Rights associated with the user name.
      * @exception MessagingException
      */
     public synchronized Rights[] listRights(String name) throws MessagingException {
         // ask the store to kindly hook us up with a connection.
         IMAPConnection connection = getConnection(); 
 
         try {
             // the connection does the heavy lifting 
             return connection.listACLRights(fullname, name); 
         } finally {
             releaseConnection(connection); 
         }
     }
     
     
     /**
      *   List the rights for the currently authenticated user.
      * 
      * @return The set of Rights for the current user.
      * @exception MessagingException
      */
     public synchronized Rights myRights() throws MessagingException {
         // ask the store to kindly hook us up with a connection.
         IMAPConnection connection = getConnection(); 
 
         try {
             // the connection does the heavy lifting 
             return connection.getMyRights(fullname); 
         } finally {
             releaseConnection(connection); 
         }
     }
     
     /**
      * Get the quota values assigned to the current folder.
      * 
      * @return The Quota information for the folder.
      * @exception MessagingException
      */
     public synchronized Quota[] getQuota() throws MessagingException {
         // ask the store to kindly hook us up with a connection.
         IMAPConnection connection = getConnection(); 
 
         try {
             // the connection does the heavy lifting 
             return connection.fetchQuotaRoot(fullname); 
         } finally {
             releaseConnection(connection); 
         }
     }
     
     /**
      * Set the quota value for a quota root
      * 
      * @param quota  The new quota information to set.
      * 
      * @exception MessagingException
      */
     public synchronized void setQuota(Quota quota) throws MessagingException {
         // ask the store to kindly hook us up with a connection.
         IMAPConnection connection = getConnection(); 
 
         try {
             // the connection does the heavy lifting 
             connection.setQuota(quota); 
         } finally {
             releaseConnection(connection); 
         }
     }
     
     /**
      * Get the set of attributes defined for the folder
      * as the set of capabilities returned when the folder 
      * was opened.
      * 
      * @return The set of attributes associated with the folder.
      * @exception MessagingException
      */
     public synchronized String[] getAttributes() throws MessagingException {
         // if we don't have the LIST command information for this folder yet, 
         // call exists() to force this to be updated so we can return. 
         if (listInfo == null) {
             // return a null reference if this is not valid. 
             if (!exists()) {
                 return null; 
             }
         }
         // return a copy of the attributes array. 
         return (String[])listInfo.attributes.clone(); 
     }
 }