com.sun.mail.imap.protocol
Class IMAPProtocol

java.lang.Object
  extended by com.sun.mail.iap.Protocol
      extended by com.sun.mail.imap.protocol.IMAPProtocol

public class IMAPProtocol
extends Protocol

This class extends the iap.Protocol object and implements IMAP semantics. In general, there is a method corresponding to each IMAP protocol command. The typical implementation issues the appropriate protocol command, collects all responses, processes those responses that are specific to this command and then dispatches the rest (the unsolicited ones) to the dispatcher using the notifyResponseHandlers(r).

Version:
1.64, 07/05/04
Author:
John Mani, Bill Shannon

Field Summary
 
Fields inherited from class com.sun.mail.iap.Protocol
debug, host, out, prefix, props, quote
 
Constructor Summary
IMAPProtocol(java.lang.String name, java.lang.String host, int port, boolean debug, java.io.PrintStream out, java.util.Properties props, boolean isSSL)
          Constructor.
 
Method Summary
 void append(java.lang.String mbox, Flags f, java.util.Date d, Literal data)
          APPEND Command.
 AppendUID appenduid(java.lang.String mbox, Flags f, java.util.Date d, Literal data)
          APPEND Command, return uid from APPENDUID response code.
 AppendUID appenduid(java.lang.String mbox, Flags f, java.util.Date d, Literal data, boolean uid)
           
 void authlogin(java.lang.String u, java.lang.String p)
          The AUTHENTICATE command with AUTH=LOGIN authenticate scheme
 void authplain(java.lang.String authzid, java.lang.String u, java.lang.String p)
          The AUTHENTICATE command with AUTH=PLAIN authentication scheme.
 void capability()
          CAPABILITY command.
 void check()
          CHECK Command.
 void close()
          CLOSE Command.
 void copy(int start, int end, java.lang.String mbox)
           
 void copy(MessageSet[] msgsets, java.lang.String mbox)
          COPY command.
 void create(java.lang.String mbox)
          CREATE Command.
 void delete(java.lang.String mbox)
          DELETE Command.
 void deleteACL(java.lang.String mbox, java.lang.String user)
          DELETEACL Command.
 void disconnect()
          Close socket connection.
 MailboxInfo examine(java.lang.String mbox)
          EXAMINE Command.
 void expunge()
          EXPUNGE Command.
 Response[] fetch(int start, int end, java.lang.String what)
           
 Response[] fetch(int msg, java.lang.String what)
           
 Response[] fetch(MessageSet[] msgsets, java.lang.String what)
           
 BODY fetchBody(int msgno, java.lang.String section)
          Fetch given BODY section.
protected  BODY fetchBody(int msgno, java.lang.String section, boolean peek)
           
 BODY fetchBody(int msgno, java.lang.String section, int start, int size)
          Partial FETCH of given BODY section.
protected  BODY fetchBody(int msgno, java.lang.String section, int start, int size, boolean peek, ByteArray ba)
           
 BODY fetchBody(int msgno, java.lang.String section, int start, int size, ByteArray ba)
          Partial FETCH of given BODY section.
 BODYSTRUCTURE fetchBodyStructure(int msgno)
          Fetch the BODYSTRUCTURE of the specified message.
 Flags fetchFlags(int msgno)
          Fetch the FLAGS for the given message.
 RFC822DATA fetchRFC822(int msgno, java.lang.String what)
          Fetch the specified RFC822 Data item.
 UID fetchSequenceNumber(long uid)
          Get the sequence number for the given UID.
 UID[] fetchSequenceNumbers(long[] uids)
          Get the sequence numbers for UIDs ranging from start till end.
 UID[] fetchSequenceNumbers(long start, long end)
          Get the sequence numbers for UIDs ranging from start till end.
 UID fetchUID(int msgno)
          Fetch the IMAP UID for the given message.
 ACL[] getACL(java.lang.String mbox)
          GETACL Command.
 java.util.Map getCapabilities()
          Return the map of capabilities returned by the server.
 Quota[] getQuota(java.lang.String root)
          GETQUOTA Command.
 Quota[] getQuotaRoot(java.lang.String mbox)
          GETQUOTAROOT Command.
