Java Doc for Folder.java in  » EJB-Server-GlassFish » mail » javax » mail » Java Source Code / Java DocumentationJava Source Code and Java Documentation

Folders can contain Messages, other Folders or both, thus providing a tree-like hierarchy rooted at the Store's default folder. (Note that some Folder implementations may not allow both Messages and other Folders in the same Folder).

The interpretation of folder names is implementation dependent. The different levels of hierarchy in a folder's full name are separated from each other by the hierarchy delimiter character.

The case-insensitive full folder name (that is, the full name relative to the default folder for a Store) INBOX is reserved to mean the "primary folder for this user on this server". Not all Stores will provide an INBOX folder, and not all users will have an INBOX folder at all times. The name INBOX is reserved to refer to this folder, when it exists, in Stores that provide it.

A Folder object obtained from a Store need not actually exist in the backend store. The exists method tests whether the folder exists or not. The create method creates a Folder.

A Folder is initially in the closed state. Certain methods are valid in this state; the documentation for those methods note this. A Folder is opened by calling its 'open' method. All Folder methods, except open, delete and renameTo, are valid in this state.

The only way to get a Folder is by invoking the getFolder method on Store, Folder, or Session, or by invoking the list or listSubscribed methods on Folder. Folder objects returned by the above methods are not cached by the Store. Thus, invoking the getFolder method with the same folder name multiple times will return distinct Folder objects. Likewise for the list and listSubscribed methods.

The Message objects within the Folder are cached by the Folder. Thus, invoking getMessage(msgno) on the same message number multiple times will return the same Message object, until an expunge is done on this Folder.

Note that a Message's message number can change within a session if the containing Folder is expunged using the expunge method. Clients that use message numbers as references to messages should be aware of this and should be prepared to deal with situation (probably by flushing out existing message number references and reloading them). Because of this complexity, it is better for clients to use Message objects as references to messages, rather than message numbers. Expunged Message objects still have to be pruned, but other Message objects in that folder are not affected by the expunge.
author:
   John Mani
author:
   Bill Shannon

The implementation provided here adds this listener to an internal list of ConnectionListeners.
Parameters:
  l - the Listener for Connection events
See Also:   javax.mail.event.ConnectionEvent

The implementation provided here adds this listener to an internal list of FolderListeners.
Parameters:
  l - the Listener for Folder events
See Also:   javax.mail.event.FolderEvent

The implementation provided here adds this listener to an internal list of MessageChangedListeners.
Parameters:
  l - the Listener for MessageChanged events
See Also:   javax.mail.event.MessageChangedEvent

The implementation provided here adds this listener to an internal list of MessageCountListeners.
Parameters:
  l - the Listener for MessageCount events
See Also:   javax.mail.event.MessageCountEvent

Folder implementations must not abort this operation if a Message in the given message array turns out to be an expunged Message.
Parameters:
  msgs - array of Messages to be appended
exception:
  FolderNotFoundException - if this folder does not exist.
exception:
  MessagingException - if the append failed.

A CLOSED ConnectionEvent is delivered to any ConnectionListeners registered on this Folder. Note that the folder is closed even if this method terminates abnormally by throwing a MessagingException.
Parameters:
  expunge - expunges all deleted messages if this flag is true
exception:
  IllegalStateException - if this folder is not opened
exception:
  MessagingException -
See Also:   javax.mail.event.ConnectionEvent

Note that the specified Message objects must belong to this folder. Folder implementations might be able to optimize this method by doing server-side copies.

This implementation just invokes appendMessages() on the destination folder to append the given Messages. Specific folder implementations that support server-side copies should do so, if the destination folder's Store is the same as this folder's Store. Also, an implementation must not abort the operation if a Message in the array turns out to be an expunged Message.
Parameters:
  msgs - the array of message objects
Parameters:
  folder - the folder to copy the messages to
exception:
  FolderNotFoundException - if the destinationfolder does not exist.
exception:
  IllegalStateException - if this folder is not opened.
exception:
  MessagingException -
See Also:   Folder.appendMessages

