gnu.inet.imap

Class IMAPConnection

Implemented Interfaces:
IMAPConstants

public class IMAPConnection
extends java.lang.Object
implements IMAPConstants

The protocol class implementing IMAP4rev1.

Version:
$Revision: 1.19 $ $Date: 2004/08/07 14:39:46 $

Author:
Chris Burdess

Nested Class Summary

Field Summary

protected static int
DEFAULT_PORT
The default IMAP port.
protected static int
DEFAULT_SSL_PORT
The default IMAP-SSL port.
protected static java.lang.String
TAG_PREFIX
Prefix for tags.
protected static java.lang.String
US_ASCII
The encoding used to create strings for IMAP commands.
protected java.util.List
asyncResponses
List of responses received asynchronously.
protected IMAPResponseTokenizer
in
The tokenizer used to read IMAP responses from.
protected CRLFOutputStream
out
The output stream.
protected java.net.Socket
socket
The socket used for communication with the server.

Fields inherited from interface gnu.inet.imap.IMAPConstants

ALERT, APPEND, AUTHENTICATE, BAD, BODY, BODYSTRUCTURE, BODY_PEEK, BYE, CAPABILITY, CHECK, CLOSE, COPY, CRAM_MD5, CREATE, DELETE, ENVELOPE, EXAMINE, EXISTS, EXPUNGE, FETCH, FETCH_FLAGS, FLAGS, FLAG_ANSWERED, FLAG_DELETED, FLAG_DRAFT, FLAG_FLAGGED, FLAG_RECENT, FLAG_SEEN, GSSAPI, HEADER, HEADER_FIELDS, HEADER_FIELDS_NOT, INTERNALDATE, KERBEROS_V4, LIST, LIST_MARKED, LIST_NOINFERIORS, LIST_NOSELECT, LIST_UNMARKED, LOGIN, LOGINDISABLED, LOGOUT, LSUB, MESSAGES, NEWNAME, NIL, NO, NOOP, OK, PARSE, PERMANENTFLAGS, PREAUTH, READ_ONLY, READ_WRITE, RECENT, RENAME, RFC822, RFC822_HEADER, RFC822_SIZE, RFC822_TEXT, SEARCH, SEARCH_ALL, SEARCH_ANSWERED, SEARCH_BCC, SEARCH_BEFORE, SEARCH_BODY, SEARCH_CC, SEARCH_DELETED, SEARCH_DRAFT, SEARCH_FLAGGED, SEARCH_FROM, SEARCH_HEADER, SEARCH_KEYWORD, SEARCH_LARGER, SEARCH_NEW, SEARCH_NOT, SEARCH_OLD, SEARCH_ON, SEARCH_OR, SEARCH_RECENT, SEARCH_SEEN, SEARCH_SENTBEFORE, SEARCH_SENTON, SEARCH_SENTSINCE, SEARCH_SINCE, SEARCH_SMALLER, SEARCH_SUBJECT, SEARCH_TEXT, SEARCH_TO, SEARCH_UID, SEARCH_UNANSWERED, SEARCH_UNDELETED, SEARCH_UNDRAFT, SEARCH_UNFLAGGED, SEARCH_UNKEYWORD, SEARCH_UNSEEN, SELECT, SKEY, STARTTLS, STATUS, STORE, SUBSCRIBE, TRYCREATE, UID, UIDNEXT, UIDVALIDITY, UNSEEN, UNSUBSCRIBE

Constructor Summary

IMAPConnection(java.lang.String host, int port)
Creates a new connection.
IMAPConnection(java.lang.String host, int port, int connectionTimeout, int timeout, boolean debug)
Creates a new connection.
IMAPConnection(java.lang.String host, int port, int connectionTimeout, int timeout, boolean secure, javax.net.ssl.TrustManager tm, boolean debug)
Creates a new connection.
IMAPConnection(java.lang.String host, int port, javax.net.ssl.TrustManager tm)
Creates a new secure connection using the specified trust manager.

Method Summary

