xmlBlaster 2.2.0 API

org.xmlBlaster.util.protocol.email
Class Pop3Driver

java.lang.Object
  extended by javax.mail.Authenticator
      extended by org.xmlBlaster.util.protocol.email.Pop3Driver
All Implemented Interfaces:
I_AdminPlugin, I_AdminPop3Driver, I_AdminService, I_AdminUsage, I_Timeout, I_Plugin, Pop3DriverMBean

public class Pop3Driver
extends javax.mail.Authenticator
implements I_Plugin, I_Timeout, Pop3DriverMBean

This class is capable to poll for emails using the POP3 protocol. Configuration is done in xmlBlasterPlugins.xml:

    <plugin id='pop3' className='org.xmlBlaster.util.protocol.email.Pop3Driver'>
    <action do='LOAD' onStartupRunlevel='7' sequence='2' 
    onFail='resource.configuration.pluginFailed'/>
    <action do='STOP' onShutdownRunlevel='7' sequence='5'/>   
    <attribute id='mail.pop3.url'>pop3://xmlBlaster:xmlBlaster@localhost:110/INBOX</attribute>
    <attribute id='pop3PollingInterval'>500</attribute>
    </plugin>
 

Switch on logging with

 -logging/org.xmlBlaster.util.protocol.email.Pop3Driver FINE
 
and add to xmlBlasterJdk14Logging.properties:
 handlers = org.xmlBlaster.util.log.XmlBlasterJdk14LoggingHandler.level = FINEST
 

Standalone test:

  1. Start a command line poller for user 'xmlBlaster':

  java -Dmail.pop3.url=pop3://xmlBlaster:xmlBlaster@localhost/INBOX org.xmlBlaster.util.protocol.email.Pop3Driver -receivePolling

 2. Send from command line an email:

 java -Dmail.smtp.url=smtp://xmlBlaster:xmlBlaster@localhost org.xmlBlaster.util.protocol.email.SmtpClient -from xmlBlaster@localhost -to xmlBlaster@localhost
 

