public class

POP3Folder

extends Folder
java.lang.Object
   ↳ com.google.code.javax.mail.Folder
     ↳ com.google.code.com.sun.mail.pop3.POP3Folder

Class Overview

A POP3 GmailFolder (can only be "INBOX"). See the com.sun.mail.pop3 package documentation for further information on the POP3 protocol provider.

Summary

[Expand]
Inherited Constants
From class com.google.code.javax.mail.Folder
Fields
private boolean doneUidl
private boolean exists
private TempFile fileCache
private Vector message_cache
private String name
private boolean opened
private Protocol port
private int size
private POP3Store store
private int total
[Expand]
Inherited Fields
From class com.google.code.javax.mail.Folder
Public Methods
void appendMessages(Message[] msgs)
Always throws MethodNotSupportedException because the POP3 protocol doesn't support appending messages.
synchronized void close(boolean expunge)
Close this GmailFolder.
boolean create(int type)
Always returns false; the POP3 protocol doesn't support creating folders.
boolean delete(boolean recurse)
Always throws MethodNotSupportedException because the POP3 protocol doesn't allow the INBOX to be deleted.
boolean exists()
Always true for the folder "INBOX", always false for any other name.
Message[] expunge()
Always throws MethodNotSupportedException because the POP3 protocol doesn't support expunging messages without closing the folder; call the close method with the expunge argument set to true instead.
synchronized void fetch(Message[] msgs, FetchProfile fp)
Prefetch information about POP3 messages.
Folder getFolder(String name)
Always throws MessagingException because no POP3 folders can contain subfolders.
String getFullName()
Returns the full name of this GmailFolder.
synchronized Message getMessage(int msgno)
Get the Message object corresponding to the given message number.
synchronized int getMessageCount()
Will not change while the folder is open because the POP3 protocol doesn't support notification of new messages arriving in open folders.
String getName()
Returns the name of this GmailFolder.
Folder getParent()
Returns the parent folder of this folder.
Flags getPermanentFlags()
Always returns an empty Flags object because the POP3 protocol doesn't support any permanent flags.
char getSeparator()
Always returns a NUL character because POP3 doesn't support a hierarchy.
synchronized int getSize()
Return the size of this folder, as was returned by the POP3 STAT command when this folder was opened.
synchronized int[] getSizes()
Return the sizes of all messages in this folder, as returned by the POP3 LIST command.
int getType()
Always returns GmailFolder.HOLDS_MESSAGES.
synchronized String getUID(Message msg)
Return the unique ID string for this message, or null if not available.
boolean hasNewMessages()
Always returns false; the POP3 protocol provides no way to determine when a new message arrives.
synchronized boolean isOpen()
Indicates whether this GmailFolder is in the 'open' state.
Folder[] list(String pattern)
Always throws MessagingException because no POP3 folders can contain subfolders.
synchronized InputStream listCommand()
Return the raw results of the POP3 LIST command with no arguments.
synchronized void open(int mode)
Throws FolderNotFoundException unless this folder is named "INBOX".
boolean renameTo(Folder f)
Always throws MethodNotSupportedException because the POP3 protocol doesn't support multiple folders.
Folder[] xlist(String pattern)
Protected Methods
POP3Message createMessage(Folder f, int msgno)
void finalize()
Close the folder when we're finalized.
void notifyMessageChangedListeners(int type, Message m)
Notify all MessageChangedListeners.
[Expand]
Inherited Methods
From class com.google.code.javax.mail.Folder
From class java.lang.Object

Fields

private boolean doneUidl

private boolean exists

private TempFile fileCache

private Vector message_cache

private String name

private boolean opened

private Protocol port

private int size

private POP3Store store

private int total

Public Methods

public void appendMessages (Message[] msgs)

Always throws MethodNotSupportedException because the POP3 protocol doesn't support appending messages.

Parameters
msgs Array of Messages to be appended
Throws
MethodNotSupportedException always
MessagingException

public synchronized void close (boolean expunge)

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

A CLOSED ConnectionEvent is delivered to any ConnectionListeners registered on this GmailFolder. 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
Throws
MessagingException

public boolean create (int type)

Always returns false; the POP3 protocol doesn't support creating folders.

Parameters
type The type of this folder.
Returns
  • false
Throws
MessagingException

public boolean delete (boolean recurse)

Always throws MethodNotSupportedException because the POP3 protocol doesn't allow the INBOX to be deleted.

Parameters
recurse
Returns
  • true if the GmailFolder is deleted successfully
Throws
MethodNotSupportedException always
MessagingException

public boolean exists ()

Always true for the folder "INBOX", always false for any other name.

Returns
  • true for INBOX, false otherwise

