com.funambol.mail
Class Folder

java.lang.Object
  extended by com.funambol.mail.Folder

public class Folder
extends java.lang.Object

Represents a mailbox folder on the device. Folders can contain Message objects, other Folder objects or both. This nesting capability enables a folder hierarchy for stored messages. The different levels of hierarchy in a folder's full name are separated by the hierarchy separator character, which you can retrieve using getSeparator(). You can retrieve a contained folder by name using getFolder(), or a list of contained folders by using list()


Constructor Summary
Folder(java.lang.String fullname, Store store)
          Constructs a new Folder providing a name for it and a reference to the Store in which it has to be created
 
Method Summary
 void appendMessage(Message msg)
          Appends the given Message to this Folder
 void deleteMessage(int index)
          Deletes a Message from this Folder, using a positional index as key.
 void deleteMessage(Message msg)
          Deletes a Message from this Folder The message is properly updated so that it is both complete (completely loaded in memory) and its parent folder is cleared.
 void deleteMessage(java.lang.String recordId)
          Deletes a Message from this Folder, using the record id as key.
 Message getFirstMessage()
          Get the first message in the folder.
 Folder getFolder(java.lang.String name)
          Returns the requested subfolder
 java.lang.String getFullName()
          Returns the full name of this Folder as passed in the constructor
 Message getMessage(java.lang.String recordId)
          Gets the Message object corresponding to the given record ID
 int getMessageCount()
          Get the total number of messages in this Folder
 int getMessageWithFlagCount(int flag, boolean set)
          Returns the total number of messages in this Folder with the specified flag enabled or disabled
 Message[] getMsgHeaders()
          This method returns the headers of all the messages in the folder path.
 java.lang.String getName()
          Returns the name of this Folder, taking the last part of the fullname
 Message getNextMessage()
          Get the next message in the folder.
 Folder getParent()
          Returns the parent Folder of this Folder
 char getSeparator()
          Returns the delimiter character that separates this Folder's pathname from the names of immediate subfolders TODO: Perhaps it is better to define in a field the character used as separator and not directly here (this adopted here is the solution by Sun)
 Store getStore()
          Retrieves the Store containing this Folder
 Folder[] list()
          This method returns the list of folders under this Folder
 void updateMessage(Message msg)
          Updates the given Message
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

Folder

public Folder(java.lang.String fullname,
              Store store)
Constructs a new Folder providing a name for it and a reference to the Store in which it has to be created

Parameters:
fullname - The name for this Folder
store - The Store in which the folder has to be created
Method Detail

appendMessage

public void appendMessage(Message msg)
                   throws MailException
Appends the given Message to this Folder

Throws:
MailException

updateMessage

public void updateMessage(Message msg)
                   throws MailException
Updates the given Message

Throws:
MailException

getMessage

public Message getMessage(java.lang.String recordId)
                   throws MailException
Gets the Message object corresponding to the given record ID

Throws:
MailException

getMsgHeaders

public Message[] getMsgHeaders()
                        throws MailException
This method returns the headers of all the messages in the folder path.

Returns:
An array of Message with all the headers set but without content
Throws:
MailException - If an error occurs accessing the Store

getFirstMessage

public Message getFirstMessage()
                        throws MailException
Get the first message in the folder.

Returns:
the first message if it exists, null otherwise
Throws:
MailException - if an error occurs while reading a message, or if the folder is not found in the store

getNextMessage

public Message getNextMessage()
                       throws MailException
Get the next message in the folder.

Returns:
the next message if it exists, null otherwise
Throws:
MailException - if an error occurs while reading a message, or if the folder is not found in the store

deleteMessage

public void deleteMessage(Message msg)
                   throws MailException
Deletes a Message from this Folder The message is properly updated so that it is both complete (completely loaded in memory) and its parent folder is cleared. After this call the Message object is valid and can be used in any operation.

Parameters:
msg - A reference to the message to be deleted
Throws:
MailException

deleteMessage

public void deleteMessage(java.lang.String recordId)
                   throws MailException
Deletes a Message from this Folder, using the record id as key. If the client has one or more Message objects that hold the message at this record id position, there is no guarantee these objects are still valid after this call. For such cases the client should use @see deleteMessage(Message)

Parameters:
key - A reference to the message to be deleted
Throws:
MailException

deleteMessage

public void deleteMessage(int index)
                   throws MailException
Deletes a Message from this Folder, using a positional index as key. If the client has one or more Message objects that hold the message at this record id position, there is no guarantee these objects are still valid after this call. For such cases the client should use @see deleteMessage(Message) The position starts from 1 and it is always referred to the messages currently present in the folder. Deleting a message causes the index to be shifted. This must be taken into account by calling methods. The order in which the messages are ordered is not defined, and the caller must not rely on it.

Parameters:
index - The index of the message to delete
Throws:
MailException

getMessageCount

public int getMessageCount()
                    throws MailException
Get the total number of messages in this Folder

Throws:
MailException

getMessageWithFlagCount

public int getMessageWithFlagCount(int flag,
                                   boolean set)
                            throws MailException
Returns the total number of messages in this Folder with the specified flag enabled or disabled

Parameters:
flag - the message flag (@see MessageFlags)
set - if this parameter is true, then a message is counted iff the corresponding flag is set to true. If this parameter is false, then a message is counted iff the corresponding flag is set to false.
Throws:
MailException - if getFirstMessage or getNextMessage throw this exception, then this method propagates it

getParent

public Folder getParent()
                 throws MailException
Returns the parent Folder of this Folder

Returns:
The Folder object this Folder is child of
Throws:
MailException

getSeparator

public char getSeparator()
Returns the delimiter character that separates this Folder's pathname from the names of immediate subfolders TODO: Perhaps it is better to define in a field the character used as separator and not directly here (this adopted here is the solution by Sun)

Returns:
The hierarchy separator character

list

public Folder[] list()
              throws MailException
This method returns the list of folders under this Folder

Throws:
MailException

getStore

public Store getStore()
Retrieves the Store containing this Folder

Returns:
A reference to the Store containing this Folder

getFullName

public java.lang.String getFullName()
Returns the full name of this Folder as passed in the constructor

Returns:
The string containing the full name of this Folder

getName

public java.lang.String getName()
Returns the name of this Folder, taking the last part of the fullname

Returns:
The string containing the name of this Folder

getFolder

public Folder getFolder(java.lang.String name)
                 throws MailException
Returns the requested subfolder

Parameters:
name - The name of the subfolder
Returns:
The Folder object representing the requested subfolder
Throws:
MailException


Copyright © 2006 Funambol.