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:
For a Java EE 7 application:ExecutorService es = Executors.newCachedThreadPool(); 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:@Resource ManagedExecutorService es; final IdleManager idleManager = new IdleManager(session, es);
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.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);
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 following should be done once... Properties props = session.getProperties(); props.put("mail.event.scope", "session"); // or "application" props.put("mail.event.executor", es);
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 aSocket
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 theidle
method can't be used if SocketChannels are being used; use this IdleManager instead. To enable support for SocketChannels instead of Sockets, set themail.imap.usesocketchannels
property in the Session used to access the IMAP Folder. (Ormail.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
-
-
Field Summary
Fields Modifier and Type Field Description private boolean
die
private java.util.concurrent.Executor
es
private MailLogger
logger
private boolean
running
private java.nio.channels.Selector
selector
private java.util.Queue<IMAPFolder>
toAbort
private java.util.Queue<IMAPFolder>
toWatch
-
Constructor Summary
Constructors Constructor Description IdleManager(Session session, java.util.concurrent.Executor es)
Create an IdleManager.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description private static java.lang.String
folderName(Folder folder)
Return the fully qualified name of the folder, for use in log messages.boolean
isRunning()
Is the IdleManager currently running? The IdleManager starts running when the Executor schedules its task.private void
processKeys()
Process the selected keys.(package private) void
requestAbort(IMAPFolder folder)
Request that the specified folder abort an IDLE command.private void
select()
Run theselect
loop to poll each watched folder for events sent from the server.void
stop()
Stop the IdleManager.private void
unwatchAll()
Stop watching all folders.void
watch(Folder folder)
Watch the Folder for new messages and other events using the IMAP IDLE command.private void
watchAll()
Register all of the folders in the queue with the selector, switching them to nonblocking I/O mode first.
-
-
-
Field Detail
-
es
private java.util.concurrent.Executor es
-
selector
private java.nio.channels.Selector selector
-
logger
private MailLogger logger
-
die
private volatile boolean die
-
running
private volatile boolean running
-
toWatch
private java.util.Queue<IMAPFolder> toWatch
-
toAbort
private java.util.Queue<IMAPFolder> toAbort
-
-
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 informationes
- 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 thestop
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
-
requestAbort
void requestAbort(IMAPFolder folder)
Request that the specified folder abort an IDLE command. We can't do the abort directly because the DONE message needs to be sent through the (potentially) SSL socket, which means we need to be in blocking I/O mode. We can only switch to blocking I/O mode when not selecting, so wake up the selector, which will process this request when it wakes up.
-
select
private void select()
Run theselect
loop to poll each watched folder for events sent from the server.
-
watchAll
private void watchAll()
Register all of the folders in the queue with the selector, switching them to nonblocking I/O mode first.
-
processKeys
private void processKeys() throws java.io.IOException
Process the selected keys.- Throws:
java.io.IOException
-
unwatchAll
private void unwatchAll()
Stop watching all folders. Cancel any selection keys and, most importantly, switch the channel back to blocking mode. If there's any folders waiting to be watched, need to abort them too.
-
stop
public void stop()
Stop the IdleManager. The IdleManager can not be restarted.
-
folderName
private static java.lang.String folderName(Folder folder)
Return the fully qualified name of the folder, for use in log messages. Essentially just the getURLName method, but ignoring the MessagingException that can never happen.
-
-