protected  ByteArray getResponseBuffer()
          Return a buffer to read a response into.
 boolean hasCapability(java.lang.String c)
          Check whether the given capability is supported by this server.
 void idleAbort()
          Abort an IDLE command.
 void idleStart()
          IDLE Command.
 boolean isAuthenticated()
          Returns true if the connection has been authenticated, either due to a successful login, or due to a PREAUTH greeting response.
 boolean isREV1()
          Returns true if this is a IMAP4rev1 server
 ListInfo[] list(java.lang.String ref, java.lang.String pattern)
          LIST Command.
 Rights[] listRights(java.lang.String mbox, java.lang.String user)
          LISTRIGHTS Command.
 void login(java.lang.String u, java.lang.String p)
          LOGIN Command.
 void logout()
          LOGOUT Command.
 ListInfo[] lsub(java.lang.String ref, java.lang.String pattern)
          LSUB Command.
 Rights myRights(java.lang.String mbox)
          MYRIGHTS Command.
 Namespaces namespace()
          NAMESPACE Command.
 void noop()
          The NOOP command.
protected  void parseCapabilities(Response r)
          Parse the capabilities from a CAPABILITY response or from a CAPABILITY response code attached to (e.g.) an OK response.
 BODY peekBody(int msgno, java.lang.String section)
          Fetch given BODY section, without marking the message as SEEN.
 BODY peekBody(int msgno, java.lang.String section, int start, int size)
          Partial FETCH of given BODY section, without setting SEEN flag.
 BODY peekBody(int msgno, java.lang.String section, int start, int size, ByteArray ba)
          Partial FETCH of given BODY section, without setting SEEN flag.
protected  void processGreeting(Response r)
          Check the greeting when first connecting; look for PREAUTH response.
 boolean processIdleResponse(Response r)
          Process a response returned by readIdleResponse().
 void proxyauth(java.lang.String u)
          PROXYAUTH Command.
 Response readIdleResponse()
          While an IDLE command is in progress, read a response sent from the server.
 Response readResponse()
          Read a response from the server.
 void rename(java.lang.String o, java.lang.String n)
          RENAME Command.
 void sasllogin(java.lang.String[] allowed, java.lang.String realm, java.lang.String authzid, java.lang.String u, java.lang.String p)
          SASL-based login.
 int[] search(MessageSet[] msgsets, SearchTerm term)
          Issue the given search criterion on the specified message sets.
 int[] search(SearchTerm term)
          Issue the given search criterion on all messages in this folder.
 MailboxInfo select(java.lang.String mbox)
          SELECT Command.
 void setACL(java.lang.String mbox, char modifier, ACL acl)
          SETACL Command.
protected  void setCapabilities(Response r)
          If the response contains a CAPABILITY response code, extract it and save the capabilities.
 void setQuota(Quota quota)
          SETQUOTA Command.
 void startTLS()
          STARTTLS Command.
 Status status(java.lang.String mbox, java.lang.String[] items)
          STATUS Command.
 void storeFlags(int msg, Flags flags, boolean set)
          Set the specified flags on this message.
 void storeFlags(int start, int end, Flags flags, boolean set)
           
 void storeFlags(MessageSet[] msgsets, Flags flags, boolean set)
           
 void subscribe(java.lang.String mbox)
          SUBSCRIBE Command.
protected  boolean supportsNonSyncLiterals()
          Returns whether this Protocol supports non-synchronizing literals.
 void uidexpunge(UIDSet[] set)
          UID EXPUNGE Command.
 void unsubscribe(java.lang.String mbox)
          UNSUBSCRIBE Command.
 
Methods inherited from class com.sun.mail.iap.Protocol
addResponseHandler, command, finalize, getInputStream, getOutputStream, getTimestamp, handleResult, notifyResponseHandlers, removeResponseHandler, simpleCommand, startTLS, writeCommand
 
Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

IMAPProtocol

