Top Description Fields Constructors Methods
com.sun.mail.pop3

public Class POP3Folder

extends Folder
Class Inheritance
Imports
javax.mail.*, javax.mail.event.*, java.io.InputStream, .IOException, .EOFException, java.util.StringTokenizer, .ArrayList, .List, java.util.logging.Level, java.lang.reflect.Constructor, com.sun.mail.util.LineInputStream, .MailLogger
A POP3 Folder (can only be "INBOX"). See the com.sun.mail.pop3 package documentation for further information on the POP3 protocol provider.

Authors
Bill Shannon, John Mani (ported to the javax.mail APIs)

Field Summary

Modifier and TypeField and Description
private boolean
doneUidl

private boolean
exists

private volatile TempFile
fileCache

private boolean
forceClose

pack-priv MailLogger
logger

private POP3Message[]
message_cache

private String
name

private volatile boolean
opened

private volatile Protocol
port

private int
size

private POP3Store
store

Hides javax.mail.Folder.store.

private int
total

Inherited from javax.mail.Folder:
HOLDS_FOLDERSHOLDS_MESSAGESmodeREAD_ONLYREAD_WRITE

Constructor Summary

AccessConstructor and Description
protected
POP3Folder(POP3Store store, String name)

Method Summary

Modifier and TypeMethod and Description
public void
appendMessages(Message[]
array of Messages to be appended
msgs)

Implements abstract javax.mail.Folder.appendMessages.

Always throws MethodNotSupportedException because the POP3 protocol doesn't support appending messages.
private void
checkClosed()

private void
checkOpen()

private void
checkReadable()

public synchronized void
close(boolean
expunges all deleted messages if this flag is true
expunge)

Implements abstract javax.mail.Folder.close.

Close this Folder.
public boolean

Returns:

false
create(int
The type of this folder.
type)

Implements abstract javax.mail.Folder.create.

Always returns false; the POP3 protocol doesn't support creating folders.
protected POP3Message
createMessage(Folder f, int msgno)

public boolean
delete(boolean
also delete subfolders?
recurse)

Implements abstract javax.mail.Folder.delete.

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

Returns:

true for INBOX, false otherwise
exists()

Implements abstract javax.mail.Folder.exists.

Always true for the folder "INBOX", always false for any other name.
public Message[]
expunge()

Implements abstract javax.mail.Folder.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.
public synchronized void
fetch(Message[]
fetch items for these messages
msgs, FetchProfile
the FetchProfile
fp)

Overrides javax.mail.Folder.fetch.

Prefetch information about POP3 messages.
protected void
finalize()

Overrides javax.mail.Folder.finalize.

Close the folder when we're finalized.
pack-priv TempFile
getFileCache()

Used by POP3Message.

public Folder
getFolder(String
name of the Folder
name)

Implements abstract javax.mail.Folder.getFolder.

Always throws MessagingException because no POP3 folders can contain subfolders.
public String
getFullName()

Implements abstract javax.mail.Folder.getFullName.

Returns the full name of this Folder.
public synchronized Message
getMessage(int
the message number
msgno)

Implements abstract javax.mail.Folder.getMessage.

Get the Message object corresponding to the given message number.
public synchronized int
getMessageCount()

Implements abstract javax.mail.Folder.getMessageCount.

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

Implements abstract javax.mail.Folder.getName.

Returns the name of this Folder.
public Folder
getParent()

Implements abstract javax.mail.Folder.getParent.

Returns the parent folder of this folder.
public Flags

Returns:

empty Flags object
getPermanentFlags()

Implements abstract javax.mail.Folder.getPermanentFlags.

Always returns an empty Flags object because the POP3 protocol doesn't support any permanent flags.
pack-priv Protocol
getProtocol()

Centralize access to the Protocol object by POP3Message objects so that they will fail appropriately when the folder is closed.

public char

Returns:

NUL
getSeparator()

Implements abstract javax.mail.Folder.getSeparator.

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

Returns:

folder size
getSize()

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

