- java.lang.Object
-
- javax.mail.Service
-
- javax.mail.Store
-
- com.sun.mail.imap.IMAPStore
-
- All Implemented Interfaces:
ResponseHandler
,java.lang.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 anIMAPStore
object and use the methods on this class. ThegetQuota
andsetQuota
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 Description protected java.lang.String
authorizationID
protected int
defaultPort
protected java.lang.String
host
static java.lang.String
ID_ADDRESS
static java.lang.String
ID_ARGUMENTS
static java.lang.String
ID_COMMAND
static java.lang.String
ID_DATE
static java.lang.String
ID_ENVIRONMENT
static java.lang.String
ID_NAME
static java.lang.String
ID_OS
static java.lang.String
ID_OS_VERSION
static java.lang.String
ID_SUPPORT_URL
static java.lang.String
ID_VENDOR
static java.lang.String
ID_VERSION
protected boolean
isSSL
protected MailLogger
logger
protected java.lang.String
name
protected java.lang.String
password
protected java.lang.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 java.lang.String
saslRealm
protected java.lang.String
user
-
Constructor Summary
Constructors Modifier Constructor 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, java.lang.String name, boolean isSSL)
Constructor used by this class and by IMAPSSLStore subclass.
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method 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(java.lang.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.java.lang.String
getProxyAuthUser()
Get the user name to be used with the PROXYAUTH command.Quota[]
getQuota(java.lang.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(java.lang.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(java.lang.String capability)
Return true if the specified capability string is in the list of capabilities the server announced.java.util.Map<java.lang.String,java.lang.String>
id(java.util.Map<java.lang.String,java.lang.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(java.lang.String fullName, char separator)
Create an IMAPFolder object.protected IMAPFolder
newIMAPFolder(java.lang.String fullName, char separator, java.lang.Boolean isNamespace)
Create an IMAPFolder object.protected IMAPProtocol
newIMAPProtocol(java.lang.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(java.lang.String host, int pport, java.lang.String user, java.lang.String password)
Implementation of protocolConnect().void
setPassword(java.lang.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(java.lang.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(java.lang.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
-
-
-
-
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 java.lang.String ID_NAME
- See Also:
- Constant Field Values
-
ID_VERSION
public static final java.lang.String ID_VERSION
- See Also:
- Constant Field Values
-
ID_OS
public static final java.lang.String ID_OS
- See Also:
- Constant Field Values
-
ID_OS_VERSION
public static final java.lang.String ID_OS_VERSION
- See Also:
- Constant Field Values
-
ID_VENDOR
public static final java.lang.String ID_VENDOR
- See Also:
- Constant Field Values
-
ID_SUPPORT_URL
public static final java.lang.String ID_SUPPORT_URL
- See Also:
- Constant Field Values
-
ID_ADDRESS
public static final java.lang.String ID_ADDRESS
- See Also:
- Constant Field Values
-
ID_DATE
public static final java.lang.String ID_DATE
- See Also:
- Constant Field Values
-
ID_COMMAND
public static final java.lang.String ID_COMMAND
- See Also:
- Constant Field Values
-
ID_ARGUMENTS
public static final java.lang.String ID_ARGUMENTS
- See Also:
- Constant Field Values
-
ID_ENVIRONMENT
public static final java.lang.String ID_ENVIRONMENT
- See Also:
- Constant Field Values
-
name
protected final java.lang.String name
-
defaultPort
protected final int defaultPort
-
isSSL
protected final boolean isSSL
-
host
protected java.lang.String host
-
user
protected java.lang.String user
-
password
protected java.lang.String password
-
proxyAuthUser
protected java.lang.String proxyAuthUser
-
authorizationID
protected java.lang.String authorizationID
-
saslRealm
protected java.lang.String saslRealm
-
logger
protected MailLogger logger
-
-
Method Detail
-
protocolConnect
protected boolean protocolConnect(java.lang.String host, int pport, java.lang.String user, java.lang.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
, andpassword
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 classService
- Parameters:
host
- the name of the host to connect topport
- the port to use (-1 means use default port)user
- the name of the user to login aspassword
- the user's password- Returns:
- true if connection successful, false if authentication failed
- Throws:
AuthenticationFailedException
- for authentication failuresMessagingException
- for non-authentication failures
-
newIMAPProtocol
protected IMAPProtocol newIMAPProtocol(java.lang.String host, int port) throws java.io.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 nameport
- the port number- Returns:
- the new IMAPProtocol object
- Throws:
java.io.IOException
- for I/O errorsProtocolException
- 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(java.lang.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(java.lang.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(java.lang.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(java.lang.String user)
Set the user name to be used with the PROXYAUTH command. The PROXYAUTH user name can also be set using themail.imap.proxyauth.user
property when this Store is created.- Parameters:
user
- the user name to set- Since:
- JavaMail 1.5.1
-
getProxyAuthUser
public java.lang.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 classService
- 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 interfacejava.lang.AutoCloseable
- Overrides:
close
in classService
- Throws:
MessagingException
- for errors while closing- See Also:
ConnectionEvent
-
finalize
protected void finalize() throws java.lang.Throwable
Description copied from class:Service
Stop the event dispatcher thread so the queue can be garbage collected.
-
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 classStore
- Returns:
- the root Folder
- Throws:
MessagingException
- for other failures
-
getFolder
public Folder getFolder(java.lang.String name) throws MessagingException
Get named folder. Returns a new, closed IMAPFolder.- Specified by:
getFolder
in classStore
- 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 classStore
- Parameters:
url
- URLName that denotes a folder- Returns:
- Folder object
- Throws:
MessagingException
- for other failures- See Also:
URLName
-
newIMAPFolder
protected IMAPFolder newIMAPFolder(java.lang.String fullName, char separator, java.lang.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 folderseparator
- the separator character for the folder hierarchyisNamespace
- does this name represent a namespace?- Returns:
- the new IMAPFolder object
-
newIMAPFolder
protected IMAPFolder newIMAPFolder(java.lang.String fullName, char separator)
Create an IMAPFolder object. Call the newIMAPFolder method above with a null isNamespace.- Parameters:
fullName
- the full name of the folderseparator
- 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 classStore
- Returns:
- array of Folder objects
- Throws:
MessagingException
- for other failures
-
getUserNamespaces
public Folder[] getUserNamespaces(java.lang.String user) throws MessagingException
Using the IMAP NAMESPACE command (RFC 2342), return a set of folders representing the User's namespaces.- Overrides:
getUserNamespaces
in classStore
- 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 classStore
- Returns:
- array of Folder objects
- Throws:
MessagingException
- for other failures
-
getQuota
public Quota[] getQuota(java.lang.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 interfaceQuotaAwareStore
- 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 thegetQuota
method, but it need not be.- Specified by:
setQuota
in interfaceQuotaAwareStore
- 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 interfaceResponseHandler
-
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 aConnectionListener
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
ConnectionListener
s as events with a type ofIMAPStore.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 theidle
method onIMAPFolder
.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 extensionjava.lang.IllegalStateException
- if the store isn't connected- Since:
- JavaMail 1.4.1
-
id
public java.util.Map<java.lang.String,java.lang.String> id(java.util.Map<java.lang.String,java.lang.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
-
-