com.sun.mail.imap

## Class IMAPStore

- java.lang.Object
- - javax.mail.Service
  - - javax.mail.Store
    - - com.sun.mail.imap.IMAPStore

- All Implemented Interfaces:
    ResponseHandler, QuotaAwareStore
  Direct Known Subclasses:
    GmailStore, 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 `getQuota` and `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

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected String` | `authorizationID`
    `protected int` | `defaultPort`
    `protected String` | `host`
    `protected boolean` | `isSSL`
    `protected MailLogger` | `logger`
    `protected String` | `name`
    `protected String` | `password`
    `protected 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 String` | `saslRealm`
    `protected String` | `user`

    - ### Fields inherited from class javax.mail.Service

      `debug, session, url`

  - ### Constructor Summary

    Constructors
    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, String name, boolean isSSL)` Constructor used by this class and by IMAPSSLStore subclass.

  - ### Method Summary

    Methods
    Modifier and Type | Method and 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(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.
    `Quota[]` | `getQuota(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(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(String capability)` Return true if the specified capability string is in the list of capabilities the server announced.
    `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(String fullName, char separator)` Create an IMAPFolder object.
    `protected IMAPFolder` | `newIMAPFolder(String fullName, char separator, Boolean isNamespace)` Create an IMAPFolder object.
    `protected IMAPProtocol` | `newIMAPProtocol(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(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` | `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).

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

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

    - #### name

          protected final String name

    - #### defaultPort

          protected final int defaultPort

    - #### isSSL

          protected final boolean isSSL

    - #### host

          protected String host

    - #### user

          protected String user

    - #### password

          protected String password

    - #### proxyAuthUser

          protected String proxyAuthUser

    - #### authorizationID

          protected String authorizationID

    - #### saslRealm

          protected String saslRealm

    - #### logger

          protected MailLogger logger

  - ### Constructor Detail

    - #### IMAPStore

          public IMAPStore(Session session,
                   URLName url)

      Constructor that takes a Session object and a URLName that represents a specific IMAP server.

    - #### IMAPStore

          protected IMAPStore(Session session,
                   URLName url,
                   String name,
                   boolean isSSL)

      Constructor used by this class and by IMAPSSLStore subclass.

  - ### Method Detail

    - #### 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 IMAPProtocol newIMAPProtocol(String host,
                                     int port)
                                          throws 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.
      Throws:
        `IOException`
        `ProtocolException`
      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.

      Throws:
        `ProtocolException`
      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.

      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.

      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.
      Throws:
        `MessagingException`
      Since:
        JavaMail 1.3.3

    - #### 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.
      Overrides:
        `close` in class `Service`
      Throws:
        `MessagingException` - for errors while closing
      See Also:
        `ConnectionEvent`

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

    - #### 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`
      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 class `Store`
      Parameters:
        `url` - URLName that denotes a folder
      Returns:
        Folder object
      Throws:
        `MessagingException`
      See Also:
        `URLName`

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

    - #### newIMAPFolder

          protected IMAPFolder newIMAPFolder(String fullName,
                                 char separator)

      Create an IMAPFolder object. Call the newIMAPFolder method above with a null isNamespace.

    - #### newIMAPFolder

          protected IMAPFolder newIMAPFolder(ListInfo li)

      Create an IMAPFolder object. If user supplied their own class, use it. Otherwise, call the constructor.

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

    - #### 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`
      Returns:
        array of Folder objects
      Throws:
        `MessagingException`

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

    - #### 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(Response r)

      Response handler method.
      Specified by:
        `handleResponse` in interface `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 `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.

      Throws:
        `MessagingException` - if the server doesn't support the IDLE extension
        `IllegalStateException` - if the store isn't connected
      Since:
        JavaMail 1.4.1

Copyright © 2013 Oracle. All Rights Reserved.