Module org.eclipse.angus.mail
Package org.eclipse.angus.mail.imap

Class IMAPStore

java.lang.Object
jakarta.mail.Service
jakarta.mail.Store
org.eclipse.angus.mail.imap.IMAPStore
All Implemented Interfaces:
QuotaAwareStore, AutoCloseable, org.eclipse.angus.mail.iap.ResponseHandler
Direct Known Subclasses:
GmailStore, IMAPSSLStore
public class IMAPStore extends Store implements QuotaAwareStore, org.eclipse.angus.mail.iap.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 org.eclipse.angus.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 Details

  • Constructor Details

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

    • 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 org.eclipse.angus.mail.imap.protocol.IMAPProtocol newIMAPProtocol(String host, int port) throws IOException, org.eclipse.angus.mail.iap.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
      org.eclipse.angus.mail.iap.ProtocolException - for protocol errors
      Since:
      JavaMail 1.4.6

    • preLogin

      protected void preLogin(org.eclipse.angus.mail.imap.protocol.IMAPProtocol p) throws org.eclipse.angus.mail.iap.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:
      org.eclipse.angus.mail.iap.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:

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

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

    • 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(org.eclipse.angus.mail.imap.protocol.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(org.eclipse.angus.mail.iap.Response r)
      Response handler method.
      Specified by:
      handleResponse in interface org.eclipse.angus.mail.iap.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