com.sun.mail.mbox
Class MboxFolder

java.lang.Object
  javax.mail.Folder
      com.sun.mail.mbox.MboxFolder

public class MboxFolder
extends javax.mail.Folder

This class represents a mailbox file containing RFC822 style email messages.

Field Summary

Fields inherited from class javax.mail.Folder

HOLDS_FOLDERS, HOLDS_MESSAGES, mode, READ_ONLY, READ_WRITE, store

Constructor Summary

MboxFolder(MboxStore store, java.lang.String name)

Method Summary

void	appendMessages(javax.mail.Message[] msgs) Append given Messages to this folder.
void	close(boolean expunge) Close this Folder.
boolean	create(int type) Create this folder on the Store.
protected javax.mail.Folder	createFolder(MboxStore store, java.lang.String name) Create an MboxFolder object, or a subclass thereof.
boolean	delete(boolean recurse) Delete this Folder.
boolean	exists() Tests if this folder physically exists on the Store.
javax.mail.Message[]	expunge() Expunge (permanently remove) messages marked DELETED.
javax.mail.Folder	getFolder(java.lang.String name) Return the Folder object corresponding to the given name.
java.lang.String	getFullName() Returns the full name of this Folder.
javax.mail.Message	getMessage(int msgno) Get the specified message.
int	getMessageCount() Get total number of messages in this Folder.
java.lang.String	getName() Returns the name of this Folder.
javax.mail.Folder	getParent() Returns the parent folder of this folder.
javax.mail.Flags	getPermanentFlags() Get the permanent flags supported by this Folder.
char	getSeparator() Return the delimiter character that separates this Folder's pathname from the names of immediate subfolders.
int	getType() Returns the type of this Folder, that is, whether this folder can hold messages or subfolders or both.
protected static java.lang.String	getUnixFrom(javax.mail.internet.MimeMessage msg) Construct an appropriately formatted UNIX From line using the sender address and the date in the message.
javax.mail.URLName	getURLName() this is an exact duplicate of the Folder.getURL except it doesn't add a beginning '/' to the URLName.
boolean	hasNewMessages() Returns true if this Folder has new messages since the last time this indication was reset.
boolean	isOpen() Indicates whether this Folder is in the 'open' state.
javax.mail.Folder[]	list(java.lang.String pattern) Returns a list of Folders belonging to this Folder's namespace that match the specified pattern.
protected javax.mail.Folder[]	list(java.lang.String ref, java.lang.String pattern, boolean fromStore)
protected void	notifyMessageChangedListeners(int type, javax.mail.Message m) Notify all MessageChangedListeners.
void	open(int mode) Open this Folder.
boolean	renameTo(javax.mail.Folder f) Rename this Folder.
protected int	writeFolder(boolean closing, boolean expunge) Re-write the folder with the current contents of the messages.
static void	writeMboxMessage(javax.mail.internet.MimeMessage msg, java.io.OutputStream os) Write a MimeMessage to the specified OutputStream in a format suitable for a UNIX mailbox, i.e., including a correct Content-Length header and with the local platform's line terminating convention.

Methods inherited from class javax.mail.Folder

addConnectionListener, addFolderListener, addMessageChangedListener, addMessageCountListener, copyMessages, fetch, finalize, getDeletedMessageCount, getMessages, getMessages, getMessages, getMode, getNewMessageCount, getStore, getUnreadMessageCount, isSubscribed, list, listSubscribed, listSubscribed, notifyConnectionListeners, notifyFolderListeners, notifyFolderRenamedListeners, notifyMessageAddedListeners, notifyMessageRemovedListeners, removeConnectionListener, removeFolderListener, removeMessageChangedListener, removeMessageCountListener, search, search, setFlags, setFlags, setFlags, setSubscribed, toString

Methods inherited from class java.lang.Object

clone, equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

MboxFolder

public MboxFolder(MboxStore store,
                  java.lang.String name)

Method Detail

getSeparator

public char getSeparator()

Description copied from class: javax.mail.Folder

Return the delimiter character that separates this Folder's pathname from the names of immediate subfolders. This method can be invoked on a closed Folder.

Specified by:

getSeparator in class javax.mail.Folder

Returns:

Hierarchy separator character

list

public javax.mail.Folder[] list(java.lang.String pattern)
                         throws javax.mail.MessagingException

Description copied from class: javax.mail.Folder

Returns a list of Folders belonging to this Folder's namespace that match the specified pattern. Patterns may contain the wildcard characters "%", which matches any character except hierarchy delimiters, and "*", which matches any character.

As an example, given the folder hierarchy:

    Personal/
       Finance/
          Stocks
          Bonus
          StockOptions
       Jokes
 

list("*") on "Personal" will return the whole hierarchy.
list("%") on "Personal" will return "Finance" and "Jokes".
list("Jokes") on "Personal" will return "Jokes".
list("Stock*") on "Finance" will return "Stocks" and "StockOptions".

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.

Specified by:

