This documentation differs from the official API. Jadeite adds extra features to the API including: variable font sizes, constructions examples, placeholders for classes and methods, and auto-generated “See Also” links. Additionally it is missing some items found in standard Javadoc documentation, including: generics type information, “Deprecated” tags and comments, “See Also” links, along with other minor differences. Please send any questions or feedback to bam@cs.cmu.edu.


com.sun.mail.imap
class IMAPStore

javax.mail.Service extended by javax.mail.Store extended by com.sun.mail.imap.IMAPStore
All Implemented Interfaces:
ResponseHandler, 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 {@link #getQuota getQuota} and {@link #setQuota 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.


Field Summary
static int RESPONSE
          A special event type for a StoreEvent to indicate an IMAP response, if the mail.imap.enableimapevents property is set.
 
Fields inherited from class javax.mail.Service
debug, session, url
 
Constructor Summary
 
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, int defaultPort, boolean isSSL)

          Constructor used by this class and by IMAPSSLStore subclass.
 
Method Summary
 void

          Close this Store.
protected void

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

          Get the default folder, representing the root of this user's namespace.
 Folder

          Get named folder.
 Folder

          Get named folder.
 Folder[]

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

          Get the quotas for the named quota root.
 Folder[]

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

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

          Response handler method.
 boolean
hasCapability(String capability)

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

          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

          Check whether this store is connected.
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
setQuota(Quota quota)

          Set the quotas for the quota root specified in the quota argument.
 void

          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, getDefaultFolder, getFolder, getFolder, getPersonalNamespaces, getSharedNamespaces, getUserNamespaces, notifyFolderListeners, notifyFolderRenamedListeners, notifyStoreListeners, removeFolderListener, removeStoreListener
 
Methods inherited from class javax.mail.Service
addConnectionListener, close, connect, connect, connect, connect, finalize, getURLName, isConnected, notifyConnectionListeners, protocolConnect, queueEvent, removeConnectionListener, setConnected, setURLName, toString
 

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.
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
url

IMAPStore

protected IMAPStore(Session session,
                    URLName url,
                    String name,
                    int defaultPort,
                    boolean isSSL)
Constructor used by this class and by IMAPSSLStore subclass.

Parameters:
session
url
name
defaultPort
isSSL
Method Detail

close

public synchronized void close()
                        throws MessagingException
Close this Store.

Overrides:
close in class Service
Throws:
MessagingException

finalize

protected void finalize()
                 throws Throwable
Overrides:
finalize in class Service
Throws:
Throwable

getDefaultFolder

public synchronized Folder getDefaultFolder()
                                     throws MessagingException
Get the default folder, representing the root of this user's namespace. Returns a closed DefaultFolder object.

Overrides:
getDefaultFolder in class Store
Throws:
MessagingException

getFolder

public synchronized Folder getFolder(String name)
                              throws MessagingException
Get named folder. Returns a new, closed IMAPFolder.

Overrides:
getFolder in class Store
Parameters:
name
Throws:
MessagingException

getFolder

public synchronized Folder getFolder(URLName url)
                              throws MessagingException
Get named folder. Returns a new, closed IMAPFolder.

Overrides:
getFolder in class Store
Parameters:
url
Throws:
MessagingException

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
Throws:
MessagingException

getQuota

public synchronized 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.

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

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
Throws:
MessagingException

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
Throws:
MessagingException

handleResponse

public void handleResponse(Response r)
Response handler method.

Parameters:
r

hasCapability

public synchronized boolean hasCapability(String capability)
                                   throws MessagingException
Return true if the specified capability string is in the list of capabilities the server announced.

Parameters:
capability
Throws:
MessagingException

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

isConnected

public synchronized boolean isConnected()
Check whether this store is connected. Override superclass method, to actually ping our server connection.

Overrides:
isConnected in class Service

protocolConnect

protected synchronized 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
pport
user
password
Throws:
MessagingException

setPassword

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 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

setQuota

public synchronized 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.

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

setUsername

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 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


This documentation differs from the official API. Jadeite adds extra features to the API including: variable font sizes, constructions examples, placeholders for classes and methods, and auto-generated “See Also” links. Additionally it is missing some items found in standard Javadoc documentation, including: generics type information, “Deprecated” tags and comments, “See Also” links, along with other minor differences. Please send any questions or feedback to bam@cs.cmu.edu.
This page displays the Jadeite version of the documention. The official Sun™ documentation can be found here at http://java.sun.com/products/javamail/javadocs/index.html.