public synchronized int[]

Returns:

array of message sizes
getSizes()

Return the sizes of all messages in this folder, as returned by the POP3 LIST command.

public int

Returns:

Folder.HOLDS_MESSAGES
getType()

Implements abstract javax.mail.Folder.getType.

Always returns Folder.HOLDS_MESSAGES.
public synchronized String

Returns:

unique ID string
getUID(Message
the message
msg)

Return the unique ID string for this message, or null if not available.

public boolean

Returns:

false
hasNewMessages()

Implements abstract javax.mail.Folder.hasNewMessages.

Always returns false; the POP3 protocol provides no way to determine when a new message arrives.
public synchronized boolean
isOpen()

Implements abstract javax.mail.Folder.isOpen.

Indicates whether this Folder is in the 'open' state.
public Folder[]
list(String
the match pattern
pattern)

Implements abstract javax.mail.Folder.list.

Always throws MessagingException because no POP3 folders can contain subfolders.
public synchronized InputStream

Returns:

InputStream containing results
listCommand()

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

protected void
notifyMessageChangedListeners(int
the MessageChangedEvent type
type, Message
the message that changed
m)

Overrides javax.mail.Folder.notifyMessageChangedListeners.

Notify all MessageChangedListeners.
public synchronized void
open(int
open the Folder READ_ONLY or READ_WRITE
mode)

Implements abstract javax.mail.Folder.open.

Throws FolderNotFoundException unless this folder is named "INBOX".
public boolean
renameTo(Folder
a folder representing the new name for this Folder
f)

Implements abstract javax.mail.Folder.renameTo.

Always throws MethodNotSupportedException because the POP3 protocol doesn't support multiple folders.
Inherited from javax.mail.Folder:
addConnectionListeneraddFolderListeneraddMessageChangedListeneraddMessageCountListenerclosecopyMessagesgetDeletedMessageCountgetMessagesgetMessagesgetMessagesgetModegetNewMessageCountgetStoregetUnreadMessageCountgetURLNameisSubscribedlistlistSubscribedlistSubscribednotifyConnectionListenersnotifyFolderListenersnotifyFolderRenamedListenersnotifyMessageAddedListenersnotifyMessageRemovedListenersremoveConnectionListenerremoveFolderListenerremoveMessageChangedListenerremoveMessageCountListenersearchsearchsetFlagssetFlagssetFlagssetSubscribedtoString

Field Detail

doneUidlback to summary
private boolean doneUidl
existsback to summary
private boolean exists
fileCacheback to summary
private volatile TempFile fileCache
forceCloseback to summary
private boolean forceClose
loggerback to summary
pack-priv MailLogger logger
message_cacheback to summary
private POP3Message[] message_cache
nameback to summary
private String name
openedback to summary
private volatile boolean opened
portback to summary
private volatile Protocol port
sizeback to summary
private int size
storeback to summary
private POP3Store store

Hides javax.mail.Folder.store.

totalback to summary
private int total

Constructor Detail

POP3Folderback to summary
protected POP3Folder(POP3Store store, String name)

Method Detail

appendMessagesback to summary
public void appendMessages(Message[] msgs) throws MessagingException

Implements abstract javax.mail.Folder.appendMessages.

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

Parameters
msgs:Message[]

Doc from javax.mail.Folder.appendMessages.

array of Messages to be appended

Annotations
@Override
Exceptions
MessagingException:

Doc from javax.mail.Folder.appendMessages.

if the append failed.

MethodNotSupportedException:
always
checkClosedback to summary
private void checkClosed() throws IllegalStateException
checkOpenback to summary
private void checkOpen() throws IllegalStateException
checkReadableback to summary
private void checkReadable() throws IllegalStateException
closeback to summary
public synchronized void close(boolean expunge) throws MessagingException

Implements abstract javax.mail.Folder.close.

Doc from javax.mail.Folder.close.

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.

Parameters
expunge:boolean

expunges all deleted messages if this flag is true

