folder.java

java Email you can use it to send email to others

     * Clients invoking this method on a closed folder must be aware
     * that this is a potentially expensive operation. Clients must
     * also be prepared to handle a return value of -1 in this case.
     * 
     * @return 		total number of messages. -1 may be returned
     *			by certain implementations if this method is
     *			invoked on a closed folder.
     * @exception	FolderNotFoundException if this folder does 
     *			not exist.
     * @exception       MessagingException
     */
    public abstract int getMessageCount() throws MessagingException;

    /**
     * Get the number of new messages in this Folder. <p>
     *
     * This method can be invoked on a closed folder. However, note
     * that for some folder implementations, getting the new message
     * count can be an expensive operation involving actually opening 
     * the folder. In such cases, a provider can choose not to support 
     * this functionality in the closed state, in which case this method
     * must return -1. <p>
     *
     * Clients invoking this method on a closed folder must be aware
     * that this is a potentially expensive operation. Clients must
     * also be prepared to handle a return value of -1 in this case. <p>
     *
     * This implementation returns -1 if this folder is closed. Else
     * this implementation gets each Message in the folder using
     * <code>getMessage(int)</code> and checks whether its
     * <code>RECENT</code> flag is set. The total number of messages
     * that have this flag set is returned.
     *
     * @return 		number of new messages. -1 may be returned
     *			by certain implementations if this method is
     *			invoked on a closed folder.
     * @exception	FolderNotFoundException if this folder does 
     *			not exist.
     * @exception       MessagingException
     */
    public synchronized int getNewMessageCount() 
			throws MessagingException {
	if (!isOpen())
	    return -1;

	int newmsgs = 0;
	int total = getMessageCount();
	for (int i = 1; i <= total; i++) {
	    try {
		if (getMessage(i).isSet(Flags.Flag.RECENT))
		    newmsgs++;
	    } catch (MessageRemovedException me) {
		// This is an expunged message, ignore it.
		continue;
	    }
	}
	return newmsgs;
    }

    /**
     * Get the total number of unread messages in this Folder. <p>
     *
     * This method can be invoked on a closed folder. However, note
     * that for some folder implementations, getting the unread message
     * count can be an expensive operation involving actually opening 
     * the folder. In such cases, a provider can choose not to support 
     * this functionality in the closed state, in which case this method
     * must return -1. <p>
     *
     * Clients invoking this method on a closed folder must be aware
     * that this is a potentially expensive operation. Clients must
     * also be prepared to handle a return value of -1 in this case. <p>
     *
     * This implementation returns -1 if this folder is closed. Else
     * this implementation gets each Message in the folder using
     * <code>getMessage(int)</code> and checks whether its
     * <code>SEEN</code> flag is set. The total number of messages
     * that do not have this flag set is returned.
     *
     * @return 		total number of unread messages. -1 may be returned
     *			by certain implementations if this method is
     *			invoked on a closed folder.
     * @exception	FolderNotFoundException if this folder does 
     *			not exist.
     * @exception       MessagingException
     */
    public synchronized int getUnreadMessageCount() 
			throws MessagingException {
	if (!isOpen())
	    return -1;

	int unread = 0;
	int total = getMessageCount();
	for (int i = 1; i <= total; i++) {
	    try {
		if (!getMessage(i).isSet(Flags.Flag.SEEN))
		    unread++;
	    } catch (MessageRemovedException me) {
		// This is an expunged message, ignore it.
		continue;
	    }
	}
	return unread;
    }

    /**
     * Get the number of deleted messages in this Folder. <p>
     *
     * This method can be invoked on a closed folder. However, note
     * that for some folder implementations, getting the deleted message
     * count can be an expensive operation involving actually opening 
     * the folder. In such cases, a provider can choose not to support 
     * this functionality in the closed state, in which case this method
     * must return -1. <p>
     *
     * Clients invoking this method on a closed folder must be aware
     * that this is a potentially expensive operation. Clients must
     * also be prepared to handle a return value of -1 in this case. <p>
     *
     * This implementation returns -1 if this folder is closed. Else
     * this implementation gets each Message in the folder using
     * <code>getMessage(int)</code> and checks whether its
     * <code>DELETED</code> flag is set. The total number of messages
     * that have this flag set is returned.
     *
     * @return 		number of deleted messages. -1 may be returned
     *			by certain implementations if this method is
     *			invoked on a closed folder.
     * @exception	FolderNotFoundException if this folder does 
     *			not exist.
     * @exception       MessagingException
     * @since		JavaMail 1.3
     */
    public synchronized int getDeletedMessageCount() throws MessagingException {
	if (!isOpen())
	    return -1;

	int deleted = 0;
	int total = getMessageCount();
	for (int i = 1; i <= total; i++) {
	    try {
		if (getMessage(i).isSet(Flags.Flag.DELETED))
		    deleted++;
	    } catch (MessageRemovedException me) {
		// This is an expunged message, ignore it.
		continue;
	    }
	}
	return deleted;
    }

    /**
     * Get the Message object corresponding to the given message
     * number.  A Message object's message number is the relative
     * position of this Message in its Folder. Messages are numbered
     * starting at 1 through the total number of message in the folder.
     * Note that the message number for a particular Message can change
     * during a session if other messages in the Folder are deleted and
     * the Folder is expunged. <p>
     *
     * Message objects are light-weight references to the actual message
     * that get filled up on demand. Hence Folder implementations are 
     * expected to provide light-weight Message objects. <p>
     *
     * Unlike Folder objects, repeated calls to getMessage with the
     * same message number will return the same Message object, as
     * long as no messages in this folder have been expunged. <p>
     *
     * Since message numbers can change within a session if the folder
     * is expunged , clients are advised not to use message numbers as 
     * references to messages. Use Message objects instead.
     *
     * @param msgnum	the message number
     * @return 		the Message object
     * @see		#getMessageCount
     * @see		#fetch
     * @exception	FolderNotFoundException if this folder does 
     *			not exist.
     * @exception	IllegalStateException if this folder is not opened
     * @exception	IndexOutOfBoundsException if the message number
     *			is out of range.
     * @exception 	MessagingException
     */
    public abstract Message getMessage(int msgnum)
				throws MessagingException;

    /**
     * Get the Message objects for message numbers ranging from start
     * through end, both start and end inclusive. Note that message 
     * numbers start at 1, not 0. <p>
     *
     * Message objects are light-weight references to the actual message
     * that get filled up on demand. Hence Folder implementations are 
     * expected to provide light-weight Message objects. <p>
     *
     * This implementation uses getMessage(index) to obtain the required
     * Message objects. Note that the returned array must contain 
     * <code>(end-start+1)</code> Message objects.
     * 
     * @param start	the number of the first message
     * @param end	the number of the last message
     * @return 		the Message objects
     * @see		#fetch
     * @exception	FolderNotFoundException if this folder does 
     *			not exist.
     * @exception	IllegalStateException if this folder is not opened.
     * @exception	IndexOutOfBoundsException if the start or end
     *			message numbers are out of range.
     * @exception 	MessagingException
     */ 
    public synchronized Message[] getMessages(int start, int end) 
			throws MessagingException {
	Message[] msgs = new Message[end - start +1];
	for (int i = start; i <= end; i++)
	    msgs[i - start] = getMessage(i);
	return msgs;
    }

    /**
     * Get the Message objects for message numbers specified in
     * the array. <p>
     *
     * Message objects are light-weight references to the actual message
     * that get filled up on demand. Hence Folder implementations are 
     * expected to provide light-weight Message objects. <p>
     *
     * This implementation uses getMessage(index) to obtain the required
     * Message objects. Note that the returned array must contain 
     * <code>msgnums.length</code> Message objects
     *
     * @param msgnums	the array of message numbers
     * @return 		the array of Message objects. 
     * @see		#fetch
     * @exception	FolderNotFoundException if this folder does 
     *			not exist.
     * @exception	IllegalStateException if this folder is not opened.
     * @exception	IndexOutOfBoundsException if any message number
     *			in the given array is out of range.
     * @exception 	MessagingException
     */ 
    public synchronized Message[] getMessages(int[] msgnums)
			throws MessagingException {
	int len = msgnums.length;
	Message[] msgs = new Message[len];
	for (int i = 0; i < len; i++)
	    msgs[i] = getMessage(msgnums[i]);
	return msgs;
    }

    /**
     * Get all Message objects from this Folder. Returns an empty array
     * if the folder is empty.
     *
     * Clients can use Message objects (instead of sequence numbers) 
     * as references to the messages within a folder; this method supplies 
     * the Message objects to the client. Folder implementations are 
     * expected to provide light-weight Message objects, which get
     * filled on demand. <p>
     *
     * This implementation invokes <code>getMessageCount()</code> to get
     * the current message count and then uses <code>getMessage()</code>
     * to get Message objects from 1 till the message count.
     *
     * @return 		array of Message objects, empty array if folder
     *			is empty.
     * @see		#fetch
     * @exception	FolderNotFoundException if this folder does 
     *			not exist.
     * @exception	IllegalStateException if this folder is not opened.
     * @exception 	MessagingException
     */ 
    public synchronized Message[] getMessages() throws MessagingException {
	if (!isOpen())	// otherwise getMessageCount might return -1
	    throw new IllegalStateException("Folder not open");
	int total = getMessageCount();
	Message[] msgs = new Message[total];
	for (int i = 1; i <= total; i++)
	    msgs[i-1] = getMessage(i);	
	return msgs;
    }

    /**
     * Append given Messages to this folder. This method can be 
     * invoked on a closed Folder. An appropriate MessageCountEvent 
     * is delivered to any MessageCountListener registered on this 
     * folder when the messages arrive in the folder. <p>
     *
     * Folder implementations must not abort this operation if a
     * Message in the given message array turns out to be an
     * expunged Message.
     *
     * @param msgs	array of Messages to be appended
     * @exception	FolderNotFoundException if this folder does 
     *			not exist.
     * @exception 	MessagingException if the append failed.
     */
    public abstract void appendMessages(Message[] msgs)
				throws MessagingException;

    /**
     * Prefetch the items specified in the FetchProfile for the
     * given Messages. <p>
     *
     * Clients use this method to indicate that the specified items are 
     * needed en-masse for the given message range. Implementations are 
     * expected to retrieve these items for the given message range in
     * a efficient manner. Note that this method is just a hint to the
     * implementation to prefetch the desired items. <p>
     *
     * An example is a client filling its header-view window with
     * the Subject, From and X-mailer headers for all messages in the 
     * folder.<p>
     * <blockquote><pre>
     *
     *  Message[] msgs = folder.getMessages();
     *
     *  FetchProfile fp = new FetchProfile();
     *  fp.add(FetchProfile.Item.ENVELOPE);
     *  fp.add("X-mailer");
     *  folder.fetch(msgs, fp);
     *  
     *  for (int i = 0; i < folder.getMessageCount(); i++) {
     *      display(msg[i].getFrom());
     *      display(msg[i].getSubject());
     *      display(msg[i].getHeader("X-mailer"));
     *  }
     *
     * </pre></blockquote><p>
     *
     * The implementation provided here just returns without
     * doing anything useful. Providers wanting to provide a real 
     * implementation for this method should override this method.