public class

IMAPStore

extends Store
implements ResponseHandler QuotaAwareStore
java.lang.Object
   ↳ com.google.code.javax.mail.Service
     ↳ com.google.code.javax.mail.Store
       ↳ com.google.code.com.sun.mail.imap.IMAPStore
Known Direct Subclasses

Class Overview

This class provides access to an IMAP message store.

Applications that need to make use of IMAP-specific features may cast a Store object to an IMAPStore object and use the methods on this class. The getQuota and setQuota methods support the IMAP QUOTA extension. Refer to RFC 2087 for more information.

See the com.sun.mail.imap package documentation for further information on the IMAP protocol provider.

WARNING: The APIs unique to this class should be considered EXPERIMENTAL. They may be changed in the future in ways that are incompatible with applications using the current APIs.

Summary

Constants
int RESPONSE A special event type for a StoreEvent to indicate an IMAP response, if the mail.imap.enableimapevents property is set.
Fields
private final int appendBufferSize
private String authorizationID
private final int blksize
private boolean connectionFailed
private final Object connectionFailedLock
private final int defaultPort
private boolean disableAuthLogin
private boolean disableAuthNtlm
private boolean disableAuthPlain
private boolean enableImapEvents
private boolean enableSASL
private boolean enableStartTLS
private Constructor folderConstructor
private Constructor folderConstructorLI
private boolean forceClose
private boolean forcePasswordRefresh
private String guid
private String host
private final boolean isSSL
private boolean messageCacheDebug
private final int minIdleTime
private final String name
private Namespaces namespaces
private ResponseHandler nonStoreResponseHandler A special response handler for connections that are being used to perform operations on behalf of an object other than the Store.
private PrintStream out
private String password
private final IMAPStore.ConnectionPool pool
private int port
private String proxyAuthUser
private boolean requireStartTLS
private String[] saslMechanisms
private String saslRealm
private final int statusCacheTimeout
private String user
[Expand]
Inherited Fields
From class com.google.code.javax.mail.Store
From class com.google.code.javax.mail.Service
Public Constructors
IMAPStore(Session session, URLName url)
Constructor that takes a Session object and a URLName that represents a specific IMAP server.
Protected Constructors
IMAPStore(Session session, URLName url, String name, boolean isSSL)
Constructor used by this class and by IMAPSSLStore subclass.
Public Methods
synchronized void close()
Close this Store.
synchronized Folder getDefaultFolder()
Get the default folder, representing the root of this user's namespace.
synchronized Folder getFolder(URLName url)
Get named folder.
synchronized Folder getFolder(String name)
Get named folder.
Folder[] getPersonalNamespaces()
Using the IMAP NAMESPACE command (RFC 2342), return a set of folders representing the Personal namespaces.
synchronized Quota[] getQuota(String root)
Get the quotas for the named quota root.
Folder[] getSharedNamespaces()
Using the IMAP NAMESPACE command (RFC 2342), return a set of folders representing the Shared namespaces.
Folder[] getUserNamespaces(String user)
Using the IMAP NAMESPACE command (RFC 2342), return a set of folders representing the User's namespaces.
void handleResponse(Response r)
Response handler method.
synchronized boolean hasCapability(String capability)
Return true if the specified capability string is in the list of capabilities the server announced.
void idle()
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 without the need for the client to constantly poll the server.
synchronized boolean isConnected()
Check whether this store is connected.
synchronized void setPassword(String password)
Set the password that will be used for subsequent connections after this Store is first connected (for example, when creating a connection to open a GmailFolder).
synchronized void setQuota(Quota quota)
Set the quotas for the quota root specified in the quota argument.
synchronized void setUsername(String user)
Set the user name that will be used for subsequent connections after this Store is first connected (for example, when creating a connection to open a GmailFolder).
Protected Methods
void finalize()
Stop the event dispatcher thread so the queue can be garbage collected.
IMAPFolder newIMAPFolder(String fullName, char separator, Boolean isNamespace)
Create an IMAPFolder object.
IMAPFolder newIMAPFolder(String fullName, char separator)
Create an IMAPFolder object.
IMAPFolder newIMAPFolder(ListInfo li)
Create an IMAPFolder object.
void preLogin(IMAPProtocol p)
This method is called after the connection is made and TLS is started (if needed), but before any authentication is attempted.
synchronized boolean protocolConnect(String host, int pport, String user, String password)
Implementation of protocolConnect().
[Expand]
Inherited Methods
From class com.google.code.javax.mail.Store
From class com.google.code.javax.mail.Service
From class java.lang.Object
From interface com.google.code.com.sun.mail.iap.ResponseHandler
From interface com.google.code.javax.mail.QuotaAwareStore