If the creation is successful, a CREATED FolderEvent is delivered to any FolderListeners registered on this Folder and this Store.
Parameters:
  type - The type of this folder. true if the creation succeeds, else false.
exception:
  MessagingException -
See Also:   Folder.HOLDS_FOLDERS
See Also:   Folder.HOLDS_MESSAGES
See Also:   javax.mail.event.FolderEvent

The recurse flag controls whether the deletion affects subfolders or not. If true, all subfolders are deleted, then this folder itself is deleted. If false, the behaviour is dependent on the folder type and is elaborated below:

• The folder can contain only messages: (type == HOLDS_MESSAGES).
  All messages within the folder are removed. The folder itself is then removed. An appropriate FolderEvent is generated by the Store and this folder.

• The folder can contain only subfolders: (type == HOLDS_FOLDERS).
  If this folder is empty (does not contain any subfolders at all), it is removed. An appropriate FolderEvent is generated by the Store and this folder.
  If this folder contains any subfolders, the delete fails and returns false.

• The folder can contain subfolders as well as messages:
  If the folder is empty (no messages or subfolders), it is removed. If the folder contains no subfolders, but only messages, then all messages are removed. The folder itself is then removed. In both the above cases, an appropriate FolderEvent is generated by the Store and this folder.

  If the folder contains subfolders there are 3 possible choices an implementation is free to do:

  1. The operation fails, irrespective of whether this folder contains messages or not. Some implementations might elect to go with this simple approach. The delete() method returns false.
  2. Any messages within the folder are removed. Subfolders are not removed. The folder itself is not removed or affected in any manner. The delete() method returns true. And the exists() method on this folder will return true indicating that this folder still exists.
     An appropriate FolderEvent is generated by the Store and this folder.
  3. Any messages within the folder are removed. Subfolders are not removed. The folder itself changes its type from HOLDS_FOLDERS | HOLDS_MESSAGES to HOLDS_FOLDERS. Thus new messages cannot be added to this folder, but new subfolders can be created underneath. The delete() method returns true indicating success. The exists() method on this folder will return true indicating that this folder still exists.
     An appropriate FolderEvent is generated by the Store and this folder.

Expunge causes the renumbering of Message objects subsequent to the expunged messages. Clients that use message numbers as references to messages should be aware of this and should be prepared to deal with the situation (probably by flushing out existing message number caches and reloading them). Because of this complexity, it is better for clients to use Message objects as references to messages, rather than message numbers. Any expunged Messages objects still have to be pruned, but other Messages in that folder are not affected by the expunge.

After a message is expunged, only the isExpunged and getMessageNumber methods are still valid on the corresponding Message object; other methods may throw MessageRemovedException array of expunged Message objects
exception:
  FolderNotFoundException - if this folder does notexist
exception:
  IllegalStateException - if this folder is not opened.
exception:
  MessagingException -
See Also:   Message.isExpunged
See Also:   javax.mail.event.MessageCountEvent

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.

An example is a client filling its header-view window with the Subject, From and X-mailer headers for all messages in the folder.

 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"));
 }
 

The implementation provided here just returns without doing anything useful. Providers wanting to provide a real implementation for this method should override this method.
Parameters:
  msgs - fetch items for these messages
Parameters:
  fp - the FetchProfile
exception:
  IllegalStateException - if this folder is not opened MessagingException.

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.

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.

This implementation returns -1 if this folder is closed. Else this implementation gets each Message in the folder using getMessage(int) and checks whether its DELETED flag is set. The total number of messages that have this flag set is returned. number of deleted messages. -1 may be returnedby certain implementations if this method isinvoked on a closed folder.
exception:
  FolderNotFoundException - if this folder does not exist.
exception:
  MessagingException -
since:
   JavaMail 1.3

In some Stores, name can be an absolute path if it starts with the hierarchy delimiter. Otherwise, it is interpreted relative to this Folder.

Folder objects are not cached by the Store, so invoking this method on the same name multiple times will return that many distinct Folder objects.

This method can be invoked on a closed Folder.
Parameters:
  name - name of the Folder Folder object
exception:
  MessagingException -

