com.sun.mail.imap

Class IMAPStore

java.lang.Object

javax.mail.Service

javax.mail.Store

com.sun.mail.imap.IMAPStore

All Implemented Interfaces:

ResponseHandler, AutoCloseable, QuotaAwareStore

Direct Known Subclasses:

IMAPSSLStore

public class IMAPStore
extends Store
implements QuotaAwareStore, ResponseHandler

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.

The id method supports the IMAP ID extension; see RFC 2971. The fields ID_NAME, ID_VERSION, etc. represent the suggested field names in RFC 2971 section 3.3 and may be used as keys in the Map containing client values or server values.

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.

Author:

John Mani, Bill Shannon, Jim Glennon

Field Summary

Fields

Modifier and Type	Field and Description
protected String	authorizationID
protected int	defaultPort
protected String	host
static String	ID_ADDRESS
static String	ID_ARGUMENTS
static String	ID_COMMAND
static String	ID_DATE
static String	ID_ENVIRONMENT
static String	ID_NAME
static String	ID_OS
static String	ID_OS_VERSION
static String	ID_SUPPORT_URL
static String	ID_VENDOR
static String	ID_VERSION
protected boolean	isSSL
protected MailLogger	logger
protected String	name
protected String	password
protected String	proxyAuthUser
static int	RESPONSE A special event type for a StoreEvent to indicate an IMAP response, if the mail.imap.enableimapevents property is set.
protected String	saslRealm
protected String	user

Fields inherited from class javax.mail.Service

debug, session, url

Constructor Summary

Constructors

Modifier	Constructor and Description
	IMAPStore(Session session, URLName url) Constructor that takes a Session object and a URLName that represents a specific IMAP server.
protected	IMAPStore(Session session, URLName url, String name, boolean isSSL) Constructor used by this class and by IMAPSSLStore subclass.

Method Summary

Modifier and Type	Method and Description
void	close() Close this Store.
protected void	finalize() Stop the event dispatcher thread so the queue can be garbage collected.
Folder	getDefaultFolder() Get the default folder, representing the root of this user's namespace.
Folder	getFolder(String name) Get named folder.
Folder	getFolder(URLName url) Get named folder.
Folder[]	getPersonalNamespaces() Using the IMAP NAMESPACE command (RFC 2342), return a set of folders representing the Personal namespaces.
String	getProxyAuthUser() Get the user name to be used with the PROXYAUTH command.
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.
boolean	hasCapability(String capability) Return true if the specified capability string is in the list of capabilities the server announced.
Map<String,String>	id(Map<String,String> clientParams) Send the IMAP ID command (if supported by the server) and return the result from the server.
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.
boolean	isConnected() Check whether this store is connected.
boolean	isSSL() Does this IMAPStore use SSL when connecting to the server?
protected IMAPFolder	newIMAPFolder(ListInfo li) Create an IMAPFolder object.
protected IMAPFolder	newIMAPFolder(String fullName, char separator) Create an IMAPFolder object.
protected IMAPFolder	newIMAPFolder(String fullName, char separator, Boolean isNamespace) Create an IMAPFolder object.
protected IMAPProtocol	newIMAPProtocol(String host, int port) Create an IMAPProtocol object connected to the host and port.
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.
protected boolean	protocolConnect(String host, int pport, String user, String password) Implementation of protocolConnect().
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 Folder).
void	setProxyAuthUser(String user) Set the user name to be used with the PROXYAUTH command.
void	setQuota(Quota quota) Set the quotas for the quota root specified in the quota argument.
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 Folder).

Methods inherited from class javax.mail.Store

addFolderListener, addStoreListener, notifyFolderListeners, notifyFolderRenamedListeners, notifyStoreListeners, removeFolderListener, removeStoreListener

Methods inherited from class javax.mail.Service

addConnectionListener, connect, connect, connect, connect, getURLName, notifyConnectionListeners, queueEvent, removeConnectionListener, setConnected, setURLName, toString

Methods inherited from class java.lang.Object

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

Field Detail

RESPONSE

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.

See Also:

Constant Field Values

ID_NAME

public static final String ID_NAME

See Also:

Constant Field Values

ID_VERSION

public static final String ID_VERSION

See Also:

Constant Field Values

ID_OS

public static final String ID_OS

See Also:

Constant Field Values

ID_OS_VERSION

public static final String ID_OS_VERSION

See Also:

Constant Field Values

ID_VENDOR

public static final String ID_VENDOR

See Also:

Constant Field Values

ID_SUPPORT_URL

public static final String ID_SUPPORT_URL

See Also:

Constant Field Values

ID_ADDRESS

public static final String ID_ADDRESS

See Also:

Constant Field Values

ID_DATE

public static final String ID_DATE

See Also:

Constant Field Values

ID_COMMAND

public static final String ID_COMMAND

See Also:

Constant Field Values

ID_ARGUMENTS

public static final String ID_ARGUMENTS

See Also:

Constant Field Values

ID_ENVIRONMENT

public static final String ID_ENVIRONMENT

See Also:

Constant Field Values

name

protected final String name

defaultPort

protected final int defaultPort

isSSL

protected final boolean isSSL

host

protected String host

user

protected String user

password

protected String password

proxyAuthUser

protected String proxyAuthUser

authorizationID

protected String authorizationID

saslRealm

protected String saslRealm

logger

protected MailLogger logger

Constructor Detail

IMAPStore

public IMAPStore(Session session,
                 URLName url)

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

Parameters:

session - the Session

url - the URLName of this store

IMAPStore

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

Constructor used by this class and by IMAPSSLStore subclass.

Parameters:

session - the Session

url - the URLName of this store

name - the protocol name for this store

isSSL - use SSL?

Method Detail

protocolConnect

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

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.

Overrides:

