IMAPFolder

Constructor used to create a possibly non-existent folder.

Constructor used to create an existing folder.

Add an access control list entry to the access control list for this folder.

Add a listener for MessageCount events on this GmailFolder.

The implementation provided here adds this listener to an internal list of MessageCountListeners.

Append the given messages into this folder. Return array of Message objects representing the messages in the destination folder. Note that the folder must be open. Each element of the returned array corresponds to an element of the msgs array. A null element means the server didn't return UID information for the appended message.

Depends on the APPENDUID response code defined by the UIDPLUS extension - RFC 2359.

Add the rights specified in the ACL to the entry for the identifier specified in the ACL. If an entry for the identifier doesn't already exist, add one.

Append the given messages into this folder.

Append the given messages into this folder. Return array of AppendUID objects containing UIDs of these messages in the destination folder. Each element of the returned array corresponds to an element of the msgs array. A null element means the server didn't return UID information for the appended message.

Depends on the APPENDUID response code defined by the UIDPLUS extension - RFC 2359.

Close this folder.

Copy the specified messages from this folder, to the specified destination.

Create this folder, with the specified type.

Delete this folder.

Execute a user-supplied IMAP command. The command is executed in the appropriate context with the necessary locks held and using the appropriate IMAPProtocol object.

This method returns whatever the ProtocolCommand object's doCommand method returns. If the doCommand method throws a ConnectionException it is translated into a StoreClosedException or FolderClosedException as appropriate. If the doCommand method throws a ProtocolException it is translated into a MessagingException.

The following example shows how to execute the IMAP NOOP command. Executing more complex IMAP commands requires intimate knowledge of the com.sun.mail.iap and com.sun.mail.imap.protocol packages, best acquired by reading the source code.

 import com.google.code.com.sun.mail.iap.*;
 import com.google.code.com.sun.mail.imap.*;
 import com.google.code.com.sun.mail.imap.protocol.*;

 ...

 IMAPFolder f = (IMAPFolder)folder;
 Object val = f.doCommand(new IMAPFolder.ProtocolCommand() {
	public Object doCommand(IMAPProtocol p)
			throws ProtocolException {
	    p.simpleCommand("NOOP", null);
	    return null;
	}
 });
 

Here's a more complex example showing how to use the proposed IMAP SORT extension:

 import com.google.code.com.sun.mail.iap.*;
 import com.google.code.com.sun.mail.imap.*;
 import com.google.code.com.sun.mail.imap.protocol.*;

 ...

 IMAPFolder f = (IMAPFolder)folder;
 Object val = f.doCommand(new IMAPFolder.ProtocolCommand() {
	public Object doCommand(IMAPProtocol p)
			throws ProtocolException {
	    // Issue command
	    Argument args = new Argument();
	    Argument list = new Argument();
	    list.writeString("SUBJECT");
	    args.writeArgument(list);
	    args.writeString("UTF-8");
	    args.writeString("ALL");
	    Response[] r = p.command("SORT", args);
	    Response response = r[r.length-1];

	    // Grab response
	    Vector v = new Vector();
	    if (response.isOK()) { // command succesful 
		for (int i = 0, len = r.length; i < len; i++) {
		    if (!(r[i] instanceof IMAPResponse))
			continue;

		    IMAPResponse ir = (IMAPResponse)r[i];
		    if (ir.keyEquals("SORT")) {
			String num;
			while ((num = ir.readAtomString()) != null)
			    System.out.println(num);
			r[i] = null;
		    }
		}
	    }

	    // dispatch remaining untagged responses
	    p.notifyResponseHandlers(r);
	    p.handleResult(response);

	    return null;
	}
 });
 

Check whether this folder really exists on the server.

Expunge the indicated messages, which must have been marked as DELETED. Depends on the UIDPLUS extension - RFC 2359.

Expunge all messages marked as DELETED.

Prefetch attributes, based on the given FetchProfile.

Close this folder without waiting for the server.

Get the access control list entries for this folder.

Get the attributes that the IMAP server returns with the LIST response.

Get the deleted message count.

Get the named subfolder.

Get the fullname of this folder.

Get the specified message.

Get the Message corresponding to the given UID. If no such message exists, null is returned.

Get the total message count.

Get the Messages specified by the given array.

uids.length() elements are returned. If any UID in the array is invalid, a null entry is returned for that element.