Constants

public static final int RESPONSE

A special event type for a StoreEvent to indicate an IMAP response, if the mail.imap.enableimapevents property is set.

Constant Value: 1000 (0x000003e8)

Fields

private final int appendBufferSize

private String authorizationID

private final int blksize

private boolean connectionFailed

private final Object connectionFailedLock

private final int defaultPort

private boolean disableAuthLogin

private boolean disableAuthNtlm

private boolean disableAuthPlain

private boolean enableImapEvents

private boolean enableSASL

private boolean enableStartTLS

private Constructor folderConstructor

private Constructor folderConstructorLI

private boolean forceClose

private boolean forcePasswordRefresh

private String guid

private String host

private final boolean isSSL

private boolean messageCacheDebug

private final int minIdleTime

private final String name

private Namespaces namespaces

private ResponseHandler nonStoreResponseHandler

A special response handler for connections that are being used to perform operations on behalf of an object other than the Store. It DOESN'T cause the Store to be cleaned up if a BYE is seen. The BYE may be real or synthetic and in either case just indicates that the connection is dead.

private PrintStream out

private String password

private final IMAPStore.ConnectionPool pool

private int port

private String proxyAuthUser

private boolean requireStartTLS

private String[] saslMechanisms

private String saslRealm

private final int statusCacheTimeout

private String user

Public Constructors

public IMAPStore (Session session, URLName url)

Constructor that takes a Session object and a URLName that represents a specific IMAP server.

Parameters
session
url

Protected Constructors

protected IMAPStore (Session session, URLName url, String name, boolean isSSL)

Constructor used by this class and by IMAPSSLStore subclass.

Parameters
session
url
name
isSSL

Public Methods

public synchronized void close ()

Close this Store.

Throws
MessagingException

public synchronized Folder getDefaultFolder ()

Get the default folder, representing the root of this user's namespace. Returns a closed DefaultFolder object.

Returns
  • the root GmailFolder
Throws
MessagingException

public synchronized Folder getFolder (URLName url)

Get named folder. Returns a new, closed IMAPFolder.

Parameters
url URLName that denotes a folder
Returns
  • GmailFolder object
Throws
MessagingException

public synchronized Folder getFolder (String name)

Get named folder. Returns a new, closed IMAPFolder.

Parameters
name The name of the GmailFolder. In some Stores, name can be an absolute path if it starts with the hierarchy delimiter. Else it is interpreted relative to the 'root' of this namespace.
Returns
  • GmailFolder object
Throws
MessagingException

public Folder[] getPersonalNamespaces ()

Using the IMAP NAMESPACE command (RFC 2342), return a set of folders representing the Personal namespaces.

Returns
  • array of GmailFolder objects
Throws
MessagingException

public synchronized Quota[] getQuota (String root)

Get the quotas for the named quota root. Quotas are controlled on the basis of a quota root, not (necessarily) a folder. The relationship between folders and quota roots depends on the IMAP server. Some servers might implement a single quota root for all folders owned by a user. Other servers might implement a separate quota root for each folder. A single folder can even have multiple quota roots, perhaps controlling quotas for different resources.

Parameters
root The name of the quota root
Returns
  • array of Quota objects
Throws
MessagingException if the server doesn't support the QUOTA extension

public Folder[] getSharedNamespaces ()

Using the IMAP NAMESPACE command (RFC 2342), return a set of folders representing the Shared namespaces.