list in class javax.mail.Folder

Parameters:

pattern - the match pattern

Returns:

array of matching Folder objects. An empty array is returned if no matching Folders exist.

Throws:

javax.mail.MessagingException

See Also:

Folder.listSubscribed(java.lang.String)

list

protected javax.mail.Folder[] list(java.lang.String ref,
                                   java.lang.String pattern,
                                   boolean fromStore)
                            throws javax.mail.MessagingException

Throws:

javax.mail.MessagingException

getName

public java.lang.String getName()

Description copied from class: javax.mail.Folder

Returns the name of this Folder.

This method can be invoked on a closed Folder.

Specified by:

getName in class javax.mail.Folder

Returns:

name of the Folder

getFullName

public java.lang.String getFullName()

Description copied from class: javax.mail.Folder

Returns the full name of this Folder. If the folder resides under the root hierarchy of this Store, the returned name is relative to the root. Otherwise an absolute name, starting with the hierarchy delimiter, is returned.

This method can be invoked on a closed Folder.

Specified by:

getFullName in class javax.mail.Folder

Returns:

full name of the Folder

getParent

public javax.mail.Folder getParent()

Description copied from class: javax.mail.Folder

Returns the parent folder of this folder. This method can be invoked on a closed Folder. If this folder is the top of a folder hierarchy, this method returns null.

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

Specified by:

getParent in class javax.mail.Folder

Returns:

Parent folder

exists

public boolean exists()

Description copied from class: javax.mail.Folder

Tests if this folder physically exists on the Store. This method can be invoked on a closed Folder.

Specified by:

exists in class javax.mail.Folder

Returns:

true if the folder exists, otherwise false

See Also:

Folder.create(int)

getType

public int getType()

Description copied from class: javax.mail.Folder

Returns the type of this Folder, that is, whether this folder can hold messages or subfolders or both. The returned value is an integer bitfield with the appropriate bits set. This method can be invoked on a closed folder.

Specified by:

getType in class javax.mail.Folder

Returns:

integer with appropriate bits set

See Also:

Folder.HOLDS_FOLDERS, Folder.HOLDS_MESSAGES

getPermanentFlags

public javax.mail.Flags getPermanentFlags()

Description copied from class: javax.mail.Folder

Get the permanent flags supported by this Folder. Returns a Flags object that contains all the flags supported.

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.

Specified by:

getPermanentFlags in class javax.mail.Folder

Returns:

permanent flags, or null if not known

hasNewMessages

public boolean hasNewMessages()

Description copied from class: javax.mail.Folder

Returns true if this Folder has new messages since the last time this indication was reset. When this indication is set or reset depends on the Folder implementation (and in the case of IMAP, depends on the server). This method can be used to implement a lightweight "check for new mail" operation on a Folder without opening it. (For example, a thread that monitors a mailbox and flags when it has new mail.) This method should indicate whether any messages in the Folder have the RECENT flag set.

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.

Specified by:

hasNewMessages in class javax.mail.Folder

Returns:

true if the Store has new Messages

getFolder

public javax.mail.Folder getFolder(java.lang.String name)
                            throws javax.mail.MessagingException

Description copied from class: javax.mail.Folder

Return the Folder object corresponding to the given name. Note that this folder does not physically have to exist in the Store. The exists() method on a Folder indicates whether it really exists on the Store.

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.

Specified by:

getFolder in class javax.mail.Folder

Parameters:

name - name of the Folder

Returns:

Folder object

Throws:

javax.mail.MessagingException

create

public boolean create(int type)
               throws javax.mail.MessagingException

Description copied from class: javax.mail.Folder

Create this folder on the Store. When this folder is created, any folders in its path that do not exist are also created.

If the creation is successful, a CREATED FolderEvent is delivered to any FolderListeners registered on this Folder and this Store.

Specified by:

create in class javax.mail.Folder

Parameters:

type - The type of this folder.

Returns:

true if the creation succeeds, else false.

Throws:

javax.mail.MessagingException

See Also:

Folder.HOLDS_FOLDERS, Folder.HOLDS_MESSAGES, FolderEvent

delete

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

Description copied from class: javax.mail.Folder

Delete this Folder. This method will succeed only on a closed Folder.

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.

Specified by:

delete in class javax.mail.Folder

Returns:

true if the Folder is deleted successfully

Throws:

javax.mail.MessagingException

See Also:

FolderEvent

renameTo

public boolean renameTo(javax.mail.Folder f)
                 throws javax.mail.MessagingException

Description copied from class: javax.mail.Folder

Rename this Folder. This method will succeed only on a closed Folder.

If the rename is successful, a RENAMED FolderEvent is delivered to FolderListeners registered on this folder and its containing Store.

Specified by:

renameTo in class javax.mail.Folder

Parameters:

f - a folder representing the new name for this Folder

Returns:

true if the Folder is renamed successfully

Throws:

javax.mail.MessagingException

See Also:

FolderEvent

isOpen