public IMAPProtocol(java.lang.String name,
                    java.lang.String host,
                    int port,
                    boolean debug,
                    java.io.PrintStream out,
                    java.util.Properties props,
                    boolean isSSL)
             throws java.io.IOException,
                    ProtocolException
Constructor. Opens a connection to the given host at given port.

Parameters:
host - host to connect to
port - portnumber to connect to
debug - debug mode
props - Properties object used by this protocol
Throws:
java.io.IOException
ProtocolException
Method Detail

capability

public void capability()
                throws ProtocolException
CAPABILITY command.

Throws:
ProtocolException
See Also:
"RFC2060, section 6.1.1"

setCapabilities

protected void setCapabilities(Response r)
If the response contains a CAPABILITY response code, extract it and save the capabilities.


parseCapabilities

protected void parseCapabilities(Response r)
Parse the capabilities from a CAPABILITY response or from a CAPABILITY response code attached to (e.g.) an OK response.


processGreeting

protected void processGreeting(Response r)
                        throws ProtocolException
Check the greeting when first connecting; look for PREAUTH response.

Overrides:
processGreeting in class Protocol
Throws:
ProtocolException

isAuthenticated

public boolean isAuthenticated()
Returns true if the connection has been authenticated, either due to a successful login, or due to a PREAUTH greeting response.


isREV1

public boolean isREV1()
Returns true if this is a IMAP4rev1 server


supportsNonSyncLiterals

protected boolean supportsNonSyncLiterals()
Returns whether this Protocol supports non-synchronizing literals.

Overrides:
supportsNonSyncLiterals in class Protocol

readResponse

public Response readResponse()
                      throws java.io.IOException,
                             ProtocolException
Read a response from the server.

Overrides:
readResponse in class Protocol
Throws:
java.io.IOException
ProtocolException

hasCapability

public boolean hasCapability(java.lang.String c)
Check whether the given capability is supported by this server. Returns true if so, otherwise returns false.


getCapabilities

public java.util.Map getCapabilities()
Return the map of capabilities returned by the server.

Since:
JavaMail 1.4.1

disconnect

public void disconnect()
Close socket connection. This method just makes the Protocol.disconnect() method public.

Overrides:
disconnect in class Protocol

noop

public void noop()
          throws ProtocolException
The NOOP command.

Throws:
ProtocolException
See Also:
"RFC2060, section 6.1.2"

logout

public void logout()
            throws ProtocolException
LOGOUT Command.

Throws:
ProtocolException
See Also:
"RFC2060, section 6.1.3"

login

public void login(java.lang.String u,
                  java.lang.String p)
           throws ProtocolException
LOGIN Command.

Throws:
ProtocolException
See Also:
"RFC2060, section 6.2.2"

authlogin

public void authlogin(java.lang.String u,
                      java.lang.String p)
               throws ProtocolException
The AUTHENTICATE command with AUTH=LOGIN authenticate scheme

Throws:
ProtocolException
See Also:
"RFC2060, section 6.2.1"

authplain

public void authplain(java.lang.String authzid,
                      java.lang.String u,
                      java.lang.String p)
               throws ProtocolException
The AUTHENTICATE command with AUTH=PLAIN authentication scheme. This is based heavly on the authlogin(java.lang.String, java.lang.String) method.

Parameters:
authzid - the authorization id
u - the username
p - the password
Throws:
ProtocolException - as thrown by Protocol.handleResult(com.sun.mail.iap.Response).
Since:
JavaMail 1.3.2
See Also:
"RFC3501, section 6.2.2", "RFC2595, section 6"

sasllogin

public void sasllogin(java.lang.String[] allowed,
                      java.lang.String realm,
                      java.lang.String authzid,
                      java.lang.String u,
                      java.lang.String p)
               throws ProtocolException
SASL-based login.

Throws:
ProtocolException

proxyauth

public void proxyauth(java.lang.String u)
               throws ProtocolException
PROXYAUTH Command.

Throws:
ProtocolException
See Also:
"Netscape/iPlanet/SunONE Messaging Server extension"

startTLS

public void startTLS()
              throws ProtocolException
STARTTLS Command.

Throws:
ProtocolException
See Also:
"RFC3501, section 6.2.1"