boolean
alertsPending()
Indicates if there are alerts pending for the user-agent.
boolean
append(java.lang.String mailbox, java.lang.String[] flags, byte[] content)
Append a message to the specified mailbox.
boolean
authenticate(java.lang.String mechanism, java.lang.String username, java.lang.String password)
Authenticates the connection using the specified SASL mechanism, username, and password.
java.util.List
capability()
Returns a list of the capabilities of the IMAP server.
void
check()
Request a checkpoint of the currently selected mailbox.
boolean
close()
Permanently remove all messages that have the \Deleted flags set, and close the mailbox.
boolean
copy(int[] messages, java.lang.String mailbox)
Copies the specified messages to the end of the destination mailbox.
boolean
create(java.lang.String mailbox)
Creates a mailbox with the specified name.
boolean
delete(java.lang.String mailbox)
Deletes the mailbox with the specified name.
MailboxStatus
examine(java.lang.String mailbox)
Selects the specified mailbox.
int[]
expunge()
Permanently removes all messages that have the \Delete flag set.
MessageStatus[]
fetch(int start, int end, java.lang.String[] fetchCommands)
Retrieves data associated with the specified range of messages in the mailbox.
MessageStatus
fetch(int message, java.lang.String[] fetchCommands)
Retrieves data associated with the specified message in the mailbox.
MessageStatus[]
fetch(int[] messages, java.lang.String[] fetchCommands)
Retrieves data associated with messages in the mailbox.
java.lang.String[]
getAlerts()
Returns the pending alerts for the user-agent as an array.
protected javax.net.ssl.SSLSocketFactory
getSSLSocketFactory(javax.net.ssl.TrustManager tm)
Returns a configured SSLSocketFactory to use in creating new SSL sockets.
protected boolean
invokeSimpleCommand(java.lang.String command)
Sends the specified IMAP command.
ListEntry[]
list(java.lang.String reference, java.lang.String mailbox)
Returns a subset of names from the compete set of names available to the client.
protected ListEntry[]
listImpl(java.lang.String command, java.lang.String reference, java.lang.String mailbox)
boolean
login(java.lang.String username, java.lang.String password)
Login to the connection using the username and password method.
void
logout()
Logout this connection.
ListEntry[]
lsub(java.lang.String reference, java.lang.String mailbox)
Returns a subset of subscribed names.
protected java.lang.String
newTag()
Returns a new tag for a command.
MailboxStatus
noop()
Ping the server.
protected IMAPResponse
readResponse()
Reads an IMAP response from the server.
boolean
rename(java.lang.String source, java.lang.String target)
Renames the source mailbox to the specified name.
int[]
search(java.lang.String charset, java.lang.String[] criteria)
Searches the currently selected mailbox for messages matching the specified criteria.
MailboxStatus
select(java.lang.String mailbox)
Selects the specified mailbox.
protected MailboxStatus
selectImpl(java.lang.String mailbox, java.lang.String command)
protected void
sendCommand(java.lang.String tag, java.lang.String command)
Sends the specified IMAP tagged command to the server.
void
setAnsiDebug(boolean flag)
Sets whether debugging output should use ANSI colour escape sequences.
boolean
starttls()
Attempts to start TLS on the specified connection.
boolean
starttls(javax.net.ssl.TrustManager tm)
Attempts to start TLS on the specified connection.
MailboxStatus
status(java.lang.String mailbox, java.lang.String[] statusNames)
Requests the status of the specified mailbox.
MessageStatus[]
store(int start, int end, java.lang.String flagCommand, java.lang.String[] flags)
Alters data associated with the specified range of messages in the mailbox.
MessageStatus
store(int message, java.lang.String flagCommand, java.lang.String[] flags)
Alters data associated with the specified message in the mailbox.
MessageStatus[]
store(int[] messages, java.lang.String flagCommand, java.lang.String[] flags)
Alters data associated with messages in the mailbox.
boolean
subscribe(java.lang.String mailbox)
Adds the specified mailbox to the set of subscribed mailboxes as returned by the LSUB command.
MessageStatus
uidFetch(long uid, java.lang.String[] fetchCommands)
Retrieves data associated with the specified message in the mailbox.
MessageStatus[]
uidFetch(long start, long end, java.lang.String[] fetchCommands)
Retrieves data associated with the specified range of messages in the mailbox.
MessageStatus[]
uidFetch(long[] uids, java.lang.String[] fetchCommands)
Retrieves data associated with messages in the mailbox.
MessageStatus
uidStore(long uid, java.lang.String flagCommand, java.lang.String[] flags)
Alters data associated with the specified message in the mailbox.
MessageStatus[]
uidStore(long start, long end, java.lang.String flagCommand, java.lang.String[] flags)
Alters data associated with the specified range of messages in the mailbox.
MessageStatus[]
uidStore(long[] uids, java.lang.String flagCommand, java.lang.String[] flags)
Alters data associated with messages in the mailbox.
boolean
unsubscribe(java.lang.String mailbox)
Removes the specified mailbox from the set of subscribed mailboxes as returned by the LSUB command.
protected boolean
updateMailboxStatus(MailboxStatus ms, java.lang.String id, IMAPResponse response)

Field Details

DEFAULT_PORT

protected static final int DEFAULT_PORT
The default IMAP port.

