FileDocCategorySizeDatePackage
POP3Folder.javaAPI DocJavaMail 1.4.316398Tue Nov 17 10:38:10 GMT 2009com.sun.mail.pop3

POP3Folder

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

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

Fields Summary
private String
name
private Protocol
port
private int
total
private int
size
private boolean
exists
private boolean
opened
private Vector
message_cache
private boolean
doneUidl
Constructors Summary
POP3Folder(POP3Store store, String name)


        
	super(store);
	this.name = name;
	if (name.equalsIgnoreCase("INBOX"))
	    exists = true;
    
Methods Summary
public voidappendMessages(Message[] msgs)
Always throws MethodNotSupportedException because the POP3 protocol doesn't support appending messages.

exception
MethodNotSupportedException always

	throw new MethodNotSupportedException("Append not supported");	
    
voidcheckClosed()

	if (opened) 
	    throw new IllegalStateException("Folder is Open");
    
voidcheckOpen()

	if (!opened) 
	    throw new IllegalStateException("Folder is not Open");
    
voidcheckReadable()

	if (!opened || (mode != READ_ONLY && mode != READ_WRITE))
	    throw new IllegalStateException("Folder is not Readable");
    
voidcheckWritable()

	if (!opened || mode != READ_WRITE)
	    throw new IllegalStateException("Folder is not Writable");
    
public synchronized voidclose(boolean expunge)

	checkOpen();

	try {
	    /*
	     * Some POP3 servers will mark messages for deletion when
	     * they're read.  To prevent such messages from being
	     * deleted before the client deletes them, you can set
	     * the mail.pop3.rsetbeforequit property to true.  This
	     * causes us to issue a POP3 RSET command to clear all
	     * the "marked for deletion" flags.  We can then explicitly
	     * delete messages as desired.
	     */
	    if (((POP3Store)store).rsetBeforeQuit)
		port.rset();
	    if (expunge && mode == READ_WRITE) {
		// find all messages marked deleted and issue DELE commands
		POP3Message m;
		for (int i = 0; i < message_cache.size(); i++) {
		    if ((m = (POP3Message)message_cache.elementAt(i)) != null) {
			if (m.isSet(Flags.Flag.DELETED))
			    try {
				port.dele(i + 1);
			    } catch (IOException ioex) {
				throw new MessagingException(
				    "Exception deleting messages during close",
				    ioex);
			    }
		    }
		}
	    }

	    port.quit();
	} catch (IOException ex) {
	    // do nothing
	} finally {
	    port = null;
	    ((POP3Store)store).closePort(this);
	    message_cache = null;
	    opened = false;
	    notifyConnectionListeners(ConnectionEvent.CLOSED);
	}
    
public booleancreate(int type)
Always returns false; the POP3 protocol doesn't support creating folders.

return
false

	return false;
    
protected com.sun.mail.pop3.POP3MessagecreateMessage(javax.mail.Folder f, int msgno)

	POP3Message m = null;
	Constructor cons = ((POP3Store)store).messageConstructor;
	if (cons != null) {
	    try {
		Object[] o = { this, new Integer(msgno) };
		m = (POP3Message)cons.newInstance(o);
	    } catch (Exception ex) {
		// ignore
	    }
	}
	if (m == null)
	    m = new POP3Message(this, msgno);
	return m;
    
public booleandelete(boolean recurse)
Always throws MethodNotSupportedException because the POP3 protocol doesn't allow the INBOX to be deleted.

exception
MethodNotSupportedException always

	throw new MethodNotSupportedException("delete");
    
public booleanexists()
Always true for the folder "INBOX", always false for any other name.

return
true for INBOX, false otherwise

	return exists;
    
public Message[]expunge()
Always throws MethodNotSupportedException because the POP3 protocol doesn't support expunging messages without closing the folder; call the {@link #close close} method with the expunge argument set to true instead.

exception
MethodNotSupportedException always

	throw new MethodNotSupportedException("Expunge not supported");
    