Annotations
@Override
Exceptions
MessagingException:
for other failures
createback to summary
public boolean create(int type) throws MessagingException

Implements abstract javax.mail.Folder.create.

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

Parameters
type:int

Doc from javax.mail.Folder.create.

The type of this folder.

Returns:boolean

false

Annotations
@Override
Exceptions
MessagingException:

Doc from javax.mail.Folder.create.

for failures

createMessageback to summary
protected POP3Message createMessage(Folder f, int msgno) throws MessagingException
deleteback to summary
public boolean delete(boolean recurse) throws MessagingException

Implements abstract javax.mail.Folder.delete.

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

Parameters
recurse:boolean

Doc from javax.mail.Folder.delete.

also delete subfolders?

Returns:boolean

Doc from javax.mail.Folder.delete.

true if the Folder is deleted successfully

Annotations
@Override
Exceptions
MessagingException:

Doc from javax.mail.Folder.delete.

for other failures

MethodNotSupportedException:
always
existsback to summary
public boolean exists()

Implements abstract javax.mail.Folder.exists.

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

Returns:boolean

true for INBOX, false otherwise

Annotations
@Override
expungeback to summary
public Message[] expunge() throws MessagingException

Implements abstract javax.mail.Folder.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:Message[]

Doc from javax.mail.Folder.expunge.

array of expunged Message objects

Annotations
@Override
Exceptions
MessagingException:

Doc from javax.mail.Folder.expunge.

for other failures

MethodNotSupportedException:
always
fetchback to summary
public synchronized void fetch(Message[] msgs, FetchProfile fp) throws MessagingException

Overrides javax.mail.Folder.fetch.

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:Message[]

Doc from javax.mail.Folder.fetch.

fetch items for these messages

fp:FetchProfile

Doc from javax.mail.Folder.fetch.

the FetchProfile

Annotations
@Override
Exceptions
MessagingException:

Doc from javax.mail.Folder.fetch.

for other failures

finalizeback to summary
protected void finalize() throws Throwable

Overrides javax.mail.Folder.finalize.

Close the folder when we're finalized.

Annotations
@Override
Exceptions
Throwable:

Doc from java.lang.Object.finalize.

the Exception raised by this method

getFileCacheback to summary
pack-priv TempFile getFileCache()

Used by POP3Message.

getFolderback to summary
public Folder getFolder(String name) throws MessagingException

Implements abstract javax.mail.Folder.getFolder.

Always throws MessagingException because no POP3 folders can contain subfolders.

Parameters
name:String

Doc from javax.mail.Folder.getFolder.

name of the Folder

Returns:Folder

Doc from javax.mail.Folder.getFolder.

Folder object

Annotations
@Override
Exceptions
MessagingException:
always
getFullNameback to summary
public String getFullName()

Implements abstract javax.mail.Folder.getFullName.

Doc from javax.mail.Folder.getFullName.

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.

Returns:String

full name of the Folder

Annotations
@Override
getMessageback to summary
public synchronized Message getMessage(int msgno) throws MessagingException

Implements abstract javax.mail.Folder.getMessage.

Doc from javax.mail.Folder.getMessage.

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

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
msgno:int

the message number

Returns:Message

the Message object

Annotations
@Override
Exceptions
MessagingException:
for other failures
getMessageCountback to summary
public synchronized int getMessageCount() throws MessagingException

Implements abstract javax.mail.Folder.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:int

Doc from javax.mail.Folder.getMessageCount.

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

Annotations
@Override
Exceptions
MessagingException:

Doc from javax.mail.Folder.getMessageCount.

for other failures

getNameback to summary
public String getName()

Implements abstract javax.mail.Folder.getName.

Doc from javax.mail.Folder.getName.

Returns the name of this Folder.

This method can be invoked on a closed Folder.

Returns:String

name of the Folder

Annotations
@Override
getParentback to summary
public Folder getParent()

Implements abstract javax.mail.Folder.getParent.

Doc from javax.mail.Folder.getParent.

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.

Returns:Folder

