public class IMAPStore extends Store implements QuotaAwareStore, ResponseHandler
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.
Modifier and Type | Class and Description |
---|---|
(package private) static class |
IMAPStore.ConnectionPool |
Modifier and Type | Field and Description |
---|---|
private int |
appendBufferSize |
protected java.lang.String |
authorizationID |
private int |
blksize |
private boolean |
closeFoldersOnStoreFailure |
private boolean |
connectionFailed |
private java.lang.Object |
connectionFailedLock |
private boolean |
debugpassword |
private boolean |
debugusername |
protected int |
defaultPort |
private boolean |
enableCompress |
private boolean |
enableImapEvents |
private boolean |
enableResponseEvents |
private boolean |
enableSASL |
private boolean |
enableStartTLS |
private boolean |
finalizeCleanClose |
private java.lang.reflect.Constructor<?> |
folderConstructor |
private java.lang.reflect.Constructor<?> |
folderConstructorLI |
private boolean |
forceClose |
private boolean |
forcePasswordRefresh |
private java.lang.String |
guid |
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 |
private boolean |
ignoreSize |
protected boolean |
isSSL |
protected MailLogger |
logger |
private boolean |
messageCacheDebug |
private int |
minIdleTime |
protected java.lang.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.
|
protected java.lang.String |
password |
private boolean |
peek |
private IMAPStore.ConnectionPool |
pool |
private int |
port |
protected java.lang.String |
proxyAuthUser |
private boolean |
requireStartTLS |
static int |
RESPONSE
A special event type for a StoreEvent to indicate an IMAP
response, if the mail.imap.enableimapevents property is set.
|
private java.lang.String[] |
saslMechanisms |
protected java.lang.String |
saslRealm |
private int |
statusCacheTimeout |
private boolean |
throwSearchException |
protected java.lang.String |
user |
private boolean |
usingSSL |
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,
java.lang.String name,
boolean isSSL)
Constructor used by this class and by IMAPSSLStore subclass.
|
Modifier and Type | Method and Description |
---|---|
(package private) boolean |
allowReadOnlySelect()
If a SELECT succeeds, but indicates that the folder is
READ-ONLY, and the user asked to open the folder READ_WRITE,
do we allow the open to succeed?
|
private void |
authenticate(IMAPProtocol p,
java.lang.String authzid,
java.lang.String user,
java.lang.String password)
Authenticate using one of the non-SASL mechanisms.
|
private void |
checkConnected() |
private void |
cleanup()
Cleanup before dying.
|
void |
close()
Close this Store.
|
private void |
closeAllFolders(boolean force)
Close all open Folders.
|
private void |
emptyConnectionPool(boolean force)
Empty the connection pool.
|
protected void |
finalize()
Stop the event dispatcher thread so the queue can be garbage collected.
|
(package private) int |
getAppendBufferSize()
Get the maximum size of a message to buffer for append.
|
(package private) MailLogger |
getConnectionPoolLogger()
Return the connection pool logger.
|
Folder |
getDefaultFolder()
Get the default folder, representing the root of this user's
namespace.
|
(package private) int |
getFetchBlockSize()
Get the block size to use for fetch requests on this Store.
|
Folder |
getFolder(java.lang.String name)
Get named folder.
|
Folder |
getFolder(URLName url)
Get named folder.
|
(package private) IMAPProtocol |
getFolderStoreProtocol()
Get a store protocol object for use by a folder.
|
(package private) boolean |
getMessageCacheDebug()
Report whether message cache debugging is enabled.
|
(package private) int |
getMinIdleTime()
Get the minimum amount of time to delay when returning from idle.
|
private Namespaces |
getNamespaces() |
(package private) boolean |
getPeek()
Get the default "peek" value.
|
Folder[] |
getPersonalNamespaces()
Using the IMAP NAMESPACE command (RFC 2342), return a set
of folders representing the Personal namespaces.
|
(package private) IMAPProtocol |
getProtocol(IMAPFolder folder) |
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.
|
(package private) Session |
getSession()
Get a reference to the session.
|
Folder[] |
getSharedNamespaces()
Using the IMAP NAMESPACE command (RFC 2342), return a set
of folders representing the Shared namespaces.
|
(package private) int |
getStatusCacheTimeout()
Get the number of milliseconds to cache STATUS response.
|
private IMAPProtocol |
getStoreProtocol()
Get this Store's protocol connection.
|
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.
|
(package private) void |
handleResponseCode(Response r)
Handle notifications and alerts.
|
boolean |
hasCapability(java.lang.String capability)
Return true if the specified capability string is in the list
of capabilities the server announced.
|
(package private) boolean |
hasSeparateStoreConnection()
Report whether the separateStoreConnection is set.
|
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.
|
(package private) boolean |
ignoreBodyStructureSize()
Ignore the size reported in the BODYSTRUCTURE when fetching data?
|
boolean |
isConnected()
Check whether this store is connected.
|
(package private) boolean |
isConnectionPoolFull()
Report whether the connection pool is full.
|
boolean |
isSSL()
Does this IMAPStore use SSL when connecting to the server?
|
private void |
login(IMAPProtocol p,
java.lang.String u,
java.lang.String pw) |
private Folder[] |
namespaceToFolders(Namespaces.Namespace[] ns,
java.lang.String user) |
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().
|
private void |
refreshPassword() |
(package private) void |
releaseFolderStoreProtocol(IMAPProtocol protocol)
Release a store protocol object that was being used by a folder.
|
(package private) void |
releaseProtocol(IMAPFolder folder,
IMAPProtocol protocol)
Release the protocol object back to the connection pool.
|
private void |
releaseStoreProtocol(IMAPProtocol protocol)
Release the store connection.
|
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).
|
(package private) boolean |
throwSearchException()
Throw a SearchException if the search expression is too complex?
|
private void |
timeoutConnections()
Check to see if it's time to shrink the connection pool.
|
private java.lang.String |
tracePassword(java.lang.String password) |
private java.lang.String |
traceUser(java.lang.String user) |
private void |
waitIfIdle() |
addFolderListener, addStoreListener, notifyFolderListeners, notifyFolderRenamedListeners, notifyStoreListeners, removeFolderListener, removeStoreListener
addConnectionListener, connect, connect, connect, connect, getURLName, notifyConnectionListeners, queueEvent, removeConnectionListener, setConnected, setURLName, toString
public static final int RESPONSE
public static final java.lang.String ID_NAME
public static final java.lang.String ID_VERSION
public static final java.lang.String ID_OS
public static final java.lang.String ID_OS_VERSION
public static final java.lang.String ID_VENDOR
public static final java.lang.String ID_SUPPORT_URL
public static final java.lang.String ID_ADDRESS
public static final java.lang.String ID_DATE
public static final java.lang.String ID_COMMAND
public static final java.lang.String ID_ARGUMENTS
public static final java.lang.String ID_ENVIRONMENT
protected final java.lang.String name
protected final int defaultPort
protected final boolean isSSL
private final int blksize
private boolean ignoreSize
private final int statusCacheTimeout
private final int appendBufferSize
private final int minIdleTime
private volatile int port
protected java.lang.String host
protected java.lang.String user
protected java.lang.String password
protected java.lang.String proxyAuthUser
protected java.lang.String authorizationID
protected java.lang.String saslRealm
private Namespaces namespaces
private boolean enableStartTLS
private boolean requireStartTLS
private boolean usingSSL
private boolean enableSASL
private java.lang.String[] saslMechanisms
private boolean forcePasswordRefresh
private boolean enableResponseEvents
private boolean enableImapEvents
private java.lang.String guid
private boolean throwSearchException
private boolean peek
private boolean closeFoldersOnStoreFailure
private boolean enableCompress
private boolean finalizeCleanClose
private volatile boolean connectionFailed
private volatile boolean forceClose
private final java.lang.Object connectionFailedLock
private boolean debugusername
private boolean debugpassword
protected MailLogger logger
private boolean messageCacheDebug
private volatile java.lang.reflect.Constructor<?> folderConstructor
private volatile java.lang.reflect.Constructor<?> folderConstructorLI
private final IMAPStore.ConnectionPool pool
private ResponseHandler nonStoreResponseHandler
public IMAPStore(Session session, URLName url)
session
- the Sessionurl
- the URLName of this storeprotected boolean protocolConnect(java.lang.String host, int pport, java.lang.String user, java.lang.String password) throws MessagingException
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.
protocolConnect
in class Service
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 passwordAuthenticationFailedException
- for authentication failuresMessagingException
- for non-authentication failuresprotected IMAPProtocol newIMAPProtocol(java.lang.String host, int port) throws java.io.IOException, ProtocolException
host
- the host nameport
- the port numberjava.io.IOException
- for I/O errorsProtocolException
- for protocol errorsprivate void login(IMAPProtocol p, java.lang.String u, java.lang.String pw) throws ProtocolException
ProtocolException
private void authenticate(IMAPProtocol p, java.lang.String authzid, java.lang.String user, java.lang.String password) throws ProtocolException
p
- the IMAPProtocol objectauthzid
- the authorization IDuser
- the user namepassword
- the passwordProtocolException
- on failuresprotected void preLogin(IMAPProtocol p) throws ProtocolException
The implementation of this method in this class does nothing.
p
- the IMAPProtocol connectionProtocolException
- for protocol errorspublic boolean isSSL()
public void setUsername(java.lang.String user)
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.
user
- the user name for the storepublic void setPassword(java.lang.String password)
Most applications will never need to use this method.
password
- the password for the storeIMAPProtocol getProtocol(IMAPFolder folder) throws MessagingException
MessagingException
private IMAPProtocol getStoreProtocol() throws ProtocolException
ProtocolException
IMAPProtocol getFolderStoreProtocol() throws ProtocolException
ProtocolException
private void refreshPassword()
boolean allowReadOnlySelect()
boolean hasSeparateStoreConnection()
MailLogger getConnectionPoolLogger()
boolean getMessageCacheDebug()
boolean isConnectionPoolFull()
void releaseProtocol(IMAPFolder folder, IMAPProtocol protocol)
private void releaseStoreProtocol(IMAPProtocol protocol)
void releaseFolderStoreProtocol(IMAPProtocol protocol)
private void emptyConnectionPool(boolean force)
private void timeoutConnections()
int getFetchBlockSize()
boolean ignoreBodyStructureSize()
Session getSession()
int getStatusCacheTimeout()
int getAppendBufferSize()
int getMinIdleTime()
boolean throwSearchException()
boolean getPeek()
public boolean hasCapability(java.lang.String capability) throws MessagingException
capability
- the capability stringMessagingException
- for failurespublic void setProxyAuthUser(java.lang.String user)
mail.imap.proxyauth.user
property when this
Store is created.user
- the user name to setpublic java.lang.String getProxyAuthUser()
public boolean isConnected()
isConnected
in class Service
public void close() throws MessagingException
close
in interface java.lang.AutoCloseable
close
in class Service
MessagingException
- for errors while closingConnectionEvent
protected void finalize() throws java.lang.Throwable
Service
private void cleanup()
private void closeAllFolders(boolean force)
public Folder getDefaultFolder() throws MessagingException
getDefaultFolder
in class Store
MessagingException
- for other failurespublic Folder getFolder(java.lang.String name) throws MessagingException
getFolder
in class Store
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.MessagingException
- for other failuresFolder.exists()
,
Folder.create(int)
public Folder getFolder(URLName url) throws MessagingException
getFolder
in class Store
url
- URLName that denotes a folderMessagingException
- for other failuresURLName
protected IMAPFolder newIMAPFolder(java.lang.String fullName, char separator, java.lang.Boolean isNamespace)
fullName
- the full name of the folderseparator
- the separator character for the folder hierarchyisNamespace
- does this name represent a namespace?protected IMAPFolder newIMAPFolder(java.lang.String fullName, char separator)
fullName
- the full name of the folderseparator
- the separator character for the folder hierarchyprotected IMAPFolder newIMAPFolder(ListInfo li)
li
- the ListInfo for the folderpublic Folder[] getPersonalNamespaces() throws MessagingException
getPersonalNamespaces
in class Store
MessagingException
- for other failurespublic Folder[] getUserNamespaces(java.lang.String user) throws MessagingException
getUserNamespaces
in class Store
user
- the user nameMessagingException
- for other failurespublic Folder[] getSharedNamespaces() throws MessagingException
getSharedNamespaces
in class Store
MessagingException
- for other failuresprivate Namespaces getNamespaces() throws MessagingException
MessagingException
private Folder[] namespaceToFolders(Namespaces.Namespace[] ns, java.lang.String user)
public Quota[] getQuota(java.lang.String root) throws MessagingException
getQuota
in interface QuotaAwareStore
root
- the name of the quota rootMessagingException
- if the server doesn't support the
QUOTA extensionpublic void setQuota(Quota quota) throws MessagingException
getQuota
method, but it need not be.setQuota
in interface QuotaAwareStore
quota
- the quota to setMessagingException
- if the server doesn't support the
QUOTA extensionprivate void checkConnected()
public void handleResponse(Response r)
handleResponse
in interface ResponseHandler
public void idle() throws MessagingException
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
ConnectionListener
s 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.
MessagingException
- if the server doesn't support the
IDLE extensionjava.lang.IllegalStateException
- if the store isn't connectedprivate void waitIfIdle() throws ProtocolException
ProtocolException
public java.util.Map<java.lang.String,java.lang.String> id(java.util.Map<java.lang.String,java.lang.String> clientParams) throws MessagingException
clientParams
- a Map of keys and values identifying the clientMessagingException
- if the server doesn't support the
ID extensionvoid handleResponseCode(Response r)
private java.lang.String traceUser(java.lang.String user)
private java.lang.String tracePassword(java.lang.String password)