Folders - JavaMail API - page 73

Like getNewMessageCount() , getUnreadMessageCount() can be invoked on either an
open or a closed folder. However, in the case of a closed folder, it may return -1 to indicate
that the real answer would be too expensive to obtain.
Getting Messages from Folders
The Folder class provides four methods for retrieving messages from open folders:
public abstract Message getMessage ( int messageNumber ) throws
IndexOutOfBoundsException , FolderNotFoundException ,
IllegalStateException , MessagingException
public Message [] getMessages () throws FolderNotFoundException ,
IllegalStateException , MessagingException
public Message [] getMessages ( int start , int end ) throws
IndexOutOfBoundsException , FolderNotFoundException ,
IllegalStateException , MessagingException
public Message [] getMessages ( int [] messageNumbers ) throws
IndexOutOfBoundsException , FolderNotFoundException ,
IllegalStateException , MessagingException
The getMessage() method returns the n th message in the folder. The first message in
the folder is number 1 (not 0). Message numbers may change when messages are ex‐
punged from the folder. An IndexOutOfBoundsException is thrown if you ask for mes‐
sage n and there are n - 1 or fewer messages in the folder.
The first getMessages() method returns an array of Message objects representing all
the messages in this folder. The second getMessages() method returns an array of
Message objects from the folder, beginning with start and finishing with end , inclusive.
The third getMessages() method returns an array containing only those messages
specifically identified by number in the messageNumbers array.
All four of these methods only create the Message objects and fill in the minimal number
of fields in those objects. The actual text and other content of the message is fetched
from the server when the Message 's methods that use those things are invoked. This
means, for example, that you can't get all the messages from the server, then get on an
airplane and work with them offline. There is, however, a fetch() method, which fills
in certain parts of the Message objects with actual data from the server:
public void fetch ( Message [] messages , FetchProfile fp )
throws IllegalStateException , MessagingException
The messages argument is an array containing the Message objects to be prefetched.
The FetchProfile argument specifies which headers in the messages to prefetch. How‐
ever, this is still just a suggestion. Implementations are free to ignore this request and
fetch the message content only when it's actually needed.
You can request prefetching of individual headers such as Subject: by name. You can
also request prefetching of three predefined blocks of information: the envelope