Get the Messages specified by the given range.

Returns Message objects for all valid messages in this range. Returns an empty array if no messages are found.

Get the name of this folder.

Get the new message count.

Get this folder's parent.

Return the permanent flags supported by the server.

Get the quotas for the quotaroot associated with this folder. Note that many folders may have the same quotaroot. Quotas are controlled on the basis of a quotaroot, not (necessarily) a folder. The relationship between folders and quotaroots depends on the IMAP server. Some servers might implement a single quotaroot for all folders owned by a user. Other servers might implement a separate quotaroot for each folder. A single folder can even have multiple quotaroots, perhaps controlling quotas for different resources.

Get the separator character.

Sort the messages in the folder according to the sort criteria. The messages are returned in the sorted order, but the order of the messages in the folder is not changed. Only messages matching the search criteria are considered.

Sort the messages in the folder according to the sort criteria. The messages are returned in the sorted order, but the order of the messages in the folder is not changed.

Get the type of this folder.

Get the UID for the specified message.

Returns the predicted UID that will be assigned to the next message that is appended to this folder. If the folder is closed, the STATUS command is used to retrieve this value. If the folder is open, the value returned from the SELECT or EXAMINE command is returned. Note that messages may have been appended to the folder while it was open and thus this value may be out of date.

Servers implementing RFC2060 likely won't return this value when a folder is opened. Servers implementing RFC3501 should return this value when a folder is opened.

Returns the UIDValidity for this folder.

Get the unread message count.

The response handler. This is the callback routine that is invoked by the protocol layer.

Check whether this folder has new messages.

Like idle(), but if once is true, abort the IDLE command after the first notification, to allow the caller to process any notification synchronously.

Use the IMAP IDLE command (see RFC 2177), if supported by the server, to enter idle mode so that the server can send unsolicited notifications of new messages arriving, etc. without the need for the client to constantly poll the server. Use an appropriate listener to be notified of new messages or other events. When another thread (e.g., the listener thread) needs to issue an IMAP comand for this folder, the idle mode will be terminated and this method will return. Typically the caller will invoke this method in a loop.

The mail.imap.minidletime property enforces a minimum delay before returning from this method, to ensure that other threads have a chance to issue commands before the caller invokes this method again. The default delay is 10 milliseconds.

Check whether this connection is really open.

Check whether this folder is subscribed.

List all subfolders matching the specified pattern.

Get all the rights that may be allowed to the given identifier. Rights are grouped per RFC 2086 and each group is returned as an element of the array. The first element of the array is the set of rights that are always granted to the identifier. Later elements are rights that may be optionally granted to the identifier.

Note that this method lists the rights that it is possible to assign to the given identifier, not the rights that are actually granted to the given identifier. For the latter, see the getACL method.

List all subscribed subfolders matching the specified pattern.

Get the rights allowed to the currently authenticated user.

Open this folder in the given mode.

Remove any access control list entry for the given identifier from the access control list for this folder.

Remove the rights specified in the ACL from the entry for the identifier specified in the ACL.

Rename this folder.

Search whole folder for messages matching the given term.

Search the folder for messages matching the given term. Returns array of matching messages. Returns an empty array if no matching messages are found.

Set the specified flags for the given array of messages.

Set the quotas for the quotaroot specified in the quota argument. Typically this will be one of the quotaroots associated with this folder, as obtained from the getQuota method, but it need not be.

Subscribe/Unsubscribe this folder.

Get the message object for the given sequence number. If none found, null is returned. ASSERT: This method must be called only when holding the messageCacheLock

Return the IMAPProtocol object for this folder.

This method will block if necessary to wait for an IDLE command to finish.

Get this folder's Store's protocol connection. When acquiring a store protocol object, it is important to use the following steps: IMAPProtocol p = null; try { p = getStoreProtocol(); // perform the command } catch (WhateverException ex) { // handle it } finally { releaseStoreProtocol(p); }

Issue a noop command for the connection if the connection has not been used in more than a second. If keepStoreAlive is true, also issue a noop over the store's connection. ASSERT: This method must be called only when holding the messageCacheLock

Release the protocol object. ASSERT: This method must be called only when holding the messageCacheLock

Release the store protocol object. If we borrowed a protocol object from the connection pool, give it back. If we used our own protocol object, nothing to do.

Throw the appropriate 'closed' exception.