Field Value:
143


DEFAULT_SSL_PORT

protected static final int DEFAULT_SSL_PORT
The default IMAP-SSL port.

Field Value:
993


TAG_PREFIX

protected static final java.lang.String TAG_PREFIX
Prefix for tags.

Field Value:
"A"


US_ASCII

protected static final java.lang.String US_ASCII
The encoding used to create strings for IMAP commands.

Field Value:
"US-ASCII"


asyncResponses

protected java.util.List asyncResponses
List of responses received asynchronously.


in

protected IMAPResponseTokenizer in
The tokenizer used to read IMAP responses from.


out

protected CRLFOutputStream out
The output stream.


socket

protected java.net.Socket socket
The socket used for communication with the server.

Constructor Details

IMAPConnection

public IMAPConnection(java.lang.String host,
                      int port)
            throws java.net.UnknownHostException,
                   java.io.IOException
Creates a new connection.

Parameters:
host - the name of the host to connect to
port - the port to connect to, or -1 for the default


IMAPConnection

public IMAPConnection(java.lang.String host,
                      int port,
                      int connectionTimeout,
                      int timeout,
                      boolean debug)
            throws java.net.UnknownHostException,
                   java.io.IOException
Creates a new connection.

Parameters:
host - the name of the host to connect to
port - the port to connect to, or -1 for the default
connectionTimeout - the socket connection timeout
timeout - the socket timeout
debug - log debugging information


IMAPConnection

public IMAPConnection(java.lang.String host,
                      int port,
                      int connectionTimeout,
                      int timeout,
                      boolean secure,
                      javax.net.ssl.TrustManager tm,
                      boolean debug)
            throws java.net.UnknownHostException,
                   java.io.IOException
Creates a new connection.

Parameters:
host - the name of the host to connect to
port - the port to connect to, or -1 for the default
connectionTimeout - the socket connection timeout
timeout - the socket timeout
secure - if an IMAP-SSL connection should be made
tm - a trust manager used to check SSL certificates, or null to use the default
debug - log debugging information


IMAPConnection

public IMAPConnection(java.lang.String host,
                      int port,
                      javax.net.ssl.TrustManager tm)
            throws java.net.UnknownHostException,
                   java.io.IOException
Creates a new secure connection using the specified trust manager.

Parameters:
host - the name of the host to connect to
port - the port to connect to, or -1 for the default
tm - a trust manager used to check SSL certificates, or null to use the default

Method Details

alertsPending

public boolean alertsPending()
Indicates if there are alerts pending for the user-agent.


append

public boolean append(java.lang.String mailbox,
                      java.lang.String[] flags,
                      byte[] content)
            throws java.io.IOException
Append a message to the specified mailbox. This method returns an OutputStream to which the message should be written and then closed.

Parameters:
mailbox - the mailbox name
flags - optional list of flags to specify for the message
content - the message body (including headers)

Returns:
true if successful, false if error in flags/text


authenticate

public boolean authenticate(java.lang.String mechanism,
                            java.lang.String username,
                            java.lang.String password)
            throws java.io.IOException
Authenticates the connection using the specified SASL mechanism, username, and password.

Parameters:
mechanism - a SASL authentication mechanism, e.g. LOGIN, PLAIN, CRAM-MD5, GSSAPI
username - the authentication principal
password - the authentication credentials

Returns:
true if authentication was successful, false otherwise


capability

public java.util.List capability()
            throws java.io.IOException
Returns a list of the capabilities of the IMAP server.


check

public void check()
            throws java.io.IOException
Request a checkpoint of the currently selected mailbox.


close

public boolean close()
            throws java.io.IOException
Permanently remove all messages that have the \Deleted flags set, and close the mailbox.

Returns:
true if successful, false if no mailbox was selected


copy

public boolean copy(int[] messages,
                    java.lang.String mailbox)
            throws java.io.IOException
Copies the specified messages to the end of the destination mailbox.

Parameters:
messages - the message numbers
mailbox - the destination mailbox


create

public boolean create(java.lang.String mailbox)
            throws java.io.IOException
Creates a mailbox with the specified name.

Parameters:
mailbox - the mailbox name

Returns:
true if the mailbox was successfully created, false otherwise


delete

public boolean delete(java.lang.String mailbox)
            throws java.io.IOException
Deletes the mailbox with the specified name.

Parameters:
mailbox - the mailbox name

Returns:
true if the mailbox was successfully deleted, false otherwise


examine

public MailboxStatus examine(java.lang.String mailbox)
            throws java.io.IOException
Selects the specified mailbox. The mailbox is identified as read-only.