Parent folder

Annotations
@Override
getPermanentFlagsback to summary
public Flags getPermanentFlags()

Implements abstract javax.mail.Folder.getPermanentFlags.

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

Returns:Flags

empty Flags object

Annotations
@Override
getProtocolback to summary
pack-priv Protocol getProtocol() throws MessagingException

Centralize access to the Protocol object by POP3Message objects so that they will fail appropriately when the folder is closed.

getSeparatorback to summary
public char getSeparator()

Implements abstract javax.mail.Folder.getSeparator.

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

Returns:char

NUL

Annotations
@Override
getSizeback to summary
public synchronized int getSize() throws MessagingException

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

Returns:int

folder size

Exceptions
MessagingException:
for other failures
IllegalStateException:
if the folder isn't open
getSizesback to summary
public synchronized int[] getSizes() throws MessagingException

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:int[]

array of message sizes

Exceptions
MessagingException:
for other failures
IllegalStateException:
if the folder isn't open
Since
JavaMail 1.3.3
getTypeback to summary
public int getType()

Implements abstract javax.mail.Folder.getType.

Always returns Folder.HOLDS_MESSAGES.

Returns:int

Folder.HOLDS_MESSAGES

Annotations
@Override
getUIDback to summary
public synchronized String getUID(Message msg) throws MessagingException

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

Parameters
msg:Message

the message

Returns:String

unique ID string

Exceptions
MessagingException:
for failures
hasNewMessagesback to summary
public boolean hasNewMessages() throws MessagingException

Implements abstract javax.mail.Folder.hasNewMessages.

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

Returns:boolean

false

Annotations
@Override
Exceptions
MessagingException:

Doc from javax.mail.Folder.hasNewMessages.

for other failures

isOpenback to summary
public synchronized boolean isOpen()

Implements abstract javax.mail.Folder.isOpen.

Doc from javax.mail.Folder.isOpen.

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

Returns:boolean

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

Annotations
@Override
listback to summary
public Folder[] list(String pattern) throws MessagingException

Implements abstract javax.mail.Folder.list.

Always throws MessagingException because no POP3 folders can contain subfolders.

Parameters
pattern:String

Doc from javax.mail.Folder.list.

the match pattern

Returns:Folder[]

Doc from javax.mail.Folder.list.

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

Annotations
@Override
Exceptions
MessagingException:
always
listCommandback to summary
public synchronized InputStream listCommand() throws MessagingException, IOException

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

Returns:InputStream

InputStream containing results

Exceptions
MessagingException:
for other errors
IOException:
for I/O errors talking to the server
IllegalStateException:
if the folder isn't open
Since
JavaMail 1.3.3
notifyMessageChangedListenersback to summary
protected void notifyMessageChangedListeners(int type, Message m)

Overrides javax.mail.Folder.notifyMessageChangedListeners.

Doc from javax.mail.Folder.notifyMessageChangedListeners.

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.

Parameters
type:int

the MessageChangedEvent type

m:Message

the message that changed

Annotations
@Override
openback to summary
public synchronized void open(int mode) throws MessagingException

Implements abstract javax.mail.Folder.open.

Throws FolderNotFoundException unless this folder is named "INBOX".

Parameters
mode:int

Doc from javax.mail.Folder.open.

open the Folder READ_ONLY or READ_WRITE

Annotations
@Override
Exceptions
MessagingException:
other open failures
FolderNotFoundException:
if not INBOX
AuthenticationFailedException:
authentication failures
renameToback to summary
public boolean renameTo(Folder f) throws MessagingException

Implements abstract javax.mail.Folder.renameTo.

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

Parameters
f:Folder

Doc from javax.mail.Folder.renameTo.

a folder representing the new name for this Folder

Returns:boolean

Doc from javax.mail.Folder.renameTo.

true if the Folder is renamed successfully

Annotations
@Override
Exceptions
MessagingException:

Doc from javax.mail.Folder.renameTo.

for other failures

MethodNotSupportedException:
always