select

public MailboxInfo select(java.lang.String mbox)
                   throws ProtocolException
SELECT Command.

Throws:
ProtocolException
See Also:
"RFC2060, section 6.3.1"

examine

public MailboxInfo examine(java.lang.String mbox)
                    throws ProtocolException
EXAMINE Command.

Throws:
ProtocolException
See Also:
"RFC2060, section 6.3.2"

status

public Status status(java.lang.String mbox,
                     java.lang.String[] items)
              throws ProtocolException
STATUS Command.

Throws:
ProtocolException
See Also:
"RFC2060, section 6.3.10"

create

public void create(java.lang.String mbox)
            throws ProtocolException
CREATE Command.

Throws:
ProtocolException
See Also:
"RFC2060, section 6.3.3"

delete

public void delete(java.lang.String mbox)
            throws ProtocolException
DELETE Command.

Throws:
ProtocolException
See Also:
"RFC2060, section 6.3.4"

rename

public void rename(java.lang.String o,
                   java.lang.String n)
            throws ProtocolException
RENAME Command.

Throws:
ProtocolException
See Also:
"RFC2060, section 6.3.5"

subscribe

public void subscribe(java.lang.String mbox)
               throws ProtocolException
SUBSCRIBE Command.

Throws:
ProtocolException
See Also:
"RFC2060, section 6.3.6"

unsubscribe

public void unsubscribe(java.lang.String mbox)
                 throws ProtocolException
UNSUBSCRIBE Command.

Throws:
ProtocolException
See Also:
"RFC2060, section 6.3.7"

list

public ListInfo[] list(java.lang.String ref,
                       java.lang.String pattern)
                throws ProtocolException
LIST Command.

Throws:
ProtocolException
See Also:
"RFC2060, section 6.3.8"

lsub

public ListInfo[] lsub(java.lang.String ref,
                       java.lang.String pattern)
                throws ProtocolException
LSUB Command.

Throws:
ProtocolException
See Also:
"RFC2060, section 6.3.9"

append

public void append(java.lang.String mbox,
                   Flags f,
                   java.util.Date d,
                   Literal data)
            throws ProtocolException
APPEND Command.

Throws:
ProtocolException
See Also:
"RFC2060, section 6.3.11"

appenduid

public AppendUID appenduid(java.lang.String mbox,
                           Flags f,
                           java.util.Date d,
                           Literal data)
                    throws ProtocolException
APPEND Command, return uid from APPENDUID response code.

Throws:
ProtocolException
See Also:
"RFC2060, section 6.3.11"

appenduid

public AppendUID appenduid(java.lang.String mbox,
                           Flags f,
                           java.util.Date d,
                           Literal data,
                           boolean uid)
                    throws ProtocolException
Throws:
ProtocolException

check

public void check()
           throws ProtocolException
CHECK Command.

Throws:
ProtocolException
See Also:
"RFC2060, section 6.4.1"

close

public void close()
           throws ProtocolException
CLOSE Command.

Throws:
ProtocolException
See Also:
"RFC2060, section 6.4.2"

expunge

public void expunge()
             throws ProtocolException
EXPUNGE Command.

Throws:
ProtocolException
See Also:
"RFC2060, section 6.4.3"

uidexpunge

public void uidexpunge(UIDSet[] set)
                throws ProtocolException
UID EXPUNGE Command.

Throws:
ProtocolException
See Also:
"RFC2359, section 4.1"

fetchBodyStructure

public BODYSTRUCTURE fetchBodyStructure(int msgno)
                                 throws ProtocolException
Fetch the BODYSTRUCTURE of the specified message.

Throws:
ProtocolException

peekBody

public BODY peekBody(int msgno,
                     java.lang.String section)
              throws ProtocolException
Fetch given BODY section, without marking the message as SEEN.

Throws:
ProtocolException

fetchBody

public BODY fetchBody(int msgno,
                      java.lang.String section)
               throws ProtocolException
Fetch given BODY section.

Throws:
ProtocolException

fetchBody

protected BODY fetchBody(int msgno,
                         java.lang.String section,
                         boolean peek)
                  throws ProtocolException
