Package com.sun.mail.imap

## Class IdleManager

- java.lang.Object
- - com.sun.mail.imap.IdleManager

    public class IdleManager
    extends java.lang.Object

IdleManager uses the optional IMAP IDLE command (RFC 2177) to watch multiple folders for new messages. IdleManager uses an Executor to execute tasks in separate threads. An Executor is typically provided by an ExecutorService. For example, for a Java SE application:

>             ExecutorService es = Executors.newCachedThreadPool();
>             final IdleManager idleManager = new IdleManager(session, es);

For a Java EE 7 application:

>             @Resource
>             ManagedExecutorService es;
>             final IdleManager idleManager = new IdleManager(session, es);

To watch for new messages in a folder, open the folder, register a listener, and ask the IdleManager to watch the folder:

>             Folder folder = store.getFolder("INBOX");
>             folder.open(Folder.READ_WRITE);
>             folder.addMessageCountListener(new MessageCountAdapter() {
>                 public void messagesAdded(MessageCountEvent ev) {
>                     Folder folder = (Folder)ev.getSource();
>                     Message[] msgs = ev.getMessages();
>                     System.out.println("Folder: " + folder +
>                         " got " + msgs.length + " new messages");
>                     try {
>                         // process new messages
>                         idleManager.watch(folder); // keep watching for new messages
>                     } catch (MessagingException mex) {
>                         // handle exception related to the Folder
>                     }
>                 }
>             });
>             idleManager.watch(folder);

This delivers the events for each folder in a separate thread, NOT using the Executor. To deliver all events in a single thread using the Executor, set the following properties for the Session (once), and then add listeners and watch the folder as above.

>             // the following should be done once...
>             Properties props = session.getProperties();
>             props.put("mail.event.scope", "session"); // or "application"
>             props.put("mail.event.executor", es);

Note that, after processing new messages in your listener, or doing any other operations on the folder in any other thread, you need to tell the IdleManager to watch for more new messages. Unless, of course, you close the folder.

The IdleManager is created with a Session, which it uses only to control debug output. A single IdleManager instance can watch multiple Folders from multiple Stores and multiple Sessions.

Due to limitations in the Java SE nio support, a `SocketChannel` must be used instead of a `Socket` to connect to the server. However, SocketChannels don't support all the features of Sockets, such as connecting through a SOCKS proxy server. SocketChannels also don't support simultaneous read and write, which means that the `idle` method can't be used if SocketChannels are being used; use this IdleManager instead. To enable support for SocketChannels instead of Sockets, set the `mail.imap.usesocketchannels` property in the Session used to access the IMAP Folder. (Or `mail.imaps.usesocketchannels` if you're using the "imaps" protocol.) This will effect all connections in that Session, but you can create another Session without this property set if you need to use the features that are incompatible with SocketChannels.

NOTE: The IdleManager, and all APIs and properties related to it, should be considered EXPERIMENTAL. They may be changed in the future in ways that are incompatible with applications using the current APIs.

Since:
  JavaMail 1.5.2

### Constructor Summary

Constructors
`IdleManager​(Session session, java.util.concurrent.Executor es)` Create an IdleManager.

### Method Summary

All Methods Instance Methods Concrete Methods
`boolean` `isRunning()` Is the IdleManager currently running? The IdleManager starts running when the Executor schedules its task.
`void` `stop()` Stop the IdleManager.
`void` `watch​(Folder folder)` Watch the Folder for new messages and other events using the IMAP IDLE command.

### Methods inherited from class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

### Constructor Detail

#### IdleManager

    public IdleManager​(Session session,
                       java.util.concurrent.Executor es)
                throws java.io.IOException

Create an IdleManager. The Session is used only to configure debugging output. The Executor is used to create the "select" thread.

Parameters:
  `session` - the Session containing configuration information
  `es` - the Executor used to create threads
Throws:
  `java.io.IOException` - for Selector failures

### Method Detail

#### isRunning

    public boolean isRunning()

Is the IdleManager currently running? The IdleManager starts running when the Executor schedules its task. The IdleManager stops running after its task detects the stop request from the `stop` method, or if it terminates abnormally due to an unexpected error.

Returns:
  true if the IdleMaanger is running
Since:
  JavaMail 1.5.5

#### watch

    public void watch​(Folder folder)
               throws MessagingException

Watch the Folder for new messages and other events using the IMAP IDLE command.

Parameters:
  `folder` - the folder to watch
Throws:
  `MessagingException` - for errors related to the folder

#### stop

    public void stop()

Stop the IdleManager. The IdleManager can not be restarted.