protocolConnect in class Service

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:

AuthenticationFailedException - for authentication failures

MessagingException - for non-authentication failures

newIMAPProtocol

protected IMAPProtocol newIMAPProtocol(String host,
                                       int port)
                                throws IOException,
                                       ProtocolException

Create an IMAPProtocol object connected to the host and port. Subclasses of IMAPStore may override this method to return a subclass of IMAPProtocol that supports product-specific extensions.

Parameters:

host - the host name

port - the port number

Returns:

the new IMAPProtocol object

Throws:

IOException - for I/O errors

ProtocolException - for protocol errors

Since:

JavaMail 1.4.6

preLogin

protected void preLogin(IMAPProtocol p)
                 throws ProtocolException

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 - the IMAPProtocol connection

Throws:

ProtocolException - for protocol errors

Since:

JavaMail 1.4.4

isSSL

public boolean isSSL()

Does this IMAPStore use SSL when connecting to the server?

Returns:

true if using SSL

Since:

JavaMail 1.4.6

setUsername

public 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 Folder). 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 - the user name for the store

Since:

JavaMail 1.3.3

setPassword

public 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 Folder). This value is overridden by any call to the Store's connect method.

Most applications will never need to use this method.

Parameters:

password - the password for the store

Since:

JavaMail 1.3.3

hasCapability

public boolean hasCapability(String capability)
                      throws MessagingException

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

Parameters:

capability - the capability string

Returns:

true if the server supports this capability

Throws:

MessagingException - for failures

Since:

JavaMail 1.3.3

setProxyAuthUser

public void setProxyAuthUser(String user)

Set the user name to be used with the PROXYAUTH command. The PROXYAUTH user name can also be set using the mail.imap.proxyauth.user property when this Store is created.

Parameters:

user - the user name to set

Since:

JavaMail 1.5.1

getProxyAuthUser

public String getProxyAuthUser()

Get the user name to be used with the PROXYAUTH command.

Returns:

the user name

Since:

JavaMail 1.5.1

isConnected

public boolean isConnected()

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

Overrides:

isConnected in class Service

Returns:

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

close

public void close()
           throws MessagingException

Close this Store.

Specified by:

close in interface AutoCloseable

Overrides:

close in class Service

Throws:

MessagingException - for errors while closing

See Also:

ConnectionEvent

finalize

protected void finalize()
                 throws Throwable

Description copied from class: Service

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

Overrides:

finalize in class Service

Throws:

Throwable

getDefaultFolder

public Folder getDefaultFolder()
                        throws MessagingException

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

Specified by:

getDefaultFolder in class Store

Returns:

the root Folder

Throws:

MessagingException - for other failures

getFolder

public Folder getFolder(String name)
                 throws MessagingException

Get named folder. Returns a new, closed IMAPFolder.

Specified by:

getFolder in class Store

Parameters:

name - The name of the Folder. 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:

Folder object

Throws:

MessagingException - for other failures

See Also:

Folder.exists(), Folder.create(int)

getFolder

public Folder getFolder(URLName url)
                 throws MessagingException

Get named folder. Returns a new, closed IMAPFolder.

Specified by:

getFolder in class Store

Parameters:

url - URLName that denotes a folder

Returns:

Folder object

Throws:

MessagingException - for other failures

See Also:

URLName

newIMAPFolder

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 - the full name of the folder

separator - the separator character for the folder hierarchy

isNamespace - does this name represent a namespace?

Returns:

the new IMAPFolder object

newIMAPFolder

protected IMAPFolder newIMAPFolder(String fullName,
                                   char separator)

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

Parameters:

fullName - the full name of the folder

separator - the separator character for the folder hierarchy

Returns:

the new IMAPFolder object

newIMAPFolder

protected IMAPFolder newIMAPFolder(ListInfo li)

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

Parameters:

li - the ListInfo for the folder

Returns:

the new IMAPFolder object

getPersonalNamespaces

public Folder[] getPersonalNamespaces()
                               throws MessagingException

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

Overrides:

getPersonalNamespaces in class Store

Returns:

array of Folder objects

Throws:

MessagingException - for other failures

getUserNamespaces

public Folder[] getUserNamespaces(String user)
                           throws MessagingException

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

Overrides:

getUserNamespaces in class Store

Parameters:

user - the user name

Returns:

array of Folder objects

Throws:

MessagingException - for other failures

getSharedNamespaces

public Folder[] getSharedNamespaces()
                             throws MessagingException

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

Overrides:

getSharedNamespaces in class Store

Returns:

array of Folder objects

Throws:

MessagingException - for other failures

getQuota

public Quota[] getQuota(String root)
                 throws MessagingException

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.

Specified by:

getQuota in interface QuotaAwareStore

Parameters:

root - the name of the quota root

Returns:

array of Quota objects

Throws:

MessagingException - if the server doesn't support the QUOTA extension

setQuota

public void setQuota(Quota quota)
              throws MessagingException

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.

Specified by:

setQuota in interface QuotaAwareStore

Parameters:

quota - the quota to set

Throws:

MessagingException - if the server doesn't support the QUOTA extension

handleResponse

public void handleResponse(Response r)

Response handler method.

Specified by:

handleResponse in interface ResponseHandler

idle

public void idle()
          throws MessagingException

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

Since:

JavaMail 1.4.1

id

public Map<String,String> id(Map<String,String> clientParams)
                      throws MessagingException

Send the IMAP ID command (if supported by the server) and return the result from the server. The ID command identfies the client to the server and returns information about the server to the client. See RFC 2971. The returned Map is unmodifiable.

Parameters:

clientParams - a Map of keys and values identifying the client

Returns:

a Map of keys and values identifying the server

Throws:

MessagingException - if the server doesn't support the ID extension

Since:

JavaMail 1.5.1