Throws:
ProtocolException

peekBody

public BODY peekBody(int msgno,
                     java.lang.String section,
                     int start,
                     int size)
              throws ProtocolException
Partial FETCH of given BODY section, without setting SEEN flag.

Throws:
ProtocolException

fetchBody

public BODY fetchBody(int msgno,
                      java.lang.String section,
                      int start,
                      int size)
               throws ProtocolException
Partial FETCH of given BODY section.

Throws:
ProtocolException

peekBody

public BODY peekBody(int msgno,
                     java.lang.String section,
                     int start,
                     int size,
                     ByteArray ba)
              throws ProtocolException
Partial FETCH of given BODY section, without setting SEEN flag.

Throws:
ProtocolException

fetchBody

public BODY fetchBody(int msgno,
                      java.lang.String section,
                      int start,
                      int size,
                      ByteArray ba)
               throws ProtocolException
Partial FETCH of given BODY section.

Throws:
ProtocolException

fetchBody

protected BODY fetchBody(int msgno,
                         java.lang.String section,
                         int start,
                         int size,
                         boolean peek,
                         ByteArray ba)
                  throws ProtocolException
Throws:
ProtocolException

getResponseBuffer

protected ByteArray getResponseBuffer()
Return a buffer to read a response into. The buffer is provided by fetchBody and is used only once.

Overrides:
getResponseBuffer in class Protocol

fetchRFC822

public RFC822DATA fetchRFC822(int msgno,
                              java.lang.String what)
                       throws ProtocolException
Fetch the specified RFC822 Data item. 'what' names the item to be fetched. 'what' can be null to fetch the whole message.

Throws:
ProtocolException

fetchFlags

public Flags fetchFlags(int msgno)
                 throws ProtocolException
Fetch the FLAGS for the given message.

Throws:
ProtocolException

fetchUID

public UID fetchUID(int msgno)
             throws ProtocolException
Fetch the IMAP UID for the given message.

Throws:
ProtocolException

fetchSequenceNumber

public UID fetchSequenceNumber(long uid)
                        throws ProtocolException
Get the sequence number for the given UID. A UID object containing the sequence number is returned. If the given UID is invalid, null is returned.

Throws:
ProtocolException

fetchSequenceNumbers

public UID[] fetchSequenceNumbers(long start,
                                  long end)
                           throws ProtocolException
Get the sequence numbers for UIDs ranging from start till end. UID objects that contain the sequence numbers are returned. If no UIDs in the given range are found, an empty array is returned.

Throws:
ProtocolException

fetchSequenceNumbers

public UID[] fetchSequenceNumbers(long[] uids)
                           throws ProtocolException
Get the sequence numbers for UIDs ranging from start till end. UID objects that contain the sequence numbers are returned. If no UIDs in the given range are found, an empty array is returned.

Throws:
ProtocolException

fetch

public Response[] fetch(MessageSet[] msgsets,
                        java.lang.String what)
                 throws ProtocolException
Throws:
ProtocolException

fetch

public Response[] fetch(int start,
                        int end,
                        java.lang.String what)
                 throws ProtocolException
Throws:
ProtocolException

fetch

public Response[] fetch(int msg,
                        java.lang.String what)
                 throws ProtocolException
Throws:
ProtocolException

copy

public void copy(MessageSet[] msgsets,
                 java.lang.String mbox)
          throws ProtocolException
COPY command.

Throws:
ProtocolException

copy

public void copy(int start,
                 int end,
                 java.lang.String mbox)
          throws ProtocolException
Throws:
ProtocolException

storeFlags

public void storeFlags(MessageSet[] msgsets,
                       Flags flags,
                       boolean set)
                throws ProtocolException
Throws:
ProtocolException

storeFlags

public void storeFlags(int start,
                       int end,
                       Flags flags,
                       boolean set)
                throws ProtocolException
Throws:
ProtocolException

storeFlags

public void storeFlags(int msg,
                       Flags flags,
                       boolean set)
                throws ProtocolException
Set the specified flags on this message.

Throws:
ProtocolException

