org.apache.geronimo.javamail.store.imap.connection
Class IMAPConnection

java.lang.Object
  org.apache.geronimo.javamail.util.MailConnection
      org.apache.geronimo.javamail.store.imap.connection.IMAPConnection

public class IMAPConnection
extends MailConnection

Simple implementation of IMAP transport. Just does plain RFC977-ish delivery.

There is no way to indicate failure for a given recipient (it's possible to have a recipient address rejected). The sun impl throws exceptions even if others successful), but maybe we do a different way...

Version:

$Rev: 739377 $ $Date: 2009-01-30 13:57:39 -0500 (Fri, 30 Jan 2009) $

Field Summary

protected static String	CAPABILITY_LOGIN_DISABLED
protected boolean	closed
protected long	lastAccess
protected IMAPConnectionPool	pool
protected List	queuedResponses
protected IMAPResponseStream	reader
protected LinkedList	responseHandlers

Fields inherited from class org.apache.geronimo.javamail.util.MailConnection

AUTHENTICATION_CRAMMD5, AUTHENTICATION_DIGESTMD5, AUTHENTICATION_LOGIN, AUTHENTICATION_PLAIN, authentications, authid, capabilities, CAPABILITY_STARTTLS, CR, debug, debugStream, DEFAULT_MAIL_HOST, defaultPort, inputStream, LF, localAddress, localHost, localPort, MAIL_AUTH, MAIL_AUTHORIZATIONID, MAIL_ENCODE_TRACE, MAIL_FACTORY_CLASS, MAIL_FACTORY_FALLBACK, MAIL_FACTORY_PORT, MAIL_LOCALADDRESS, MAIL_LOCALHOST, MAIL_LOCALPORT, MAIL_LOGIN_DISABLE, MAIL_PLAIN_DISABLE, MAIL_PORT, MAIL_SASL_ENABLE, MAIL_SASL_MECHANISMS, MAIL_SASL_REALM, MAIL_SSL_CIPHERSUITES, MAIL_SSL_ENABLE, MAIL_SSL_PROTOCOLS, MAIL_STARTTLS_ENABLE, MAIL_TIMEOUT, mechanisms, MIN_MILLIS, outputStream, password, props, protocol, realm, serverHost, serverPort, session, socket, sslConnection, timeout, TIMEOUT, username

Constructor Summary

IMAPConnection(ProtocolProperties props, IMAPConnectionPool pool)
Normal constructor for an IMAPConnection() object.

Method Summary

void	addACLRights(String mailbox, ACL acl) Add a set of ACL rights to a mailbox.
void	addResponseHandler(IMAPUntaggedResponseHandler h) Attach a handler for untagged responses to this connection.
void	appendMessage(String mailbox, Date messageDate, Flags messageFlags, byte[] messageData) Append a message to a mailbox, given the direct message data.
void	close() Close the connection.
void	closeMailbox() Deselect a mailbox when a folder returns a connection.
void	copyMessages(String messageSet, String target) Copy a range of messages to a target mailbox.
void	createMailbox(String mailbox) Create a mailbox.
void	deleteACL(String mailbox, String name) Delete an ACL item for a given user name from a target mailbox.
void	deleteMailbox(String mailbox) Delete a mailbox.
List	expungeMailbox() Tells the IMAP server to expunge messages marked for deletion.
protected IMAPFetchDataItem	extractFetchDataItem(long sequenceNumber, int type) Extract a fetch response data item from the queued elements.
protected List	extractFetchDataItems(int type) Extract a all fetch responses that contain a given data item.
List	extractFetchResponses(int sequenceNumber) Extract all responses from the pending queue that are "FETCH" responses for a given message number.
IMAPUntaggedResponse	extractResponse(String type) Extract a single response from the pending queue that match a give keyword type.
List	extractResponses(String type) Extract all responses from the pending queue that match a give keyword type.
List	fetch(String messageSet, FetchProfile profile) Prefetch message information based on the request profile.
IMAPBody	fetchBody(int sequenceNumber, String section) Issue a FETCH command to retrieve the entire message body in one shot.
IMAPMessageText	fetchBodyPartText(int sequenceNumber, String section) Issue a FETCH command to retrieve the message text
IMAPBodyStructure	fetchBodyStructure(int sequenceNumber) Issue a FETCH command to retrieve the message BODYSTRUCTURE structure.
byte[]	fetchContent(int sequenceNumber) Fetch the message content.
byte[]	fetchContent(int sequenceNumber, String section) Fetch the message content.
List	fetchEnvelope(int sequenceNumber) Issue a fetch command to retrieve the message ENVELOPE structure.
Flags	fetchFlags(int sequenceNumber) Fetch the flag set for a given message sequence number.
InternetHeaders	fetchHeaders(int sequenceNumber, String part) Issue a FETCH command to retrieve the message RFC822.HEADERS structure containing the message headers (using PEEK).
Quota[]	fetchQuota(String root) Fetch QUOTA information from a named QUOTE root.
Quota[]	fetchQuotaRoot(String mailbox) Fetch the quota root information for a target mailbox.
IMAPMessageText	fetchText(int sequenceNumber) Issue a FETCH command to retrieve the message text
ACL[]	getACLRights(String mailbox) Get the ACL rights assigned to a given mailbox.
void	getCapability() Get the servers capabilities from the wire....
protected void	getConnection() Create a transport connection object and connect it to the target server.
String	getHost() Return the server host for this connection.
IMAPMailboxStatus	getMailboxStatus(String mailbox) Retrieve a complete set of status items for a mailbox.
Rights	getMyRights(String mailbox) Get the current user's ACL rights to a given mailbox.
IMAPNamespaceResponse	getNamespaces() Retrieve the user name space info from the server.
protected ClientAuthenticator	getSaslAuthenticator()
IMAPUid	getSequenceNumberForUid(long uid) Fetch the message number for a give UID.
List	getSequenceNumbersForUids(long start, long end) Fetch the message numbers for a consequetive range of UIDs.
IMAPUid	getUidForSequenceNumber(int sequenceNumber) Fetch the UID value for a target message number
boolean	hasCapability(String capability) Test if this connection has a given capability.
boolean	isAlive(long timeout) check to see if this connection is truely alive.
boolean	isClosed() Test if the connnection has been forcibly closed.
boolean	isStale(long timeout) Test if the connection has been sitting idle for longer than the set timeout period.
List	list(String mailbox, String pattern) Send an LIST command to the IMAP server, returning all LIST response information.
Rights[]	listACLRights(String mailbox, String name) List the ACL rights that a particular user has to a mailbox.
List	listSubscribed(String mailbox, String pattern) Send an LSUB command to the IMAP server, returning all LSUB response information.
protected boolean	login() Authenticate with the server, if necessary (or possible).
void	logout() Logs out from the server.
IMAPMailboxStatus	openMailbox(String mailbox, boolean readOnly) Select a mailbox, returning the accumulated status information about the mailbox returned with the response.
protected boolean	processLogin() Process a LOGIN using the LOGIN command instead of AUTHENTICATE.
protected boolean	processLogin(ClientAuthenticator authenticator) Process a login using the provided authenticator object.
protected boolean	processLoginAuthentication() Process SASL-type LOGIN authentication.
void	processPendingResponses() Process any untagged responses in the queue.
protected boolean	processPlainAuthentication() Process SASL-type PLAIN authentication.
protected boolean	processSaslAuthentication() Process SASL-type authentication.
boolean	protocolConnect(String host, int port, String authid, String realm, String username, String password) Connect to the server and do the initial handshaking.
void	queuePendingResponse(IMAPUntaggedResponse response) Add a response to the pending untagged response queue.
IMAPTaggedResponse	receiveResponse() Get a reply line for an IMAP command.
void	removeACLRights(String mailbox, ACL acl) Remove an ACL from a given mailbox.
void	removeResponseHandler(IMAPUntaggedResponseHandler h) Remove a response handler from the connection.
void	renameMailbox(String oldName, String newName) Rename a mailbox.
int[]	searchMailbox(SearchTerm term)
int[]	searchMailbox(String messages, SearchTerm term) Send a search to the IMAP server using the specified messages selector and search term.
int[]	searchMailbox(String messages, SearchTerm term, String charset) Send a search to the IMAP server using the specified messages selector and search term.
IMAPTaggedResponse	sendCommand(IMAPCommand data) Sends a command down the socket, returning the server response.
IMAPTaggedResponse	sendCommand(String data) Sends a command down the socket, returning the server response.
IMAPTaggedResponse	sendLine(byte[] data) Sends a message down the socket and terminates with the appropriate CRLF
IMAPTaggedResponse	sendLine(byte[] data, int offset, int length) Sends a message down the socket and terminates with the appropriate CRLF
IMAPTaggedResponse	sendLine(String data) Sends a message down the socket and terminates with the appropriate CRLF
void	sendSimpleCommand(IMAPCommand data) Process a simple command/response sequence between the client and the server.
void	sendSimpleCommand(String data) Process a simple command/response sequence between the client and the server.
void	setACLRights(String mailbox, ACL acl) Set the ACL rights for a mailbox.
void	setClosed() Tag this connection as having been closed by the server.
Flags	setFlags(int sequenceNumber, Flags flags, boolean set) Set the flags for a single message.
List	setFlags(String messageSet, Flags flags, boolean set) Set the flags for a range of messages.
void	setQuota(Quota quota) Set a Quota item for the currently accessed userid/folder resource.
void	subscribe(String mailbox) Subscribe to a give mailbox.
void	unsubscribe(String mailbox) Unsubscribe from a mailbox.
protected void	updateLastAccess() Update the last access time for the connection.
void	updateMailboxStatus() Make sure we have the latest status information available.

Methods inherited from class org.apache.geronimo.javamail.util.MailConnection

checkConnected, closeServerConnection, connect, debugOut, debugOut, getCapabilities, getConnectedSocket, getConnectedSSLSocket, getConnectedTLSSocket, getConnectionProperties, getConnectionStreams, getLocalHost, getLoginAuthenticator, getSaslMechanisms, getSASLRealm, getServerMechanisms, protocolConnect, selectSaslMechanisms, setLocalHost, setSASLRealm, supportsMechanism

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

CAPABILITY_LOGIN_DISABLED

protected static final String CAPABILITY_LOGIN_DISABLED

See Also:

Constant Field Values

pool

protected IMAPConnectionPool pool

reader

protected IMAPResponseStream reader

lastAccess

protected long lastAccess

responseHandlers

protected LinkedList responseHandlers

queuedResponses

protected List queuedResponses

closed

protected boolean closed

Constructor Detail

IMAPConnection

public IMAPConnection(ProtocolProperties props,
                      IMAPConnectionPool pool)

Normal constructor for an IMAPConnection() object.

Parameters:

props - The protocol properties abstraction containing our property modifiers.

pool -

Method Detail

protocolConnect

public boolean protocolConnect(String host,
                               int port,
                               String authid,
                               String realm,
                               String username,
                               String password)
                        throws MessagingException

Connect to the server and do the initial handshaking.

Throws:

MessagingException

updateLastAccess

protected void updateLastAccess()

Update the last access time for the connection.

isStale

public boolean isStale(long timeout)

Test if the connection has been sitting idle for longer than the set timeout period.

Parameters:

timeout - The allowed "freshness" interval.

Returns:

True if the connection has been active within the required interval, false if it has been sitting idle for too long.

close

public void close()
           throws MessagingException

Close the connection. On completion, we'll be disconnected from the server and unable to send more data.

Throws:

MessagingException

getConnection

protected void getConnection()
                      throws IOException,
                             MessagingException

Create a transport connection object and connect it to the target server.

Overrides:

getConnection in class MailConnection

Throws:

MessagingException

IOException

sendSimpleCommand

public void sendSimpleCommand(String data)
                       throws MessagingException

Process a simple command/response sequence between the client and the server. These are commands where the client is expecting them to "just work", and also will not directly process the reply information. Unsolicited untagged responses are dispatched to handlers, and a MessagingException will be thrown for any non-OK responses from the server.

Parameters:

data - The command data we're writing out.

Throws:

MessagingException

sendSimpleCommand

public void sendSimpleCommand(IMAPCommand data)
                       throws MessagingException

Process a simple command/response sequence between the client and the server. These are commands where the client is expecting them to "just work", and also will not directly process the reply information. Unsolicited untagged responses are dispatched to handlers, and a MessagingException will be thrown for any non-OK responses from the server.

Parameters:

data - The command data we're writing out.

Throws:

MessagingException

sendCommand

public IMAPTaggedResponse sendCommand(String data)
                               throws MessagingException

Sends a command down the socket, returning the server response.

Parameters:

data - The String form of the command.

Returns:

The tagged response information that terminates the command interaction.

Throws:

MessagingException

sendCommand

public IMAPTaggedResponse sendCommand(IMAPCommand data)
                               throws MessagingException

Sends a command down the socket, returning the server response.

Parameters:

data - An IMAPCommand object with the prepared command information.

Returns:

The tagged (or continuation) response information that terminates the command response sequence.

Throws:

MessagingException

sendLine

public IMAPTaggedResponse sendLine(String data)
                            throws MessagingException

Sends a message down the socket and terminates with the appropriate CRLF

Parameters:

data - The string data to send.

Returns:

An IMAPTaggedResponse item returned from the server.

Throws:

MessagingException

sendLine

public IMAPTaggedResponse sendLine(byte[] data)
                            throws MessagingException

Sends a message down the socket and terminates with the appropriate CRLF

Parameters:

data - The array of data to send to the server.

Returns:

The response item returned from the IMAP server.

Throws:

MessagingException

sendLine

public IMAPTaggedResponse sendLine(byte[] data,
                                   int offset,
                                   int length)
                            throws MessagingException

Sends a message down the socket and terminates with the appropriate CRLF

Parameters:

data - The source data array.

offset - The offset within the data array.

length - The length of data to send.

Returns:

The response line returned from the IMAP server.

Throws:

MessagingException

receiveResponse

public IMAPTaggedResponse receiveResponse()
                                   throws MessagingException

Get a reply line for an IMAP command.

Returns:

An IMAP reply object from the stream.

Throws:

MessagingException

getCapability

public void getCapability()
                   throws MessagingException

Get the servers capabilities from the wire....

Throws:

MessagingException

logout

public void logout()
            throws MessagingException

Logs out from the server.

Throws:

MessagingException

closeMailbox

public void closeMailbox()
                  throws MessagingException

Deselect a mailbox when a folder returns a connection.

Throws:

MessagingException

login

protected boolean login()
                 throws MessagingException

Authenticate with the server, if necessary (or possible).

Returns:

true if we were able to authenticate correctly, false for authentication failures.

Throws:

MessagingException

processSaslAuthentication

protected boolean processSaslAuthentication()
                                     throws MessagingException

Process SASL-type authentication.

Returns:

Returns true if the server support a SASL authentication mechanism and accepted reponse challenges.

Throws:

MessagingException

getSaslAuthenticator

protected ClientAuthenticator getSaslAuthenticator()

processPlainAuthentication

protected boolean processPlainAuthentication()
                                      throws MessagingException

Process SASL-type PLAIN authentication.

Returns:

Returns true if the login is accepted.

Throws:

MessagingException

processLoginAuthentication

protected boolean processLoginAuthentication()
                                      throws MessagingException

Process SASL-type LOGIN authentication.

Returns:

Returns true if the login is accepted.

Throws:

MessagingException

processLogin

protected boolean processLogin()
                        throws MessagingException

Process a LOGIN using the LOGIN command instead of AUTHENTICATE.

Returns:

true if the command succeeded, false for any authentication failures.

Throws:

MessagingException

processLogin

protected boolean processLogin(ClientAuthenticator authenticator)
                        throws MessagingException

Process a login using the provided authenticator object. NB: This method is synchronized because we have a multi-step process going on here. No other commands should be sent to the server until we complete.

Returns:

Returns true if the server support a SASL authentication mechanism and accepted reponse challenges.

Throws:

MessagingException

getHost

public String getHost()

Return the server host for this connection.

Overrides:

getHost in class MailConnection

Returns:

The String name of the server host.

addResponseHandler

public void addResponseHandler(IMAPUntaggedResponseHandler h)

Attach a handler for untagged responses to this connection.

Parameters:

h - The new untagged response handler.

removeResponseHandler

public void removeResponseHandler(IMAPUntaggedResponseHandler h)

Remove a response handler from the connection.

Parameters:

h - The handler to remove.

queuePendingResponse

public void queuePendingResponse(IMAPUntaggedResponse response)

Add a response to the pending untagged response queue.

Parameters:

response - The response to add.

processPendingResponses

public void processPendingResponses()
                             throws MessagingException

Process any untagged responses in the queue. This will clear out the queue, and send each response to the registered untagged response handlers.

Throws:

MessagingException

extractResponse

public IMAPUntaggedResponse extractResponse(String type)

Extract a single response from the pending queue that match a give keyword type. All matching responses are removed from the pending queue.

Parameters:

type - The string name of the keyword.

Returns:

A List of all matching queued responses.

extractResponses

public List extractResponses(String type)

Extract all responses from the pending queue that match a give keyword type. All matching responses are removed from the pending queue.

Parameters:

type - The string name of the keyword.

Returns:

A List of all matching queued responses.

extractFetchResponses

public List extractFetchResponses(int sequenceNumber)

Extract all responses from the pending queue that are "FETCH" responses for a given message number. All matching responses are removed from the pending queue.

Parameters:

type - The string name of the keyword.

Returns:

A List of all matching queued responses.

extractFetchDataItem

protected IMAPFetchDataItem extractFetchDataItem(long sequenceNumber,
                                                 int type)

Extract a fetch response data item from the queued elements.

Parameters:

sequenceNumber - The message number we're interested in. Fetch responses for other messages will be skipped.

type - The type of body element we need. It is assumed that only one item for the given message number will exist in the queue. The located item will be returned, and that fetch response will be removed from the pending queue.

Returns:

The target data item, or null if a match is not found.

extractFetchDataItems

protected List extractFetchDataItems(int type)

Extract a all fetch responses that contain a given data item.

Parameters:

type - The type of body element we need. It is assumed that only one item for the given message number will exist in the queue. The located item will be returned, and that fetch response will be removed from the pending queue.

Returns:

A List of all matching Fetch responses.

updateMailboxStatus

public void updateMailboxStatus()
                         throws MessagingException

Make sure we have the latest status information available. We retreive this by sending a NOOP command to the server, and processing any untagged responses we get back.

Throws:

MessagingException

isAlive

public boolean isAlive(long timeout)

check to see if this connection is truely alive.

Parameters:

timeout - The timeout value to control how often we ping the server to see if we're still good.

Returns:

true if the server is responding to requests, false for any connection errors. This will also update the folder status by processing returned unsolicited messages.

fetchEnvelope

public List fetchEnvelope(int sequenceNumber)
                   throws MessagingException

Issue a fetch command to retrieve the message ENVELOPE structure.

Parameters:

sequenceNumber - The sequence number of the message.

Returns:

The IMAPResponse item containing the ENVELOPE information.

Throws:

MessagingException

fetchBodyStructure

public IMAPBodyStructure fetchBodyStructure(int sequenceNumber)
                                     throws MessagingException

Issue a FETCH command to retrieve the message BODYSTRUCTURE structure.

Parameters:

sequenceNumber - The sequence number of the message.

Returns:

The IMAPBodyStructure item for the message. All other untagged responses are queued for processing.

Throws:

MessagingException

fetchHeaders

public InternetHeaders fetchHeaders(int sequenceNumber,
                                    String part)
                             throws MessagingException

Issue a FETCH command to retrieve the message RFC822.HEADERS structure containing the message headers (using PEEK).

Parameters:

sequenceNumber - The sequence number of the message.

Returns:

The IMAPRFC822Headers item for the message. All other untagged responses are queued for processing.

Throws:

MessagingException

fetchText

public IMAPMessageText fetchText(int sequenceNumber)
                          throws MessagingException

Issue a FETCH command to retrieve the message text

Parameters:

sequenceNumber - The sequence number of the message.

Returns:

The IMAPMessageText item for the message. All other untagged responses are queued for processing.

Throws:

MessagingException

fetchBodyPartText

public IMAPMessageText fetchBodyPartText(int sequenceNumber,
                                         String section)
                                  throws MessagingException

Issue a FETCH command to retrieve the message text

Parameters:

sequenceNumber - The sequence number of the message.

Returns:

The IMAPMessageText item for the message. All other untagged responses are queued for processing.

Throws:

MessagingException

fetchBody

public IMAPBody fetchBody(int sequenceNumber,
                          String section)
                   throws MessagingException

Issue a FETCH command to retrieve the entire message body in one shot. This may also be used to fetch an embedded message part as a unit.

Parameters:

sequenceNumber - The sequence number of the message.

section - The section number to fetch. If null, the entire body of the message is retrieved.

Returns:

The IMAPBody item for the message. All other untagged responses are queued for processing.

Throws:

MessagingException

fetchContent

public byte[] fetchContent(int sequenceNumber)
                    throws MessagingException

Fetch the message content. This sorts out which method should be used based on the server capability.

Parameters:

sequenceNumber - The sequence number of the target message.

Returns:

The byte[] content information.

Throws:

MessagingException

fetchContent

public byte[] fetchContent(int sequenceNumber,
                           String section)
                    throws MessagingException

Fetch the message content. This sorts out which method should be used based on the server capability.

Parameters:

sequenceNumber - The sequence number of the target message.

Returns:

The byte[] content information.

Throws:

MessagingException

list

public List list(String mailbox,
                 String pattern)
          throws MessagingException

Send an LIST command to the IMAP server, returning all LIST response information.

Parameters:

mailbox - The reference mailbox name sent on the command.

pattern - The match pattern used on the name.

Returns:

A List of all LIST response information sent back from the server.

Throws:

MessagingException

listSubscribed

public List listSubscribed(String mailbox,
                           String pattern)
                    throws MessagingException

Send an LSUB command to the IMAP server, returning all LSUB response information.

Parameters:

mailbox - The reference mailbox name sent on the command.

pattern - The match pattern used on the name.

Returns:

A List of all LSUB response information sent back from the server.

Throws:

MessagingException

subscribe

public void subscribe(String mailbox)
               throws MessagingException

Subscribe to a give mailbox.

Parameters:

mailbox - The desired mailbox name.

Throws:

MessagingException

unsubscribe

public void unsubscribe(String mailbox)
                 throws MessagingException

Unsubscribe from a mailbox.

Parameters:

mailbox - The mailbox to remove.

Throws:

MessagingException

createMailbox

public void createMailbox(String mailbox)
                   throws MessagingException

Create a mailbox.

Parameters:

mailbox - The desired new mailbox name (fully qualified);

Throws:

MessagingException

deleteMailbox

public void deleteMailbox(String mailbox)
                   throws MessagingException

Delete a mailbox.

Parameters:

mailbox - The target mailbox name (fully qualified);

Throws:

MessagingException

renameMailbox

public void renameMailbox(String oldName,
                          String newName)
                   throws MessagingException

Rename a mailbox.

Parameters:

mailbox - The target mailbox name (fully qualified);

Throws:

MessagingException

getMailboxStatus

public IMAPMailboxStatus getMailboxStatus(String mailbox)
                                   throws MessagingException

Retrieve a complete set of status items for a mailbox.

Parameters:

mailbox - The mailbox name.

Returns:

An IMAPMailboxStatus item filled in with the STATUS responses.

Throws:

MessagingException

openMailbox

public IMAPMailboxStatus openMailbox(String mailbox,
                                     boolean readOnly)
                              throws MessagingException

Select a mailbox, returning the accumulated status information about the mailbox returned with the response.

Parameters:

mailbox - The desired mailbox name.

readOnly - The open mode. If readOnly is true, the mailbox is opened using EXAMINE rather than SELECT.

Returns:

A status object containing the mailbox particulars.

Throws:

MessagingException

expungeMailbox

public List expungeMailbox()
                    throws MessagingException

Tells the IMAP server to expunge messages marked for deletion. The server will send us an untagged EXPUNGE message back for each deleted message. For explicit expunges we request, we'll grabbed the untagged responses here, rather than force them to be handled as pending responses. The caller will handle the updates directly.

Throws:

MessagingException

searchMailbox

public int[] searchMailbox(SearchTerm term)
                    throws MessagingException

Throws:

MessagingException

searchMailbox

public int[] searchMailbox(String messages,
                           SearchTerm term)
                    throws MessagingException

Send a search to the IMAP server using the specified messages selector and search term. This figures out what to do with CHARSET on the SEARCH command.

Parameters:

messages - The list of messages (comma-separated numbers or "ALL").

term - The desired search criteria

Returns:

Returns an int[] array of message numbers for all matched messages.

Throws:

MessagingException

searchMailbox

public int[] searchMailbox(String messages,
                           SearchTerm term,
                           String charset)
                    throws MessagingException

Send a search to the IMAP server using the specified messages selector and search term.

Parameters:

messages - The list of messages (comma-separated numbers or "ALL").

charset - The charset specifier to send to the server. If null, then the CHARSET keyword is omitted.

term - The desired search criteria

Returns:

Returns an int[] array of message numbers for all matched messages.

Throws:

MessagingException

appendMessage

public void appendMessage(String mailbox,
                          Date messageDate,
                          Flags messageFlags,
                          byte[] messageData)
                   throws MessagingException

Append a message to a mailbox, given the direct message data.

Parameters:

mailbox - The target mailbox name.

messageFlags - The initial flag set for the appended message.

messageDate - The received date the message is created with,

messageData - The RFC822 Message data stored on the server.

Throws:

MessagingException

fetchFlags

public Flags fetchFlags(int sequenceNumber)
                 throws MessagingException

Fetch the flag set for a given message sequence number.

Parameters:

sequenceNumber - The message sequence number.

Returns:

The Flags defined for this message.

Throws:

MessagingException

setFlags

public List setFlags(String messageSet,
                     Flags flags,
                     boolean set)
              throws MessagingException

Set the flags for a range of messages.

Parameters:

messageSet - The set of message numbers.

flags - The new flag settings.

set - true if the flags should be set, false for a clear operation.

Returns:

A list containing all of the responses with the new flag values.

Throws:

MessagingException

setFlags

public Flags setFlags(int sequenceNumber,
                      Flags flags,
                      boolean set)
               throws MessagingException

Set the flags for a single message.

Parameters:

sequenceNumber - The sequence number of target message.

flags - The new flag settings.

set - true if the flags should be set, false for a clear operation.

Throws:

MessagingException

copyMessages

public void copyMessages(String messageSet,
                         String target)
                  throws MessagingException

Copy a range of messages to a target mailbox.

Parameters:

messageSet - The set of message numbers.

target - The target mailbox name.

Throws:

MessagingException

getSequenceNumberForUid

public IMAPUid getSequenceNumberForUid(long uid)
                                throws MessagingException

Fetch the message number for a give UID.

Parameters:

uid - The target UID

Returns:

An IMAPUid object containing the mapping information.

Throws:

MessagingException

getSequenceNumbersForUids

public List getSequenceNumbersForUids(long start,
                                      long end)
                               throws MessagingException

Fetch the message numbers for a consequetive range of UIDs.

Parameters:

start - The start of the range.

end - The end of the uid range.

Returns:

A list of UID objects containing the mappings.

Throws:

MessagingException

getUidForSequenceNumber

public IMAPUid getUidForSequenceNumber(int sequenceNumber)
                                throws MessagingException

Fetch the UID value for a target message number

Parameters:

sequenceNumber - The target message number.

Returns:

An IMAPUid object containing the mapping information.

Throws:

MessagingException

getNamespaces

public IMAPNamespaceResponse getNamespaces()
                                    throws MessagingException

Retrieve the user name space info from the server.

Returns:

An IMAPNamespace response item with the information. If the server doesn't support the namespace extension, an empty one is returned.

Throws:

MessagingException

fetch

public List fetch(String messageSet,
                  FetchProfile profile)
           throws MessagingException

Prefetch message information based on the request profile. We'll return all of the fetch information to the requesting Folder, which will sort out what goes where.

Parameters:

messageSet - The set of message numbers we need to fetch.

profile - The profile of the required information.

Returns:

All FETCH responses resulting from the command.

Throws:

MessagingException

setACLRights

public void setACLRights(String mailbox,
                         ACL acl)
                  throws MessagingException

Set the ACL rights for a mailbox. This replaces any existing ACLs defined.

Parameters:

mailbox - The target mailbox.

acl - The new ACL to be used for the mailbox.

Throws:

MessagingException

addACLRights

public void addACLRights(String mailbox,
                         ACL acl)
                  throws MessagingException

Add a set of ACL rights to a mailbox.

Parameters:

mailbox - The mailbox to alter.

acl - The ACL to add.

Throws:

MessagingException

removeACLRights

public void removeACLRights(String mailbox,
                            ACL acl)
                     throws MessagingException

Remove an ACL from a given mailbox.

Parameters:

mailbox - The mailbox to alter.

acl - The particular ACL to revoke.

Throws:

MessagingException

getACLRights

public ACL[] getACLRights(String mailbox)
                   throws MessagingException

Get the ACL rights assigned to a given mailbox.

Parameters:

mailbox - The target mailbox.

Returns:

The an array of ACL items describing the access rights to the mailbox.

Throws:

MessagingException

getMyRights

public Rights getMyRights(String mailbox)
                   throws MessagingException

Get the current user's ACL rights to a given mailbox.

Parameters:

mailbox - The target mailbox.

Returns:

The Rights associated with this mailbox.

Throws:

MessagingException

listACLRights

public Rights[] listACLRights(String mailbox,
                              String name)
                       throws MessagingException

List the ACL rights that a particular user has to a mailbox.

Parameters:

mailbox - The target mailbox.

name - The user we're querying.

Returns:

An array of rights the use has to this mailbox.

Throws:

MessagingException

deleteACL

public void deleteACL(String mailbox,
                      String name)
               throws MessagingException

Delete an ACL item for a given user name from a target mailbox.

Parameters:

mailbox - The mailbox we're altering.

name - The user name.

Throws:

MessagingException

fetchQuotaRoot

public Quota[] fetchQuotaRoot(String mailbox)
                       throws MessagingException

Fetch the quota root information for a target mailbox.

Parameters:

mailbox - The mailbox of interest.

Returns:

An array of quotas describing all of the quota roots that apply to the target mailbox.

Throws:

MessagingException

fetchQuota

public Quota[] fetchQuota(String root)
                   throws MessagingException

Fetch QUOTA information from a named QUOTE root.

Parameters:

root - The target root name.

Returns:

An array of Quota items associated with that root name.

Throws:

MessagingException

setQuota

public void setQuota(Quota quota)
              throws MessagingException

Set a Quota item for the currently accessed userid/folder resource.

Parameters:

quota - The new QUOTA information.

Throws:

MessagingException

hasCapability

public boolean hasCapability(String capability)

Test if this connection has a given capability.

Overrides:

hasCapability in class MailConnection

Parameters:

capability - The capability name.

Returns:

true if this capability is in the list, false for a mismatch.

setClosed

public void setClosed()

Tag this connection as having been closed by the server. This will not be returned to the connection pool.

isClosed

public boolean isClosed()

Test if the connnection has been forcibly closed.

Returns:

True if the server disconnected the connection.