org.apache.geronimo.javamail.store.imap
Class IMAPStore

java.lang.Object
  javax.mail.Service
      javax.mail.Store
          org.apache.geronimo.javamail.store.imap.IMAPStore

All Implemented Interfaces:

QuotaAwareStore, IMAPUntaggedResponseHandler

Direct Known Subclasses:

IMAPSSLStore

public class IMAPStore
extends Store
implements QuotaAwareStore, IMAPUntaggedResponseHandler

IMAP implementation of javax.mail.Store POP protocol spec is implemented in org.apache.geronimo.javamail.store.pop3.IMAPConnection

Version:

$Rev: 707037 $ $Date: 2008-10-22 07:34:53 -0400 (Wed, 22 Oct 2008) $

Field Summary

protected IMAPConnectionPool	connectionPool
protected boolean	debug
protected PrintStream	debugStream
protected static int	DEFAULT_IMAP_PORT
protected static int	DEFAULT_IMAP_SSL_PORT
protected static int	DEFAULT_STATUS_TIMEOUT
protected static String	MAIL_STATUS_TIMEOUT
protected List	openFolders
protected ProtocolProperties	props
protected IMAPRootFolder	root

Fields inherited from class javax.mail.Service

session, url

Constructor Summary

	IMAPStore(Session session, URLName urlName) Construct an IMAPStore item.
protected	IMAPStore(Session session, URLName urlName, String protocol, boolean sslConnection, int defaultPort) Protected common constructor used by both the IMAPStore and the IMAPSSLStore to initialize the Store instance.

Method Summary

void	close() Close this service and terminate its physical connection.
protected void	closeOpenFolders() Close all open folders.
protected void	finalize() Finalizer to perform IMAPStore() cleanup when no longer in use.
Folder	getDefaultFolder() Return a Folder object that represents the root of the namespace for the current user.
Folder	getFolder(String name) Return the Folder corresponding to the given name.
Folder	getFolder(URLName url) Return the folder identified by the URLName; the URLName must refer to this Store.
protected Folder[]	getNamespaceFolders(List namespaces) Convert a List of IMAPNamespace definitions into an array of Folder instances.
protected IMAPNamespaceResponse	getNamespaces() Get the namespace information from the IMAP server.
Folder[]	getPersonalNamespaces() Return the root folders of the personal namespace belonging to the current user.
Quota[]	getQuota(String root) Get the quotas for the specified root element.
Folder[]	getSharedNamespaces() Return the root folders of namespaces that are intended to be shared between users.
protected IMAPConnection	getStoreConnection() Retrieve the server connection created by this store.
Folder[]	getUserNamespaces(String user) Return the root folders of the personal namespaces belonging to the supplied user.
boolean	handleResponse(IMAPUntaggedResponse response) Handle an unsolicited response from the server.
boolean	hasCapability(String capability) Test if this connection has a given capability.
boolean	isConnected() Test to see if we're still connected.
protected boolean	protocolConnect(String host, int port, String username, String password) Attempt the protocol-specific connection; subclasses should override this to establish a connection in the appropriate manner.
protected void	releaseStoreConnection(IMAPConnection connection)
void	setQuota(Quota quota) Set a quota item.

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

DEFAULT_IMAP_PORT

protected static final int DEFAULT_IMAP_PORT

See Also:

Constant Field Values

DEFAULT_IMAP_SSL_PORT

protected static final int DEFAULT_IMAP_SSL_PORT

See Also:

Constant Field Values

MAIL_STATUS_TIMEOUT

protected static final String MAIL_STATUS_TIMEOUT

See Also:

Constant Field Values

DEFAULT_STATUS_TIMEOUT

protected static final int DEFAULT_STATUS_TIMEOUT

See Also:

Constant Field Values

props

protected ProtocolProperties props

connectionPool

protected IMAPConnectionPool connectionPool

root

protected IMAPRootFolder root

openFolders

protected List openFolders

debugStream

protected PrintStream debugStream

debug

protected boolean debug

Constructor Detail

IMAPStore

public IMAPStore(Session session,
                 URLName urlName)

Construct an IMAPStore item.

Parameters:

session - The owning javamail Session.

urlName - The Store urlName, which can contain server target information.

IMAPStore

protected IMAPStore(Session session,
                    URLName urlName,
                    String protocol,
                    boolean sslConnection,
                    int defaultPort)

Protected common constructor used by both the IMAPStore and the IMAPSSLStore to initialize the Store instance.

Parameters:

session - The Session we're attached to.

urlName - The urlName.

protocol - The protocol name.

sslConnection - The sslConnection flag.

defaultPort - The default connection port.

Method Detail

protocolConnect

protected boolean protocolConnect(String host,
                                  int port,
                                  String username,
                                  String password)
                           throws MessagingException

Attempt the protocol-specific connection; subclasses should override this to establish a connection in the appropriate manner. This method should return true if the connection was established. It may return false to cause the Service.connect(String, int, String, String) method to reattempt the connection after trying to obtain user and password information from the user. Alternatively it may throw a AuthenticatedFailedException to abandon the conection attempt.

Overrides:

protocolConnect in class Service

Parameters:

host - The target host name of the service.

port - The connection port for the service.

user - The user name used for the connection.

password - The password used for the connection.

Returns:

true if a connection was established, false if there was authentication error with the connection.

Throws:

AuthenticationFailedException - if authentication fails

MessagingException - for other failures

close

public void close()
           throws MessagingException