Parameters:
mailbox - the mailbox name

Returns:
a MailboxStatus containing the state of the selected mailbox


expunge

public int[] expunge()
            throws java.io.IOException
Permanently removes all messages that have the \Delete flag set.

Returns:
the numbers of the messages expunged


fetch

public MessageStatus[] fetch(int start,
                             int end,
                             java.lang.String[] fetchCommands)
            throws java.io.IOException
Retrieves data associated with the specified range of messages in the mailbox.

Parameters:
start - the message number of the first message
end - the message number of the last message
fetchCommands - the fetch commands, e.g. FLAGS


fetch

public MessageStatus fetch(int message,
                           java.lang.String[] fetchCommands)
            throws java.io.IOException
Retrieves data associated with the specified message in the mailbox.

Parameters:
message - the message number
fetchCommands - the fetch commands, e.g. FLAGS


fetch

public MessageStatus[] fetch(int[] messages,
                             java.lang.String[] fetchCommands)
            throws java.io.IOException
Retrieves data associated with messages in the mailbox.

Parameters:
messages - the message numbers
fetchCommands - the fetch commands, e.g. FLAGS


getAlerts

public java.lang.String[] getAlerts()
Returns the pending alerts for the user-agent as an array.


getSSLSocketFactory

protected javax.net.ssl.SSLSocketFactory getSSLSocketFactory(javax.net.ssl.TrustManager tm)
            throws java.security.GeneralSecurityException
Returns a configured SSLSocketFactory to use in creating new SSL sockets.

Parameters:
tm - an optional trust manager to use


invokeSimpleCommand

protected boolean invokeSimpleCommand(java.lang.String command)
            throws java.io.IOException
Sends the specified IMAP command.

Parameters:
command - the command

Returns:
true if OK was received, or false if NO was received

Throws:
java.io.IOException - if BAD was received or an I/O error occurred


list

public ListEntry[] list(java.lang.String reference,
                        java.lang.String mailbox)
            throws java.io.IOException
Returns a subset of names from the compete set of names available to the client.

Parameters:
reference - the context relative to which mailbox names are defined
mailbox - a mailbox name, possibly including IMAP wildcards


listImpl

protected ListEntry[] listImpl(java.lang.String command,
                               java.lang.String reference,
                               java.lang.String mailbox)
            throws java.io.IOException


login

public boolean login(java.lang.String username,
                     java.lang.String password)
            throws java.io.IOException
Login to the connection using the username and password method.

Parameters:
username - the authentication principal
password - the authentication credentials

Returns:
true if authentication was successful, false otherwise


logout

public void logout()
            throws java.io.IOException
Logout this connection. Underlying network resources will be freed.


lsub

public ListEntry[] lsub(java.lang.String reference,
                        java.lang.String mailbox)
            throws java.io.IOException
Returns a subset of subscribed names.

See Also:
list(java.lang.String,java.lang.String)


newTag

protected java.lang.String newTag()
Returns a new tag for a command.


noop

public MailboxStatus noop()
            throws java.io.IOException
Ping the server. If a change in mailbox state is detected, a new mailbox status is returned, otherwise this method returns null.


readResponse

protected IMAPResponse readResponse()
            throws java.io.IOException
Reads an IMAP response from the server. The response will consist of either:
  • A tagged response corresponding to a pending command
  • An untagged error response
  • A continuation response


rename

public boolean rename(java.lang.String source,
                      java.lang.String target)
            throws java.io.IOException
Renames the source mailbox to the specified name.

Parameters:
source - the source mailbox name
target - the target mailbox name

Returns:
true if the mailbox was successfully renamed, false otherwise


search

public int[] search(java.lang.String charset,
                    java.lang.String[] criteria)
            throws java.io.IOException
Searches the currently selected mailbox for messages matching the specified criteria.


select

public MailboxStatus select(java.lang.String mailbox)
            throws java.io.IOException
Selects the specified mailbox. The mailbox is identified as read-write if writes are permitted.

Parameters:
mailbox - the mailbox name

Returns:
a MailboxStatus containing the state of the selected mailbox


selectImpl

protected MailboxStatus selectImpl(java.lang.String mailbox,
                                   java.lang.String command)
            throws java.io.IOException


sendCommand

protected void sendCommand(java.lang.String tag,
                           java.lang.String command)
            throws java.io.IOException
Sends the specified IMAP tagged command to the server.


setAnsiDebug

public void setAnsiDebug(boolean flag)
Sets whether debugging output should use ANSI colour escape sequences.


starttls

public boolean starttls()
            throws java.io.IOException
Attempts to start TLS on the specified connection. See RFC 2595 for details.