This method can be invoked on a closed Folder. full name of the Folder

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.

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.

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.
Parameters:
  msgnum - the message number the Message object
See Also:   Folder.getMessageCount
See Also:   Folder.fetch
exception:
  FolderNotFoundException - if this folder does not exist.
exception:
  IllegalStateException - if this folder is not opened
exception:
  IndexOutOfBoundsException - if the message numberis out of range.
exception:
  MessagingException -

This method can be invoked on a closed folder. However, note that for some folder implementations, getting the total 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.

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. total number of messages. -1 may be returnedby certain implementations if this method isinvoked on a closed folder.
exception:
  FolderNotFoundException - if this folder does not exist.
exception:
  MessagingException -

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.

This implementation uses getMessage(index) to obtain the required Message objects. Note that the returned array must contain (end-start+1) Message objects.
Parameters:
  start - the number of the first message
Parameters:
  end - the number of the last message the Message objects
See Also:   Folder.fetch
exception:
  FolderNotFoundException - if this folder does not exist.
exception:
  IllegalStateException - if this folder is not opened.
exception:
  IndexOutOfBoundsException - if the start or endmessage numbers are out of range.
exception:
  MessagingException -

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.

This implementation uses getMessage(index) to obtain the required Message objects. Note that the returned array must contain msgnums.length Message objects
Parameters:
  msgnums - the array of message numbers the array of Message objects.
See Also:   Folder.fetch
exception:
  FolderNotFoundException - if this folder does not exist.
exception:
  IllegalStateException - if this folder is not opened.
exception:
  IndexOutOfBoundsException - if any message numberin the given array is out of range.
exception:
  MessagingException -

This implementation invokes getMessageCount() to get the current message count and then uses getMessage() to get Message objects from 1 till the message count. array of Message objects, empty array if folderis empty.
See Also:   Folder.fetch
exception:
  FolderNotFoundException - if this folder does not exist.
exception:
  IllegalStateException - if this folder is not opened.
exception:
  MessagingException -

This method can be invoked on a closed Folder. name of the Folder

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.

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.

This implementation returns -1 if this folder is closed. Else this implementation gets each Message in the folder using getMessage(int) and checks whether its RECENT flag is set. The total number of messages that have this flag set is returned. number of new messages. -1 may be returnedby certain implementations if this method isinvoked on a closed folder.
exception:
  FolderNotFoundException - if this folder does not exist.
exception:
  MessagingException -

Note that since Folder objects are not cached, invoking this method returns a new distinct Folder object. Parent folder

The special flag Flags.USER indicates that this Folder supports arbitrary user-defined flags.

The supported permanent flags for a folder may not be available until the folder is opened. permanent flags, or null if not known

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.

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.

This implementation returns -1 if this folder is closed. Else this implementation gets each Message in the folder using getMessage(int) and checks whether its SEEN flag is set. The total number of messages that do not have this flag set is returned. total number of unread messages. -1 may be returnedby certain implementations if this method isinvoked on a closed folder.
exception:
  FolderNotFoundException - if this folder does not exist.
exception:
  MessagingException -

Note that this is not an incremental check for new mail, i.e., it cannot be used to determine whether any new messages have arrived since the last time this method was invoked. To implement incremental checks, the Folder needs to be opened.

This method can be invoked on a closed Folder that can contain Messages. true if the Store has new Messages
exception:
  FolderNotFoundException - if this folder doesnot exist.
exception:
  MessagingException -

This method can be invoked on a closed Folder.

The default implementation provided here just returns true. true if this Folder is subscribed

As an example, given the folder hierarchy:

 Personal/
 Finance/
 Stocks
 Bonus
 StockOptions
 Jokes
 

Folder objects are not cached by the Store, so invoking this method on the same pattern multiple times will return that many distinct Folder objects.

This method can be invoked on a closed Folder.
Parameters:
  pattern - the match pattern array of matching Folder objects. An emptyarray is returned if no matching Folders exist.
See Also:   Folder.listSubscribed
exception:
  FolderNotFoundException - if this folder does not exist.
exception:
  MessagingException -

