org.xmlBlaster.util.protocol.email
Class Pop3Driver

java.lang.Object
  javax.mail.Authenticator
      org.xmlBlaster.util.protocol.email.Pop3Driver

All Implemented Interfaces:

I_AdminPlugin, I_AdminPop3Driver, I_AdminService, I_AdminUsage, I_Plugin, I_Timeout, 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
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

Fields inherited from class javax.mail.Authenticator

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) 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) 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.
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() 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

Constructor Detail

Pop3Driver

public Pop3Driver()

You need to call setSessionProperties() thereafter.

Method Detail

getPop3Driver

public static Pop3Driver getPop3Driver(Global glob,
                                       I_PluginConfig pluginConfig)
                                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

getPasswordAuthentication

public javax.mail.PasswordAuthentication getPasswordAuthentication()

Used by Authenticator to access user name and password

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

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)

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_Plugin

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()

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