public synchronized voidfetch(Message[] msgs, javax.mail.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.

	checkReadable();
	if (!doneUidl && ((POP3Store)store).supportsUidl &&
		fp.contains(UIDFolder.FetchProfileItem.UID)) {
	    /*
	     * Since the POP3 protocol only lets us fetch the UID
	     * for a single message or for all messages, we go ahead
	     * and fetch UIDs for all messages here, ignoring the msgs
	     * parameter.  We could be more intelligent and base this
	     * decision on the number of messages fetched, or the
	     * percentage of the total number of messages fetched.
	     */
	    String[] uids = new String[message_cache.size()];
	    try {
		if (!port.uidl(uids))
		    return;
	    } catch (EOFException eex) {
		close(false);
		throw new FolderClosedException(this, eex.toString());
	    } catch (IOException ex) {
		throw new MessagingException("error getting UIDL", ex);
	    }
	    for (int i = 0; i < uids.length; i++) {
		if (uids[i] == null)
		    continue;
		POP3Message m = (POP3Message)getMessage(i + 1);
		m.uid = uids[i];
	    }
	    doneUidl = true;	// only do this once
	}
	if (fp.contains(FetchProfile.Item.ENVELOPE)) {
	    for (int i = 0; i < msgs.length; i++) {
		try {
		    POP3Message msg = (POP3Message)msgs[i];
		    // fetch headers
		    msg.getHeader("");
		    // fetch message size
		    msg.getSize();
		} catch (MessageRemovedException mex) {
		    // should never happen, but ignore it if it does
		}
	    }
	}
    
protected voidfinalize()
Close the folder when we're finalized.

	super.finalize();
	close(false);
    
public javax.mail.FoldergetFolder(java.lang.String name)
Always throws MessagingException because no POP3 folders can contain subfolders.

exception
MessagingException always

	throw new MessagingException("not a directory");
    
public java.lang.StringgetFullName()

	return name;
    
public synchronized MessagegetMessage(int msgno)

	checkOpen();

	POP3Message m;

	// Assuming that msgno is <= total 
	if ((m = (POP3Message)message_cache.elementAt(msgno-1)) == null) {
	    m = createMessage(this, msgno);
	    message_cache.setElementAt(m, msgno-1);
	}
	return m;
    
public synchronized intgetMessageCount()
Will not change while the folder is open because the POP3 protocol doesn't support notification of new messages arriving in open folders.

	if (!opened)
	    return -1;
	checkReadable();
	return total;
    
public java.lang.StringgetName()

	return name;
    
public javax.mail.FoldergetParent()

	return new DefaultFolder((POP3Store)store);
    
public javax.mail.FlagsgetPermanentFlags()
Always returns an empty Flags object because the POP3 protocol doesn't support any permanent flags.

return
empty Flags object

	return new Flags(); // empty flags object
    
com.sun.mail.pop3.ProtocolgetProtocol()
Centralize access to the Protocol object by POP3Message objects so that they will fail appropriately when the folder is closed.

	checkOpen();
	return port;
    
public chargetSeparator()
Always returns a NUL character because POP3 doesn't support a hierarchy.

return
NUL

	return '\0";
    
public synchronized intgetSize()
Return the size of this folder, as was returned by the POP3 STAT command when this folder was opened.

return
folder size
exception
IllegalStateException if the folder isn't open

	checkOpen();
	return size;
    
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.

return
array of message sizes
exception
IllegalStateException if the folder isn't open
since
JavaMail 1.3.3

	checkOpen();
	int sizes[] = new int[total];
	InputStream is = null;
	LineInputStream lis = null;
	try {
	    is = port.list();
	    lis = new LineInputStream(is);
	    String line;
	    while ((line = lis.readLine()) != null) {
		try {
		    StringTokenizer st = new StringTokenizer(line);
		    int msgnum = Integer.parseInt(st.nextToken());
		    int size = Integer.parseInt(st.nextToken());
		    if (msgnum > 0 && msgnum <= total)
			sizes[msgnum - 1] = size;
		} catch (Exception e) {
		}
	    }
	} catch (IOException ex) {
	    // ignore it?
	} finally {
	    try {
		if (lis != null)
		    lis.close();
	    } catch (IOException cex) { }
	    try {
		if (is != null)
		    is.close();
	    } catch (IOException cex) { }
	}
	return sizes;
    
public intgetType()
Always returns Folder.HOLDS_MESSAGES.

return
Folder.HOLDS_MESSAGES

	return HOLDS_MESSAGES;
    
public synchronized java.lang.StringgetUID(Message msg)
Return the unique ID string for this message, or null if not available. Uses the POP3 UIDL command.

return
unique ID string
exception
MessagingException

	checkOpen();
	POP3Message m = (POP3Message)msg;
	try {
	    if (!((POP3Store)store).supportsUidl)
		return null;
	    if (m.uid == POP3Message.UNKNOWN)
		m.uid = port.uidl(m.getMessageNumber());
	    return m.uid;
	} catch (EOFException eex) {
	    close(false);
	    throw new FolderClosedException(this, eex.toString());
	} catch (IOException ex) {
	    throw new MessagingException("error getting UIDL", ex);
	}
    
public booleanhasNewMessages()
Always returns false; the POP3 protocol provides no way to determine when a new message arrives.

return
false

	return false;    // no way to know
    
public synchronized booleanisOpen()

	if (!opened)
	    return false;
	try {
	    if (!port.noop())
		throw new IOException("NOOP failed");
	} catch (IOException ioex) {
	    try {
		close(false);
	    } catch (MessagingException mex) {
		// ignore it
	    } finally {
		return false;
	    }
	}
	return true;
    
public javax.mail.Folder[]list(java.lang.String pattern)
Always throws MessagingException because no POP3 folders can contain subfolders.

exception
MessagingException always

	throw new MessagingException("not a directory");
    
public synchronized java.io.InputStreamlistCommand()
Return the raw results of the POP3 LIST command with no arguments.

return
InputStream containing results
exception
IllegalStateException if the folder isn't open
since
JavaMail 1.3.3

	checkOpen();
	return port.list();
    
protected voidnotifyMessageChangedListeners(int type, Message m)

	super.notifyMessageChangedListeners(type, m);
    
public synchronized voidopen(int mode)
Throws FolderNotFoundException unless this folder is named "INBOX".

exception
FolderNotFoundException if not INBOX
exception
AuthenticationException authentication failures
exception
MessagingException other open failures

	checkClosed();
	if (!exists)
	    throw new FolderNotFoundException(this, "folder is not INBOX");

	try {
	    port = ((POP3Store)store).getPort(this);
	    Status s = port.stat();
	    total = s.total;
	    size = s.size;
	    this.mode = mode;
	    opened = true;
	} catch (IOException ioex) {
	    try {
		if (port != null)
		    port.quit();
	    } catch (IOException ioex2) {
		// ignore
	    } finally {
		port = null;
		((POP3Store)store).closePort(this);
	    }
	    throw new MessagingException("Open failed", ioex);
	}

	// Create the message cache vector of appropriate size
	message_cache = new Vector(total);
	message_cache.setSize(total);
	doneUidl = false;

	notifyConnectionListeners(ConnectionEvent.OPENED);
    
public booleanrenameTo(javax.mail.Folder f)
Always throws MethodNotSupportedException because the POP3 protocol doesn't support multiple folders.

exception
MethodNotSupportedException always

	throw new MethodNotSupportedException("renameTo");