search

public int[] search(MessageSet[] msgsets,
                    SearchTerm term)
             throws ProtocolException,
                    SearchException
Issue the given search criterion on the specified message sets. Returns array of matching sequence numbers. An empty array is returned if no matches are found.

Parameters:
msgsets - array of MessageSets
term - SearchTerm
Returns:
array of matching sequence numbers.
Throws:
ProtocolException
SearchException

search

public int[] search(SearchTerm term)
             throws ProtocolException,
                    SearchException
Issue the given search criterion on all messages in this folder. Returns array of matching sequence numbers. An empty array is returned if no matches are found.

Parameters:
term - SearchTerm
Returns:
array of matching sequence numbers.
Throws:
ProtocolException
SearchException

namespace

public Namespaces namespace()
                     throws ProtocolException
NAMESPACE Command.

Throws:
ProtocolException
See Also:
"RFC2342"

getQuotaRoot

public Quota[] getQuotaRoot(java.lang.String mbox)
                     throws ProtocolException
GETQUOTAROOT Command. Returns an array of Quota objects, representing the quotas for this mailbox and, indirectly, the quotaroots for this mailbox.

Throws:
ProtocolException
See Also:
"RFC2087"

getQuota

public Quota[] getQuota(java.lang.String root)
                 throws ProtocolException
GETQUOTA Command. Returns an array of Quota objects, representing the quotas for this quotaroot.

Throws:
ProtocolException
See Also:
"RFC2087"

setQuota

public void setQuota(Quota quota)
              throws ProtocolException
SETQUOTA Command. Set the indicated quota on the corresponding quotaroot.

Throws:
ProtocolException
See Also:
"RFC2087"

setACL

public void setACL(java.lang.String mbox,
                   char modifier,
                   ACL acl)
            throws ProtocolException
SETACL Command.

Throws:
ProtocolException
See Also:
"RFC2086"

deleteACL

public void deleteACL(java.lang.String mbox,
                      java.lang.String user)
               throws ProtocolException
DELETEACL Command.

Throws:
ProtocolException
See Also:
"RFC2086"

getACL

public ACL[] getACL(java.lang.String mbox)
             throws ProtocolException
GETACL Command.

Throws:
ProtocolException
See Also:
"RFC2086"

listRights

public Rights[] listRights(java.lang.String mbox,
                           java.lang.String user)
                    throws ProtocolException
LISTRIGHTS Command.

Throws:
ProtocolException
See Also:
"RFC2086"

myRights

public Rights myRights(java.lang.String mbox)
                throws ProtocolException
MYRIGHTS Command.

Throws:
ProtocolException
See Also:
"RFC2086"

idleStart

public void idleStart()
               throws ProtocolException
IDLE Command.

If the server supports the IDLE command extension, the IDLE command is issued and this method blocks until a response has been received. Once the first response has been received, the IDLE command is terminated and all responses are collected and handled and this method returns.

Note that while this method is blocked waiting for a response, no other threads may issue any commands to the server that would use this same connection.

Throws:
ProtocolException
Since:
JavaMail 1.4.1
See Also:
"RFC2177"

readIdleResponse

public Response readIdleResponse()
While an IDLE command is in progress, read a response sent from the server. The response is read with no locks held so that when the read blocks waiting for the response from the server it's not holding locks that would prevent other threads from interrupting the IDLE command.

Since:
JavaMail 1.4.1

processIdleResponse

public boolean processIdleResponse(Response r)
                            throws ProtocolException
Process a response returned by readIdleResponse(). This method will be called with appropriate locks held so that the processing of the response is safe.

Throws:
ProtocolException
Since:
JavaMail 1.4.1

idleAbort

public void idleAbort()
               throws ProtocolException
Abort an IDLE command. While one thread is blocked in readIdleResponse(), another thread will use this method to abort the IDLE command, which will cause the server to send the closing tag for the IDLE command, which readIdleResponse() and processIdleResponse() will see and terminate the IDLE state.

Throws:
ProtocolException
Since:
JavaMail 1.4.1


Copyright © 2012. All Rights Reserved.