Note that, at a given level of the folder hierarchy, a particular folder may not be subscribed, but folders underneath that folder in the folder hierarchy may be subscribed. In order to allow walking the folder hierarchy, such unsubscribed folders may be returned, indicating that a folder lower in the hierarchy is subscribed. The isSubscribed method on a folder will tell whether any particular folder is actually subscribed.

Folder objects are not cached by the Store, so invoking this method on the same pattern multiple times will return that many distinct Folder objects.

This method can be invoked on a closed Folder.
Parameters:
  pattern - the match pattern array of matching subscribed Folder objects. Anempty array is returned if no matchingsubscribed folders exist.
See Also:   Folder.list
exception:
  FolderNotFoundException - if this folder doesnot exist.
exception:
  MessagingException -

The provided implementation queues the event into an internal event queue. An event dispatcher thread dequeues events from the queue and dispatches them to the registered ConnectionListeners. Note that the event dispatching occurs in a separate thread, thus avoiding potential deadlock problems.
Parameters:
  type - the ConnectionEvent type
See Also:   javax.mail.event.ConnectionEvent

The implementation provided here queues the event into an internal event queue. An event dispatcher thread dequeues events from the queue and dispatches them to the FolderListeners registered on this folder. The implementation also invokes notifyFolderListeners on this folder's Store to notify any FolderListeners registered on the store.
Parameters:
  type - type of FolderEvent
See Also:   Folder.notifyFolderRenamedListeners

The implementation provided here queues the event into an internal event queue. An event dispatcher thread dequeues events from the queue and dispatches them to the FolderListeners registered on this folder. The implementation also invokes notifyFolderRenamedListeners on this folder's Store to notify any FolderListeners registered on the store.
Parameters:
  folder - Folder representing the new name.
See Also:   Folder.notifyFolderListeners
since:
   JavaMail 1.1

The provided implementation queues the event into an internal event queue. An event dispatcher thread dequeues events from the queue and dispatches them to the registered MessageCountListeners. Note that the event dispatching occurs in a separate thread, thus avoiding potential deadlock problems.

The provided implementation queues the event into an internal event queue. An event dispatcher thread dequeues events from the queue and dispatches them to registered MessageChangedListeners. Note that the event dispatching occurs in a separate thread, thus avoiding potential deadlock problems.

The provided implementation queues the event into an internal event queue. An event dispatcher thread dequeues events from the queue and dispatches them to the registered MessageCountListeners. Note that the event dispatching occurs in a separate thread, thus avoiding potential deadlock problems.

If this folder is opened successfully, an OPENED ConnectionEvent is delivered to any ConnectionListeners registered on this Folder.

The effect of opening multiple connections to the same folder on a specifc Store is implementation dependent. Some implementations allow multiple readers, but only one writer. Others allow multiple writers as well as readers.
Parameters:
  mode - open the Folder READ_ONLY or READ_WRITE
exception:
  FolderNotFoundException - if this folder does not exist.
exception:
  IllegalStateException - if this folder is not in the closed state.
exception:
  MessagingException -
See Also:   Folder.READ_ONLY
See Also:   Folder.READ_WRITE
See Also:   Folder.getType()
See Also:   javax.mail.event.ConnectionEvent

The implementation provided here removes this listener from the internal list of ConnectionListeners.
Parameters:
  l - the listener
See Also:   Folder.addConnectionListener

The implementation provided here removes this listener from the internal list of FolderListeners.
Parameters:
  l - the listener
See Also:   Folder.addFolderListener

The implementation provided here removes this listener from the internal list of MessageChangedListeners.
Parameters:
  l - the listener
See Also:   Folder.addMessageChangedListener

The implementation provided here removes this listener from the internal list of MessageCountListeners.
Parameters:
  l - the listener
See Also:   Folder.addMessageCountListener

If the rename is successful, a RENAMED FolderEvent is delivered to FolderListeners registered on this folder and its containing Store.
Parameters:
  f - a folder representing the new name for this Folder true if the Folder is renamed successfully
exception:
  FolderNotFoundException - if this folder does not exist
exception:
  IllegalStateException - if this folder is not in the closed state.