Close this service and terminate its physical connection. The default implementation simply calls setConnected(false) and then sends a CLOSED event to all registered ConnectionListeners. Subclasses overriding this method should still ensure it is closed; they should also ensure that it is called if the connection is closed automatically, for for example in a finalizer.

Overrides:

close in class Service

Throws:

MessagingException - if there were errors closing; the connection is still closed

getDefaultFolder

public Folder getDefaultFolder()
                        throws MessagingException

Return a Folder object that represents the root of the namespace for the current user. Note that in some store configurations (such as IMAP4) the root folder might not be the INBOX folder.

Specified by:

getDefaultFolder in class Store

Returns:

the root Folder

Throws:

MessagingException - if there was a problem accessing the store

getFolder

public Folder getFolder(String name)
                 throws MessagingException

Return the Folder corresponding to the given name. The folder might not physically exist; the Folder.exists() method can be used to determine if it is real.

Specified by:

getFolder in class Store

Parameters:

name - the name of the Folder to return

Returns:

the corresponding folder

Throws:

MessagingException - if there was a problem accessing the store

getFolder

public Folder getFolder(URLName url)
                 throws MessagingException

Return the folder identified by the URLName; the URLName must refer to this Store. Implementations may use the URLName.getFile() method to determined the folder name.

Specified by:

getFolder in class Store

Parameters:

url -

Returns:

the corresponding folder

Throws:

MessagingException - if there was a problem accessing the store

getPersonalNamespaces

public Folder[] getPersonalNamespaces()
                               throws MessagingException

Return the root folders of the personal namespace belonging to the current user. The default implementation simply returns an array containing the folder returned by getDefaultFolder().

Overrides:

getPersonalNamespaces in class Store

Returns:

the root folders of the user's peronal namespaces

Throws:

MessagingException - if there was a problem accessing the store

getUserNamespaces

public Folder[] getUserNamespaces(String user)
                           throws MessagingException

Return the root folders of the personal namespaces belonging to the supplied user. The default implementation simply returns an empty array.

Overrides:

getUserNamespaces in class Store

Parameters:

user - the user whose namespaces should be returned

Returns:

the root folders of the given user's peronal namespaces

Throws:

MessagingException - if there was a problem accessing the store

getSharedNamespaces

public Folder[] getSharedNamespaces()
                             throws MessagingException

Return the root folders of namespaces that are intended to be shared between users. The default implementation simply returns an empty array.

Overrides:

getSharedNamespaces in class Store

Returns:

the root folders of all shared namespaces

Throws:

MessagingException - if there was a problem accessing the store

getQuota

public Quota[] getQuota(String root)
                 throws MessagingException

Get the quotas for the specified root element.

Specified by:

getQuota in interface QuotaAwareStore

Parameters:

root - The root name for the quota information.

Returns:

An array of Quota objects defined for the root.

Throws:

MessagingException - if the quotas cannot be retrieved

setQuota

public void setQuota(Quota quota)
              throws MessagingException

Set a quota item. The root contained in the Quota item identifies the quota target.

Specified by:

setQuota in interface QuotaAwareStore

Parameters:

quota - The source quota item.

Throws:

MessagingException - if the quota cannot be set

isConnected

public boolean isConnected()

Test to see if we're still connected. This will ping the server to see if we're still alive.

Overrides:

isConnected in class Service

Returns:

true if we have a live, active culture, false otherwise.

getStoreConnection

protected IMAPConnection getStoreConnection()
                                     throws MessagingException

Retrieve the server connection created by this store.

Returns:

The active connection object.

Throws:

MessagingException

releaseStoreConnection

protected void releaseStoreConnection(IMAPConnection connection)
                               throws MessagingException

Throws:

MessagingException

closeOpenFolders

protected void closeOpenFolders()

Close all open folders. We have a small problem here with a race condition. There's no safe, single synchronization point for us to block creation of new folders while we're closing. So we make a copy of the folders list, close all of those folders, and keep repeating until we're done.

getNamespaces

protected IMAPNamespaceResponse getNamespaces()
                                       throws MessagingException

Get the namespace information from the IMAP server.

Returns:

An IMAPNamespaceResponse with the namespace information.

Throws:

MessagingException

getNamespaceFolders

protected Folder[] getNamespaceFolders(List namespaces)
                                throws MessagingException

Convert a List of IMAPNamespace definitions into an array of Folder instances.

Parameters:

namespaces - The namespace List

Returns:

An array of the same size as the namespace list containing a Folder instance for each defined namespace.

Throws:

MessagingException

hasCapability

public boolean hasCapability(String capability)

Test if this connection has a given capability.

Parameters:

capability - The capability name.

Returns:

true if this capability is in the list, false for a mismatch.

handleResponse

public boolean handleResponse(IMAPUntaggedResponse response)

Handle an unsolicited response from the server. Most unsolicited responses are replies to specific commands sent to the server. The remainder must be handled by the Store or the Folder using the connection. These are critical to handle, as events such as expunged messages will alter the sequence numbers of the live messages. We need to keep things in sync.

Specified by:

handleResponse in interface IMAPUntaggedResponseHandler

Parameters:

response - The UntaggedResponse to process.

Returns:

true if we handled this response and no further handling is required. false means this one wasn't one of ours.

finalize

protected void finalize()
                 throws Throwable

Finalizer to perform IMAPStore() cleanup when no longer in use.

Overrides:

finalize in class Service

Throws:

Throwable