public Message[] expunge ()

Always throws MethodNotSupportedException because the POP3 protocol doesn't support expunging messages without closing the folder; call the close method with the expunge argument set to true instead.

Returns
  • array of expunged Message objects
Throws
MethodNotSupportedException always
MessagingException

public synchronized void fetch (Message[] msgs, FetchProfile fp)

Prefetch information about POP3 messages. If the FetchProfile contains UIDFolder.FetchProfileItem.UID, POP3 UIDs for all messages in the folder are fetched using the POP3 UIDL command. If the FetchProfile contains FetchProfile.Item.ENVELOPE, the headers and size of all messages are fetched using the POP3 TOP and LIST commands.

Parameters
msgs Fetch items for these messages
fp The FetchProfile
Throws
MessagingException

public Folder getFolder (String name)

Always throws MessagingException because no POP3 folders can contain subfolders.

Parameters
name Name of the GmailFolder
Returns
  • GmailFolder object
Throws
MessagingException always

public String getFullName ()

Returns the full name of this GmailFolder. 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 GmailFolder.

Returns
  • full name of the GmailFolder

public synchronized Message getMessage (int msgno)

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 GmailFolder. 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 GmailFolder are deleted and the GmailFolder is expunged.

Message objects are light-weight references to the actual message that get filled up on demand. Hence GmailFolder implementations are expected to provide light-weight Message objects.

Unlike GmailFolder 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
msgno The message number
Returns
  • the Message object
Throws
MessagingException

public synchronized int getMessageCount ()

Will not change while the folder is open because the POP3 protocol doesn't support notification of new messages arriving in open folders.

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

public String getName ()

Returns the name of this GmailFolder.

This method can be invoked on a closed GmailFolder.

Returns
  • name of the GmailFolder

public Folder getParent ()

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

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

Returns
  • Parent folder

public Flags getPermanentFlags ()

Always returns an empty Flags object because the POP3 protocol doesn't support any permanent flags.

Returns
  • empty Flags object

public char getSeparator ()

Always returns a NUL character because POP3 doesn't support a hierarchy.

Returns
  • NUL

public synchronized int getSize ()

Return the size of this folder, as was returned by the POP3 STAT command when this folder was opened.

Returns
  • folder size
Throws
IllegalStateException if the folder isn't open
MessagingException

public synchronized int[] getSizes ()

Return the sizes of all messages in this folder, as returned by the POP3 LIST command. Each entry in the array corresponds to a message; entry i corresponds to message number i+1.

Returns
  • array of message sizes
Throws
IllegalStateException if the folder isn't open
MessagingException

public int getType ()

Always returns GmailFolder.HOLDS_MESSAGES.

Returns
  • GmailFolder.HOLDS_MESSAGES

public synchronized String getUID (Message msg)

Return the unique ID string for this message, or null if not available. Uses the POP3 UIDL command.

Parameters
msg
Returns
  • unique ID string
Throws
MessagingException

public boolean hasNewMessages ()

Always returns false; the POP3 protocol provides no way to determine when a new message arrives.

Returns
  • false
Throws
MessagingException

public synchronized boolean isOpen ()

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

Returns
  • true if this GmailFolder is in the 'open' state.

public Folder[] list (String pattern)

Always throws MessagingException because no POP3 folders can contain subfolders.

Parameters
pattern The match pattern
Returns
  • array of matching GmailFolder objects. An empty array is returned if no matching Folders exist.
Throws
MessagingException always

public synchronized InputStream listCommand ()

Return the raw results of the POP3 LIST command with no arguments.

Returns
  • InputStream containing results
Throws
IllegalStateException if the folder isn't open
IOException
MessagingException

public synchronized void open (int mode)

Throws FolderNotFoundException unless this folder is named "INBOX".

Parameters
mode Open the GmailFolder READ_ONLY or READ_WRITE
Throws
FolderNotFoundException if not INBOX
MessagingException other open failures

public boolean renameTo (Folder f)

Always throws MethodNotSupportedException because the POP3 protocol doesn't support multiple folders.

Parameters
f A folder representing the new name for this GmailFolder
Returns
  • true if the GmailFolder is renamed successfully
Throws
MethodNotSupportedException always
MessagingException

public Folder[] xlist (String pattern)

Parameters
pattern
Throws
MessagingException

Protected Methods

protected POP3Message createMessage (Folder f, int msgno)

Parameters
f
msgno
Throws
MessagingException

protected void finalize ()

Close the folder when we're finalized.

Throws
Throwable

protected void notifyMessageChangedListeners (int type, Message m)

Notify all MessageChangedListeners. GmailFolder 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.

Parameters
type
m