exception:
  MessagingException -
See Also:   javax.mail.event.FolderEvent

This implementation invokes search(term, getMessages()), to apply the search over all the messages in this folder. Providers that can implement server-side searching might want to override this method to provide a more efficient implementation.
Parameters:
  term - the search criterion array of matching messages
exception:
  javax.mail.search.SearchException - if the search term is too complex for the implementation to handle.
exception:
  FolderNotFoundException - if this folder does not exist.
exception:
  IllegalStateException - if this folder is not opened.
exception:
  MessagingException -
See Also:   javax.mail.search.SearchTerm

Note that the specified Message objects must belong to this folder.

This implementation iterates through the given array of messages, and applies the search criterion on each message by calling its match() method with the given term. The messages that succeed in the match are returned. Providers that can implement server-side searching might want to override this method to provide a more efficient implementation. If the search term is too complex or contains user-defined terms that cannot be executed on the server, providers may elect to either throw a SearchException or degenerate to client-side searching by calling super.search() to invoke this implementation.
Parameters:
  term - the search criterion
Parameters:
  msgs - the messages to be searched array of matching messages
exception:
  javax.mail.search.SearchException - if the search term is too complex for the implementation to handle.
exception:
  IllegalStateException - if this folder is not opened
exception:
  MessagingException -
See Also:   javax.mail.search.SearchTerm

Note that the specified Message objects must belong to this folder. Certain Folder implementations can optimize the operation of setting Flags for a group of messages, so clients might want to use this method, rather than invoking Message.setFlags for each Message.

This implementation degenerates to invoking setFlags() on each Message object. Specific Folder implementations that can optimize this case should do so. Also, an implementation must not abort the operation if a Message in the array turns out to be an expunged Message.
Parameters:
  msgs - the array of message objects
Parameters:
  flag - Flags object containing the flags to be set
Parameters:
  value - set the flags to this boolean value
exception:
  IllegalStateException - if this folder is not openedor if it has been opened READ_ONLY.
exception:
  MessagingException -
See Also:   Message.setFlags
See Also:   javax.mail.event.MessageChangedEvent

Certain Folder implementations can optimize the operation of setting Flags for a group of messages, so clients might want to use this method, rather than invoking Message.setFlags for each Message.

The default implementation uses getMessage(int) to get each Message object and then invokes setFlags on that object to set the flags. Specific Folder implementations that can optimize this case should do so. Also, an implementation must not abort the operation if a message number refers to an expunged message.
Parameters:
  start - the number of the first message
Parameters:
  end - the number of the last message
Parameters:
  flag - Flags object containing the flags to be set
Parameters:
  value - set the flags to this boolean value
exception:
  IllegalStateException - if this folder is not openedor if it has been opened READ_ONLY.
exception:
  IndexOutOfBoundsException - if the start or endmessage numbers are out of range.
exception:
  MessagingException -
See Also:   Message.setFlags
See Also:   javax.mail.event.MessageChangedEvent

Certain Folder implementations can optimize the operation of setting Flags for a group of messages, so clients might want to use this method, rather than invoking Message.setFlags for each Message.

The default implementation uses getMessage(int) to get each Message object and then invokes setFlags on that object to set the flags. Specific Folder implementations that can optimize this case should do so. Also, an implementation must not abort the operation if a message number refers to an expunged message.
Parameters:
  msgnums - the array of message numbers
Parameters:
  flag - Flags object containing the flags to be set
Parameters:
  value - set the flags to this boolean value
exception:
  IllegalStateException - if this folder is not openedor if it has been opened READ_ONLY.
exception:
  IndexOutOfBoundsException - if any message numberin the given array is out of range.
exception:
  MessagingException -
See Also:   Message.setFlags
See Also:   javax.mail.event.MessageChangedEvent

This method can be invoked on a closed Folder.

The implementation provided here just throws the MethodNotSupportedException.
Parameters:
  subscribe - true to subscribe, false to unsubscribe
exception:
  FolderNotFoundException - if this folder doesnot exist.
exception:
  MethodNotSupportedException - if this storedoes not support subscription
exception:
  MessagingException -