TODO: Implement reusing inbox.getMessage() for better performance currently we reconnect for each query ( the benefit is that we don't block the POP3 server with a permanent connection).

Author:
Marcel Ruff
See Also:
James MTA, Java Mail API, Javamail tutorial, The protocol.email requirement

Field Summary
private  javax.mail.PasswordAuthentication authentication
           
static boolean CLEAR_MESSAGES
           
private  ContextNode contextNode
           
static java.lang.String DISCARD
           
private  boolean firstException
           
private  Global glob
           
private  long holdbackExpireTimeout
           
private  java.util.Map holdbackMap
           
private  boolean isConnected
           
static boolean LEAVE_MESSAGES
           
private  java.util.Map listeners
           
private static java.util.logging.Logger log
           
private  java.lang.Object mbeanHandle
          My JMX registration
private static java.lang.String messageIdFileName
           
static java.lang.String OBJECTENTRY_KEY
           
private  I_PluginConfig pluginConfig
           
private  long pollingInterval
           
static java.lang.String POP3_FOLDER
           
private  java.lang.String pop3Url
           
private  java.util.Properties props
           
private  javax.mail.Session session
           
static java.lang.String threadName
           
private  Timeout timeout
           
private  Timestamp timeoutHandle
           
protected  XbUri xbUri
           
 
Constructor Summary
Pop3Driver()
          You need to call setSessionProperties() thereafter.
 
Method Summary
 void activate()
          Activate xmlBlaster access through this protocol.
 void deActivate()
          Deactivate xmlBlaster access (standby), no clients can connect.
 int deregisterForEmail(I_ResponseListener listener)
          Deregister all existing registrations for the given listener.
 java.lang.Object deregisterForEmail(java.lang.String secretSessionId, java.lang.String requestId)
           
 java.lang.String getEnvPrefix()
          The command line key prefix
 long getHoldbackExpireTimeout()
           
private  java.lang.Long[] getHoldbackTimestamps()
           
 java.util.Map.Entry[] getListenerInterfaces()
           
 java.lang.String[] getListenerKeys()
           
 java.lang.String getListeners()
          Access a list of registered java listeners.
 javax.mail.Message getMessage()
           
 java.lang.String getMyEmailAddress()
          Returns for example "demo@localhost" which is extracted from pop3Url="pop3://demo:secret@localhost:110/INBOX"
 int getNumberOfHoldbackEmails()
          Get the number of received emails for which no java bean is interested.
 javax.mail.PasswordAuthentication getPasswordAuthentication()
          Used by Authenticator to access user name and password
 long getPollingInterval()
          Access the polling interval
static Pop3Driver getPop3Driver(Global glob, I_PluginConfig pluginConfig, java.lang.String msgIdFileName)
          The Pop3Driver is a singleton in the Global scope.
 java.lang.String getPop3Url()
          Access the POP3 MTA access configuration
 java.lang.String getProtocolId()
          Access the xmlBlaster internal name of the protocol driver.
 javax.mail.Session getSession()
          Access the mailing session.
private  javax.mail.Store getStore()
          Connect to POP3 store.
 java.lang.String getType()
          Enforced by I_Plugin
 java.lang.String getUrlWithoutPassword()
          Returns for example "pop3://demo@localhost:110/INBOX" which is extracted from pop3Url="pop3://demo:secret@localhost:110/INBOX"
 java.lang.String getUsageUrl()
           
 java.lang.String getVersion()
          Enforced by I_Plugin
private  void handleLostEmail(EmailData emailData)
           
 void init(Global glob, I_PluginConfig pluginConfig)
           
 void init(Global glob, PluginInfo pluginInfo)
          This method is called by the PluginManager (enforced by I_Plugin).
 boolean isActive()
          Access the current state
 boolean isShutdown()
          Check status
static void main(java.lang.String[] args)
          java -Dmail.pop3.url=pop3://blue:blue@localhost:110/INBOX org.xmlBlaster.util.protocol.email.Pop3Driver -receivePolling true -clearMessages false
private  java.lang.String notify(EmailData emailData, boolean calledFromHoldbackMap, java.lang.String msgIdFileName)
          Notify a listener about a new email.
 EmailData[] readInbox(boolean clear)
          Read messages from mail server with POP3.
 void registerForEmail(java.lang.String secretSessionId, java.lang.String requestId, I_ResponseListener listener)
          If you are interested in an email register it here.
protected  java.lang.String retrieveContent(javax.mail.internet.MimePart part)
          Get content text.
 void setHoldbackExpireTimeout(long holdbackExpireTimeout)
          Configure how long a not yet dispatched message shall live in the Pop3Driver map.
private  void setMessageIdFileName(java.lang.String msgIdFileName)
           
 void setPollingInterval(long pollingInterval)
          Set the polling interval
 void setPop3Url(java.lang.String pop3Url)
           
 void setSessionProperties(java.util.Properties properties, Global glob, I_PluginConfig pluginConfig)
          Set session properties and create a session.
 void setUsageUrl(java.lang.String url)
           
 void shutdown()
          Halt the plugin.
 void timeout(java.lang.Object userData)
          Polling for response messages.
private  void tryToDeliverHoldbackMails(java.lang.String msgIdFileName)
          Try to deliver hold back messages to local registrars.
 java.lang.String usage()
          JMX
 
Methods inherited from class javax.mail.Authenticator
getDefaultUserName, getRequestingPort, getRequestingPrompt, getRequestingProtocol, getRequestingSite
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

log

private static java.util.logging.Logger log

glob

private Global glob

contextNode

private ContextNode contextNode

session

private javax.mail.Session session

pop3Url

private java.lang.String pop3Url

pluginConfig

private I_PluginConfig pluginConfig

timeout

private Timeout timeout

timeoutHandle

private Timestamp timeoutHandle

pollingInterval

private long pollingInterval

props

private java.util.Properties props

listeners

private final java.util.Map listeners

firstException

private boolean firstException

isConnected

private boolean isConnected

authentication

private javax.mail.PasswordAuthentication authentication

xbUri

protected XbUri xbUri

mbeanHandle

private java.lang.Object mbeanHandle
My JMX registration


holdbackMap

private java.util.Map holdbackMap

holdbackExpireTimeout

private long holdbackExpireTimeout

CLEAR_MESSAGES

public static final boolean CLEAR_MESSAGES
See Also:
Constant Field Values

LEAVE_MESSAGES

public static final boolean LEAVE_MESSAGES
See Also:
Constant Field Values

POP3_FOLDER

public static final java.lang.String POP3_FOLDER
See Also:
Constant Field Values

threadName

public static java.lang.String threadName

OBJECTENTRY_KEY

public static final java.lang.String OBJECTENTRY_KEY

DISCARD

public static final java.lang.String DISCARD
See Also:
Constant Field Values

messageIdFileName

private static java.lang.String messageIdFileName
Constructor Detail

Pop3Driver

public Pop3Driver()
You need to call setSessionProperties() thereafter.

Method Detail

getPop3Driver

public static Pop3Driver getPop3Driver(Global glob,
                                       I_PluginConfig pluginConfig,
                                       java.lang.String msgIdFileName)
                                throws XmlBlasterException
The Pop3Driver is a singleton in the Global scope. Access this singleton for the given global, and if it doesn't exist create one instance.

Parameters:
glob -
pluginConfig -
Returns:
never null
Throws:
XmlBlasterException

setMessageIdFileName

private void setMessageIdFileName(java.lang.String msgIdFileName)

getPasswordAuthentication

public javax.mail.PasswordAuthentication getPasswordAuthentication()
Used by Authenticator to access user name and password

Overrides:
getPasswordAuthentication in class javax.mail.Authenticator

init

public void init(Global glob,
                 PluginInfo pluginInfo)
          throws XmlBlasterException
This method is called by the PluginManager (enforced by I_Plugin). The Pop3Driver singleton is registered in the Global object store.

Specified by:
init in interface I_Plugin
Throws:
XmlBlasterException
See Also:
I_Plugin.init(org.xmlBlaster.util.Global,org.xmlBlaster.util.plugin.PluginInfo)

init

public void init(Global glob,
                 I_PluginConfig pluginConfig)
          throws XmlBlasterException
Throws:
XmlBlasterException

getProtocolId

public java.lang.String getProtocolId()
Access the xmlBlaster internal name of the protocol driver.

Returns:
The configured [type] in xmlBlaster.properties, defaults to "pop3"

getType

public java.lang.String getType()
Enforced by I_Plugin

Specified by:
getType in interface I_AdminPlugin
Specified by:
getType in interface I_Plugin
Returns:
The configured type in xmlBlaster.properties, defaults to "pop3"

registerForEmail

public void registerForEmail(java.lang.String secretSessionId,
                             java.lang.String requestId,
                             I_ResponseListener listener)
If you are interested in an email register it here.

Parameters:
key - :
listener -

deregisterForEmail

public java.lang.Object deregisterForEmail(java.lang.String secretSessionId,
                                           java.lang.String requestId)

deregisterForEmail

public int deregisterForEmail(I_ResponseListener listener)
Deregister all existing registrations for the given listener.

Parameters:
listener - The listener to cleanup
Returns:
Number of registrations cleared

getListenerInterfaces

public java.util.Map.Entry[] getListenerInterfaces()

getListenerKeys

public java.lang.String[] getListenerKeys()

getListeners

public java.lang.String getListeners()
Description copied from interface: I_AdminPop3Driver
Access a list of registered java listeners.

Specified by:
getListeners in interface I_AdminPop3Driver
Returns:
Keys of interested party for incoming POP3 mails

handleLostEmail

private void handleLostEmail(EmailData emailData)

notify

private java.lang.String notify(EmailData emailData,
                                boolean calledFromHoldbackMap,
                                java.lang.String msgIdFileName)
Notify a listener about a new email. The registration remains The listener is searched as a "sessionId-requestId" and as a general "sessionId"

Parameters:
emailData -
calledFromHoldbackMap - is true if we try a redelivery
Returns:
The listener notified or null if none was found

getEnvPrefix

public java.lang.String getEnvPrefix()
The command line key prefix

Returns:
The configured type in xmlBlasterPlugins.xml, defaults to "plugin/pop3"

getVersion

public java.lang.String getVersion()
Enforced by I_Plugin

Specified by:
getVersion in interface I_AdminPlugin
Specified by:
getVersion in interface I_Plugin
Returns:
For example "1.0"

setSessionProperties

public void setSessionProperties(java.util.Properties properties,
                                 Global glob,
                                 I_PluginConfig pluginConfig)
                          throws XmlBlasterException
Set session properties and create a session.

Example settings:

 Properties props = System.getProperties();
 props.put("mail.pop3.url", "pop3://joe:secret@localhost/INBOX");
 props.put("mail.debug", "false");
 

Usage is "pop3://user:password@host:port/INBOX". Only 'INBOX' is supported for pop3. If a property is not found System.getProperty() is consulted.

Throws:
XmlBlasterException
See Also:
SMTP API, POP3 API

getHoldbackTimestamps

private java.lang.Long[] getHoldbackTimestamps()

tryToDeliverHoldbackMails

private void tryToDeliverHoldbackMails(java.lang.String msgIdFileName)
Try to deliver hold back messages to local registrars. This happens if on startup we access POP3 messages but nobody has registered yet
Switch this feature on by setting holdbackExpireTimeout to a value > 0. After the given milli seconds the message is discarded.
For example a client may on startup receive update() mails before he has initialized the CallbackEmailDriver. Those messages are kept in RAM if the client stops immediately the mails are lost but redelivered by the server after the responseTimeout.


timeout

public void timeout(java.lang.Object userData)
Polling for response messages.

Specified by:
timeout in interface I_Timeout
Parameters:
userData - You get bounced back your userData which you passed with Timeout.addTimeoutListener()

getSession

public javax.mail.Session getSession()
Access the mailing session.


getMessage

public javax.mail.Message getMessage()

getMyEmailAddress

public java.lang.String getMyEmailAddress()
Returns for example "demo@localhost" which is extracted from pop3Url="pop3://demo:secret@localhost:110/INBOX"

Returns:

getUrlWithoutPassword

public java.lang.String getUrlWithoutPassword()
Returns for example "pop3://demo@localhost:110/INBOX" which is extracted from pop3Url="pop3://demo:secret@localhost:110/INBOX"

Returns:

getStore

private javax.mail.Store getStore()
                           throws XmlBlasterException
Connect to POP3 store. NOTE: You need to call store.close() after usage to cleanup resources.

Returns:
never null
Throws:
XmlBlasterException

readInbox

public EmailData[] readInbox(boolean clear)
                      throws XmlBlasterException
Read messages from mail server with POP3.

Convenience method which returns the most important fields only

Parameters:
clear - If CLEAR_MESSAGES=true the messages are destroyed on the server
Returns:
Never null
Throws:
XmlBlasterException

getPop3Url

public java.lang.String getPop3Url()
Description copied from interface: I_AdminPop3Driver
Access the POP3 MTA access configuration

Specified by:
getPop3Url in interface I_AdminPop3Driver
Returns:
Syntax is "pop3://user:password@host:port/INBOX"

setPop3Url

public void setPop3Url(java.lang.String pop3Url)
Specified by:
setPop3Url in interface I_AdminPop3Driver
Parameters:
pop3Url - Syntax is "pop3://user:password@host:port/INBOX"

getPollingInterval

public long getPollingInterval()
Description copied from interface: I_AdminPop3Driver
Access the polling interval

Specified by:
getPollingInterval in interface I_AdminPop3Driver
Returns:
Returns the pollingInterval.

setPollingInterval

public void setPollingInterval(long pollingInterval)
Description copied from interface: I_AdminPop3Driver
Set the polling interval

Specified by:
setPollingInterval in interface I_AdminPop3Driver
Parameters:
pollingInterval - The timeout in milliseconds.

retrieveContent

protected java.lang.String retrieveContent(javax.mail.internet.MimePart part)
                                    throws javax.mail.MessagingException,
                                           java.io.IOException
Get content text.

Parameters:
part - the MimePart to check for content
Returns:
The retrieved string
Throws:
javax.mail.MessagingException
java.io.IOException

activate

public void activate()
              throws java.lang.Exception
Activate xmlBlaster access through this protocol. Triggers an immediate POP3 access and starts polling thereafter

Specified by:
activate in interface I_AdminService
Throws:
java.lang.Exception

isActive

public boolean isActive()
Description copied from interface: I_AdminService
Access the current state

Specified by:
isActive in interface I_AdminService
Returns:
true if active

deActivate

public void deActivate()
Deactivate xmlBlaster access (standby), no clients can connect.

Specified by:
deActivate in interface I_AdminService

shutdown

public void shutdown()
Halt the plugin.

Specified by:
shutdown in interface I_AdminPlugin
Specified by:
shutdown in interface I_Plugin

isShutdown

public boolean isShutdown()
Description copied from interface: I_AdminPlugin
Check status

Specified by:
isShutdown in interface I_AdminPlugin
Returns:
true if down

usage

public java.lang.String usage()
JMX

Specified by:
usage in interface I_AdminUsage
Returns:
a human readable usage help string

getUsageUrl

public java.lang.String getUsageUrl()
Specified by:
getUsageUrl in interface I_AdminUsage
Returns:
A link for JMX usage

setUsageUrl

public void setUsageUrl(java.lang.String url)
Specified by:
setUsageUrl in interface I_AdminUsage

getHoldbackExpireTimeout

public long getHoldbackExpireTimeout()
Specified by:
getHoldbackExpireTimeout in interface I_AdminPop3Driver
Returns:
Returns the holdbackExpireTimeout.

setHoldbackExpireTimeout

public void setHoldbackExpireTimeout(long holdbackExpireTimeout)
Description copied from interface: I_AdminPop3Driver
Configure how long a not yet dispatched message shall live in the Pop3Driver map. Note that the map is transient, after restart such mails are lost (but resend by the server).

Specified by:
setHoldbackExpireTimeout in interface I_AdminPop3Driver
Parameters:
holdbackExpireTimeout - The holdbackExpireTimeout to set.

getNumberOfHoldbackEmails

public int getNumberOfHoldbackEmails()
Description copied from interface: I_AdminPop3Driver
Get the number of received emails for which no java bean is interested.

Specified by:
getNumberOfHoldbackEmails in interface I_AdminPop3Driver
Returns:
Number of emails

main

public static void main(java.lang.String[] args)
java -Dmail.pop3.url=pop3://blue:blue@localhost:110/INBOX org.xmlBlaster.util.protocol.email.Pop3Driver -receivePolling true -clearMessages false

See Also:
for other properties

xmlBlaster 2.2.0 API

Copyright © 1999-2014 The xmlBlaster.org contributers.