public boolean isOpen()

Description copied from class: javax.mail.Folder

Indicates whether this Folder is in the 'open' state.

Specified by:

isOpen in class javax.mail.Folder

Returns:

true if this Folder is in the 'open' state.

open

public void open(int mode)
          throws javax.mail.MessagingException

Description copied from class: javax.mail.Folder

Open this Folder. This method is valid only on Folders that can contain Messages and that are closed.

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.

Specified by:

open in class javax.mail.Folder

Parameters:

mode - open the Folder READ_ONLY or READ_WRITE

Throws:

javax.mail.MessagingException

See Also:

Folder.READ_ONLY, Folder.READ_WRITE, Folder.getType(), ConnectionEvent

close

public void close(boolean expunge)
           throws javax.mail.MessagingException

Description copied from class: javax.mail.Folder

Close this Folder. This method is valid only on open Folders.

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.

Specified by:

close in class javax.mail.Folder

Parameters:

expunge - expunges all deleted messages if this flag is true

Throws:

javax.mail.MessagingException

See Also:

ConnectionEvent

writeFolder

protected int writeFolder(boolean closing,
                          boolean expunge)
                   throws java.io.IOException,
                          javax.mail.MessagingException

Re-write the folder with the current contents of the messages. If closing is true, turn off the RECENT flag. If expunge is true, don't write out deleted messages (only used from close() when the message cache won't be accessed again). Return the number of messages written.

Throws:

java.io.IOException

javax.mail.MessagingException

writeMboxMessage

public static void writeMboxMessage(javax.mail.internet.MimeMessage msg,
                                    java.io.OutputStream os)
                             throws java.io.IOException,
                                    javax.mail.MessagingException

Write a MimeMessage to the specified OutputStream in a format suitable for a UNIX mailbox, i.e., including a correct Content-Length header and with the local platform's line terminating convention.

If the message is really a MboxMessage, use its writeToFile method, which has access to the UNIX From line. Otherwise, do all the work here, creating an appropriate UNIX From line.

Throws:

java.io.IOException

javax.mail.MessagingException

getUnixFrom

protected static java.lang.String getUnixFrom(javax.mail.internet.MimeMessage msg)

Construct an appropriately formatted UNIX From line using the sender address and the date in the message.

getMessageCount

public int getMessageCount()
                    throws javax.mail.MessagingException

Description copied from class: javax.mail.Folder

Get total number of messages in this Folder.

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.

Specified by:

getMessageCount in class javax.mail.Folder

Returns:

total number of messages. -1 may be returned by certain implementations if this method is invoked on a closed folder.

Throws:

javax.mail.MessagingException

getMessage

public javax.mail.Message getMessage(int msgno)
                              throws javax.mail.MessagingException

Get the specified message. Note that messages are numbered from 1.

Specified by:

getMessage in class javax.mail.Folder

Parameters:

msgno - the message number

Returns:

the Message object

Throws:

javax.mail.MessagingException

See Also:

Folder.getMessageCount(), Folder.fetch(javax.mail.Message[], javax.mail.FetchProfile)

appendMessages

public void appendMessages(javax.mail.Message[] msgs)
                    throws javax.mail.MessagingException

Description copied from class: javax.mail.Folder

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.

Folder implementations must not abort this operation if a Message in the given message array turns out to be an expunged Message.

Specified by:

appendMessages in class javax.mail.Folder

Parameters:

msgs - array of Messages to be appended

Throws:

javax.mail.MessagingException - if the append failed.

expunge

public javax.mail.Message[] expunge()
                             throws javax.mail.MessagingException

Description copied from class: javax.mail.Folder

Expunge (permanently remove) messages marked DELETED. Returns an array containing the expunged message objects. The getMessageNumber method on each of these message objects returns that Message's original (that is, prior to the expunge) sequence number. A MessageCountEvent containing the expunged messages is delivered to any MessageCountListeners registered on the 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

Specified by:

expunge in class javax.mail.Folder

Returns:

array of expunged Message objects

Throws:

javax.mail.MessagingException

See Also:

Message.isExpunged(), MessageCountEvent

notifyMessageChangedListeners

protected void notifyMessageChangedListeners(int type,
                                             javax.mail.Message m)

Description copied from class: javax.mail.Folder

Notify all MessageChangedListeners. Folder implementations are expected to use this method to broadcast MessageChanged events.

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.

Overrides:

notifyMessageChangedListeners in class javax.mail.Folder

getURLName

public javax.mail.URLName getURLName()

this is an exact duplicate of the Folder.getURL except it doesn't add a beginning '/' to the URLName.

Overrides:

getURLName in class javax.mail.Folder

Returns:

the URLName representing this folder

See Also:

URLName

createFolder

protected javax.mail.Folder createFolder(MboxStore store,
                                         java.lang.String name)

Create an MboxFolder object, or a subclass thereof. Can be overridden by subclasses of MboxFolder so that the appropriate subclass is created by the list method.