Returns
  • array of GmailFolder objects
Throws
MessagingException

public Folder[] getUserNamespaces (String user)

Using the IMAP NAMESPACE command (RFC 2342), return a set of folders representing the User's namespaces.

Parameters
user
Returns
  • array of GmailFolder objects
Throws
MessagingException

public void handleResponse (Response r)

Response handler method.

Parameters
r

public synchronized boolean hasCapability (String capability)

Return true if the specified capability string is in the list of capabilities the server announced.

Parameters
capability
Throws
MessagingException

public void idle ()

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 without the need for the client to constantly poll the server. Use a ConnectionListener to be notified of events. When another thread (e.g., the listener thread) needs to issue an IMAP comand for this Store, the idle mode will be terminated and this method will return. Typically the caller will invoke this method in a loop.

If the mail.imap.enableimapevents property is set, notifications received while the IDLE command is active will be delivered to ConnectionListeners as events with a type of IMAPStore.RESPONSE. The event's message will be the raw IMAP response string. Note that most IMAP servers will not deliver any events when using the IDLE command on a connection with no mailbox selected (i.e., this method). In most cases you'll want to use the idle method on IMAPFolder.

NOTE: This capability is highly experimental and likely will change in future releases.

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.

Throws
MessagingException if the server doesn't support the IDLE extension
IllegalStateException if the store isn't connected

public synchronized boolean isConnected ()

Check whether this store is connected. Override superclass method, to actually ping our server connection.

Returns
  • true if the service is connected, false if it is not connected

public synchronized void setPassword (String password)

Set the password that will be used for subsequent connections after this Store is first connected (for example, when creating a connection to open a GmailFolder). This value is overridden by any call to the Store's connect method.

Most applications will never need to use this method.

Parameters
password

public synchronized void setQuota (Quota quota)

Set the quotas for the quota root specified in the quota argument. Typically this will be one of the quota roots obtained from the getQuota method, but it need not be.

Parameters
quota The quota to set
Throws
MessagingException if the server doesn't support the QUOTA extension

public synchronized void setUsername (String user)

Set the user name that will be used for subsequent connections after this Store is first connected (for example, when creating a connection to open a GmailFolder). This value is overridden by any call to the Store's connect method.

Some IMAP servers may provide an authentication ID that can be used for more efficient authentication for future connections. This authentication ID is provided in a server-specific manner not described here.

Most applications will never need to use this method.

Parameters
user

Protected Methods

protected void finalize ()

Stop the event dispatcher thread so the queue can be garbage collected.

Throws
Throwable

protected IMAPFolder newIMAPFolder (String fullName, char separator, Boolean isNamespace)

Create an IMAPFolder object. If user supplied their own class, use it. Otherwise, call the constructor.

Parameters
fullName
separator
isNamespace

protected IMAPFolder newIMAPFolder (String fullName, char separator)

Create an IMAPFolder object. Call the newIMAPFolder method above with a null isNamespace.

Parameters
fullName
separator

protected IMAPFolder newIMAPFolder (ListInfo li)

Create an IMAPFolder object. If user supplied their own class, use it. Otherwise, call the constructor.

Parameters
li

protected void preLogin (IMAPProtocol p)

This method is called after the connection is made and TLS is started (if needed), but before any authentication is attempted. Subclasses can override this method to issue commands that are needed in the "not authenticated" state. Note that if the connection is pre-authenticated, this method won't be called.

The implementation of this method in this class does nothing.

Parameters
p
Throws
ProtocolException

protected synchronized boolean protocolConnect (String host, int pport, String user, String password)

Implementation of protocolConnect(). Will create a connection to the server and authenticate the user using the mechanisms specified by various properties.

The host, user, and password parameters must all be non-null. If the authentication mechanism being used does not require a password, an empty string or other suitable dummy password should be used.

Parameters
host The name of the host to connect to
pport The port to use (-1 means use default port)
user The name of the user to login as
password The user's password
Returns
  • true if connection successful, false if authentication failed
Throws
MessagingException