Returns:
true if successful, false otherwise


starttls

public boolean starttls(javax.net.ssl.TrustManager tm)
            throws java.io.IOException
Attempts to start TLS on the specified connection. See RFC 2595 for details.

Parameters:
tm - the custom trust manager to use

Returns:
true if successful, false otherwise


status

public MailboxStatus status(java.lang.String mailbox,
                            java.lang.String[] statusNames)
            throws java.io.IOException
Requests the status of the specified mailbox.


store

public MessageStatus[] store(int start,
                             int end,
                             java.lang.String flagCommand,
                             java.lang.String[] flags)
            throws java.io.IOException
Alters data associated with the specified range of messages in the mailbox.

Parameters:
start - the message number of the first message
end - the message number of the last message
flagCommand - FLAGS, +FLAGS, -FLAGS (or .SILENT versions)
flags - message flags to set

Returns:
a list of message-number to current flags


store

public MessageStatus store(int message,
                           java.lang.String flagCommand,
                           java.lang.String[] flags)
            throws java.io.IOException
Alters data associated with the specified message in the mailbox.

Parameters:
message - the message number
flagCommand - FLAGS, +FLAGS, -FLAGS (or .SILENT versions)
flags - message flags to set

Returns:
the message status


store

public MessageStatus[] store(int[] messages,
                             java.lang.String flagCommand,
                             java.lang.String[] flags)
            throws java.io.IOException
Alters data associated with messages in the mailbox.

Parameters:
messages - the message numbers
flagCommand - FLAGS, +FLAGS, -FLAGS (or .SILENT versions)
flags - message flags to set

Returns:
a list of message-number to current flags


subscribe

public boolean subscribe(java.lang.String mailbox)
            throws java.io.IOException
Adds the specified mailbox to the set of subscribed mailboxes as returned by the LSUB command.

Parameters:
mailbox - the mailbox name

Returns:
true if the mailbox was successfully subscribed, false otherwise


uidFetch

public MessageStatus uidFetch(long uid,
                              java.lang.String[] fetchCommands)
            throws java.io.IOException
Retrieves data associated with the specified message in the mailbox.

Parameters:
uid - the message UID
fetchCommands - the fetch commands, e.g. FLAGS


uidFetch

public MessageStatus[] uidFetch(long start,
                                long end,
                                java.lang.String[] fetchCommands)
            throws java.io.IOException
Retrieves data associated with the specified range of messages in the mailbox.

Parameters:
start - the message number of the first message
end - the message number of the last message
fetchCommands - the fetch commands, e.g. FLAGS


uidFetch

public MessageStatus[] uidFetch(long[] uids,
                                java.lang.String[] fetchCommands)
            throws java.io.IOException
Retrieves data associated with messages in the mailbox.

Parameters:
uids - the message UIDs
fetchCommands - the fetch commands, e.g. FLAGS


uidStore

public MessageStatus uidStore(long uid,
                              java.lang.String flagCommand,
                              java.lang.String[] flags)
            throws java.io.IOException
Alters data associated with the specified message in the mailbox.

Parameters:
uid - the message UID
flagCommand - FLAGS, +FLAGS, -FLAGS (or .SILENT versions)
flags - message flags to set

Returns:
the message status


uidStore

public MessageStatus[] uidStore(long start,
                                long end,
                                java.lang.String flagCommand,
                                java.lang.String[] flags)
            throws java.io.IOException
Alters data associated with the specified range of messages in the mailbox.

Parameters:
start - the UID of the first message
end - the UID of the last message
flagCommand - FLAGS, +FLAGS, -FLAGS (or .SILENT versions)
flags - message flags to set

Returns:
a list of message-number to current flags


uidStore

public MessageStatus[] uidStore(long[] uids,
                                java.lang.String flagCommand,
                                java.lang.String[] flags)
            throws java.io.IOException
Alters data associated with messages in the mailbox.

Parameters:
uids - the message UIDs
flagCommand - FLAGS, +FLAGS, -FLAGS (or .SILENT versions)
flags - message flags to set

Returns:
a list of message-number to current flags


unsubscribe

public boolean unsubscribe(java.lang.String mailbox)
            throws java.io.IOException
Removes the specified mailbox from the set of subscribed mailboxes as returned by the LSUB command.

Parameters:
mailbox - the mailbox name

Returns:
true if the mailbox was successfully unsubscribed, false otherwise


updateMailboxStatus

protected boolean updateMailboxStatus(MailboxStatus ms,
                                      java.lang.String id,
                                      IMAPResponse response)
            throws java.io.IOException


© Copyright 2003 The Free Software Foundation, all rights reserved