com.antelmann.net.mail
Class POP3Account

java.lang.Object
  com.antelmann.net.mail.POP3Account

All Implemented Interfaces:

Forgeable<POP3Account>, LoggerProvider, Iterable<javax.mail.Message>

@ThirdParty(value="javax.email")
public class POP3Account
extends Object
implements Forgeable<POP3Account>, Iterable<javax.mail.Message>, LoggerProvider

EmailAccount provides an easy way to send and receive emails via POP3/SMTP through an application. A special feature is the ability to send the same email body to lots of individual addresses, such as a customized newsletter. Note that this class is not to be used for unsolicited bulk email, but its purpose is solely to be used for legitimate subscribers of proper newsletters that abide to the appropriate Internet rules! The bulk email feature for newsletters currently only supports text messages. EmailAccount requires at least javax.mail API 1.4.2

Since:

12/30/2003

Author:

Holger Antelmann

See Also:

JNewsletterManager, EmailClientFrame, EmailAccountTableModel

Nested Class Summary

static class

POP3Account.Config encapsulates the configuration for an EmailAccount

Constructor Summary

POP3Account()
convenience constructor that uses null values (and 'from@email' as 'from'-address; parameters must be changed before use

POP3Account(File configFile)

POP3Account(POP3Account.Config settings)

POP3Account(Properties props)
uses the following property keys: pop3Server, smtpServer, user, password, from and authentication

POP3Account(Properties props, String keyPrefix)

POP3Account(String pop3Server, String smtpServer, String user, String password, String from, boolean authentication)

POP3Account(String pop3Server, String smtpServer, String user, String password, String from, boolean authentication, Logger logger)

Method Summary

void	abortActions() allows to cancel long-running operations, such as loopTest()
javax.mail.internet.MimeMessage	createMessage(Email email) if no 'from' address is configured, the embedded 'from' address is used
javax.mail.internet.MimeMessage	createTextMessage(String subject, String body) from-address is taken from this object's configuration
boolean	delete(Email email)
boolean	delete(javax.mail.Message msg)
boolean	delete(String messageId)
int	deleteFromInbox(int maxMessagesToDelete) returns the number of messages actually deleted from the POP3 inbox
int	emptyInbox() returns the number of messages deleted from the POP3 inbox
static void	expungePop3Message(javax.mail.Message msg) the associated folder must subsequently be closed with the flag set to true to actually delete the message from the inbox.
Email	extractEmail(javax.mail.Message msg)
String[]	fetchMessageIDs()
boolean	getAccessInboxBeforeSend() false by default
boolean	getAuthentication()
boolean	getDebug()
String	getFrom()
Vector<Email.Header>	getHeaders()
javax.mail.Folder	getInbox() returns the POP3 inbox from the given mail settings.
Logger	getLogger() acess to the (non-null) Logger suitable for logging entries in the context of this instance
static int	getMXCount(String hostName) looks up the 'MX'-record of the given hostName to see how many email servers are running (code taken from public domain)
String	getPassword()
String	getPop3Server()
Processor<javax.mail.Message,? extends Exception>	getSendProcessor()
javax.mail.Session	getSession()
POP3Account.Config	getSettings() returns a new instance of Settings; changing the returned instance will have no effect on this instance
String	getSmtpPassword()
int	getSmtpPort()
String	getSmtpServer()
com.sun.mail.smtp.SMTPTransport	getTransport()
String	getUser()
void	init(POP3Account.Config settings)
void	initSession() recreates the embedded session and accounts for possibly changed System settings
boolean	isRequireStartTLS()
boolean	isSmtpOverSSL()
Iterator<javax.mail.Message>	iterator() note that if there were any messages, the folder is left open until you close it
javax.mail.internet.MimeMessage	load(File emlFile)
javax.mail.internet.MimeMessage	load(InputStream in)
static javax.mail.internet.InternetAddress[]	loadAddressesFromFile(File file) calls loadAddressesFromText(String)
static javax.mail.internet.InternetAddress[]	loadAddressesFromText(String text) each address is assumed to be in an individual line.
boolean	loopTest() calls loopTest(20, 2*60).
boolean	loopTest(int waitBetweenTriesInSeconds, int timeOutInSeconds) this method tests this email account fully regarding its send/receive functionality.
boolean	loopTest(POP3Account account) calls loopTest(account, 30, 5*60).
boolean	loopTest(POP3Account account, int waitBetweenTriesInSeconds, int timeOutInSeconds) this method tests this email account externally against the given account for its sending/receiving capabilities.
Email[]	receiveEmails(boolean removeFromServer) fully downloads all messages from the inbox into Email objects
javax.mail.Message[]	receiveMessages() retrieves all messages from the INBOX but doesn't download the content.
void	resetAbortStatus() resets the abort status, so that operations can normally proceed
static POP3Account[]	retrieveAccountsFromFile(File file) constructs EmailAccount objects from a file containing the necessary configuration data.
static void	saveAccountsToFile(POP3Account[] accounts, File file)
void	send(Email email) all settings (including from address) is taken from the given Email object
void	send(javax.mail.Message msg) sends out the given message after it ran through the processor (if applicable).
void	send(String to, String subject, String messageBody) sends out a simple text email message
void	send(String to, String subject, String messageBody, File attachment) sends an email with a file attachment.
void	sendEmails(Email email, javax.mail.internet.InternetAddress[] recipients) sends the email individually to each address.
void	sendEmails(Email email, javax.mail.internet.InternetAddress[] recipients, EmailCustomizer replacerCallback, Monitor monitor) sends the email individually to each address.
void	setAccessInboxBeforeSend(boolean flag) may be necessary for special ISPs that have that requirement
void	setAllFrom(POP3Account account) copies the properties of the given object and applies them to this instance, so that its behavior in regards to the given object can be matched to the extend that the implementing class supports that behavior.
void	setAuthentication(boolean flag)
void	setDebug(boolean flag)
void	setFrom(String from)
static void	setHeaders(javax.mail.Message msg, Email.Header[] header) all headers keys and values must be String objects
void	setPassword(char[] pwd)
void	setPassword(String password) sets both, the pop3 password and the smtp password; if the smtp password is different, it must be set herafter.
void	setPop3Server(String pop3Server)
void	setRequireStartTLS(boolean flag) used to support GoogleMail, for example
void	setSendProcessor(Processor<javax.mail.Message,? extends Exception> processor) allows to set a processor that will handle messages before they get sent
void	setSmtpOverSSL(boolean smtpOverSSL)
void	setSmtpPassword(String smtpPassword) must only be set explicitly if different from the POP3 password
void	setSmtpPort(int smtpPort) default is 25; for SSL: 465; alternatively: 587
void	setSmtpServer(String smtpServer)
void	setSmtpUser(String smtpUser) must only be set explicitly if different from the POP3 user
void	setUser(String user) sets both, the pop3 user and the smtp user; if the smtp user is different, it must be set herafter.
String	toString()

Methods inherited from class java.lang.Object

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

Constructor Detail

POP3Account

public POP3Account()
            throws javax.mail.NoSuchProviderException,
                   javax.mail.internet.AddressException

convenience constructor that uses null values (and 'from@email' as 'from'-address; parameters must be changed before use

Throws:

javax.mail.NoSuchProviderException

javax.mail.internet.AddressException

POP3Account

public POP3Account(File configFile)
            throws IOException,
                   javax.mail.NoSuchProviderException,
                   javax.mail.internet.AddressException

Throws:

IOException

javax.mail.NoSuchProviderException

javax.mail.internet.AddressException

POP3Account

public POP3Account(Properties props)
            throws javax.mail.NoSuchProviderException,
                   javax.mail.internet.AddressException

uses the following property keys: pop3Server, smtpServer, user, password, from and authentication

Throws:

javax.mail.NoSuchProviderException

javax.mail.internet.AddressException

POP3Account

public POP3Account(Properties props,
                   String keyPrefix)
            throws javax.mail.NoSuchProviderException,
                   javax.mail.internet.AddressException

Throws:

javax.mail.NoSuchProviderException

javax.mail.internet.AddressException

POP3Account

public POP3Account(String pop3Server,
                   String smtpServer,
                   String user,
                   String password,
                   String from,
                   boolean authentication)
            throws javax.mail.NoSuchProviderException,
                   javax.mail.internet.AddressException

Throws:

javax.mail.NoSuchProviderException

javax.mail.internet.AddressException

POP3Account

public POP3Account(String pop3Server,
                   String smtpServer,
                   String user,
                   String password,
                   String from,
                   boolean authentication,
                   Logger logger)
            throws javax.mail.NoSuchProviderException,
                   javax.mail.internet.AddressException

Throws:

javax.mail.NoSuchProviderException

javax.mail.internet.AddressException

POP3Account

public POP3Account(POP3Account.Config settings)
            throws javax.mail.NoSuchProviderException,
                   javax.mail.internet.AddressException

Throws:

javax.mail.NoSuchProviderException

javax.mail.internet.AddressException

Method Detail

setAllFrom

public void setAllFrom(POP3Account account)

Description copied from interface: Forgeable

copies the properties of the given object and applies them to this instance, so that its behavior in regards to the given object can be matched to the extend that the implementing class supports that behavior.

Specified by:

setAllFrom in interface Forgeable<POP3Account>

Parameters:

account - the object whose behavior is to be copied to this instance

init

public void init(POP3Account.Config settings)
          throws javax.mail.NoSuchProviderException

Throws:

javax.mail.NoSuchProviderException

getSettings

public POP3Account.Config getSettings()

returns a new instance of Settings; changing the returned instance will have no effect on this instance

See Also:

init(Config)

getSession

public javax.mail.Session getSession()

getTransport

public com.sun.mail.smtp.SMTPTransport getTransport()

initSession

public void initSession()
                 throws javax.mail.NoSuchProviderException

recreates the embedded session and accounts for possibly changed System settings

Throws:

javax.mail.NoSuchProviderException

setRequireStartTLS

public void setRequireStartTLS(boolean flag)
                        throws javax.mail.NoSuchProviderException

used to support GoogleMail, for example

Throws:

javax.mail.NoSuchProviderException

isRequireStartTLS

public boolean isRequireStartTLS()

getSmtpPort

public int getSmtpPort()

setSmtpPort

public void setSmtpPort(int smtpPort)
                 throws javax.mail.NoSuchProviderException

default is 25; for SSL: 465; alternatively: 587

Throws:

javax.mail.NoSuchProviderException

isSmtpOverSSL

public boolean isSmtpOverSSL()

setSmtpOverSSL

public void setSmtpOverSSL(boolean smtpOverSSL)
                    throws javax.mail.NoSuchProviderException

Throws:

javax.mail.NoSuchProviderException

getDebug

public boolean getDebug()

setDebug

public void setDebug(boolean flag)
              throws javax.mail.NoSuchProviderException

Throws:

javax.mail.NoSuchProviderException

getPop3Server

public String getPop3Server()

setPop3Server

public void setPop3Server(String pop3Server)
                   throws javax.mail.NoSuchProviderException

Throws:

javax.mail.NoSuchProviderException

getSmtpServer

public String getSmtpServer()

setSmtpServer

public void setSmtpServer(String smtpServer)
                   throws javax.mail.NoSuchProviderException

Throws:

javax.mail.NoSuchProviderException

getUser

public String getUser()

setUser

public void setUser(String user)
             throws javax.mail.NoSuchProviderException

sets both, the pop3 user and the smtp user; if the smtp user is different, it must be set herafter.

Throws:

javax.mail.NoSuchProviderException

setSmtpUser

public void setSmtpUser(String smtpUser)
                 throws javax.mail.NoSuchProviderException

must only be set explicitly if different from the POP3 user

Throws:

javax.mail.NoSuchProviderException

getPassword

public String getPassword()

getSmtpPassword

public String getSmtpPassword()

setPassword

public void setPassword(char[] pwd)

setPassword

public void setPassword(String password)

sets both, the pop3 password and the smtp password; if the smtp password is different, it must be set herafter.

setSmtpPassword

public void setSmtpPassword(String smtpPassword)

must only be set explicitly if different from the POP3 password

getFrom

public String getFrom()

setFrom

public void setFrom(String from)
             throws javax.mail.internet.AddressException

Throws:

javax.mail.internet.AddressException

getAuthentication

public boolean getAuthentication()

setAuthentication

public void setAuthentication(boolean flag)
                       throws javax.mail.NoSuchProviderException

Throws:

javax.mail.NoSuchProviderException

getHeaders

public Vector<Email.Header> getHeaders()

getLogger

public Logger getLogger()

Description copied from interface: LoggerProvider

acess to the (non-null) Logger suitable for logging entries in the context of this instance

Specified by:

getLogger in interface LoggerProvider

setAccessInboxBeforeSend

public void setAccessInboxBeforeSend(boolean flag)

may be necessary for special ISPs that have that requirement

getAccessInboxBeforeSend

public boolean getAccessInboxBeforeSend()

false by default

receiveEmails

public Email[] receiveEmails(boolean removeFromServer)
                      throws javax.mail.MessagingException,
                             IOException

fully downloads all messages from the inbox into Email objects

Throws:

javax.mail.MessagingException

IOException

delete

public boolean delete(Email email)
               throws javax.mail.MessagingException

Throws:

javax.mail.MessagingException

delete

public boolean delete(javax.mail.Message msg)
               throws javax.mail.MessagingException

Throws:

javax.mail.MessagingException

delete

public boolean delete(String messageId)
               throws javax.mail.MessagingException

Throws:

javax.mail.MessagingException

getInbox

public javax.mail.Folder getInbox()
                           throws javax.mail.MessagingException

returns the POP3 inbox from the given mail settings. If the store is not already connected, it is after calling this method.

Throws:

javax.mail.MessagingException

fetchMessageIDs

public String[] fetchMessageIDs()
                         throws javax.mail.MessagingException

Throws:

javax.mail.MessagingException

receiveMessages

public javax.mail.Message[] receiveMessages()
                                     throws javax.mail.MessagingException

retrieves all messages from the INBOX but doesn't download the content. The method is not closing the store; this ought to be done through the Message.getFolder().close(boolean) method after processing the returned messages. If the number of returned messages is 0, the store is closed automatically.

Throws:

javax.mail.MessagingException

See Also:

getInbox()

iterator

public Iterator<javax.mail.Message> iterator()

note that if there were any messages, the folder is left open until you close it

Specified by:

iterator in interface Iterable<javax.mail.Message>

See Also:

getInbox()

emptyInbox

public int emptyInbox()
               throws javax.mail.MessagingException

returns the number of messages deleted from the POP3 inbox

Throws:

javax.mail.MessagingException

deleteFromInbox

public int deleteFromInbox(int maxMessagesToDelete)
                    throws javax.mail.MessagingException

returns the number of messages actually deleted from the POP3 inbox

Throws:

javax.mail.MessagingException

send

public void send(String to,
                 String subject,
                 String messageBody)
          throws javax.mail.MessagingException

sends out a simple text email message

Parameters:

to - may be a comma or semicolon separated list of addresses

Throws:

javax.mail.MessagingException

send

public void send(String to,
                 String subject,
                 String messageBody,
                 File attachment)
          throws javax.mail.MessagingException

sends an email with a file attachment.

Parameters:

to - may be a comma or semicolon separated list of addresses

Throws:

javax.mail.MessagingException

send

public void send(Email email)
          throws javax.mail.MessagingException

all settings (including from address) is taken from the given Email object

Throws:

javax.mail.MessagingException

send

public void send(javax.mail.Message msg)
          throws javax.mail.MessagingException

sends out the given message after it ran through the processor (if applicable). All settings (including from address) are taken from the given Message object. If the processor returns a null value, this particular message is ignored by the rest of this implementation.

Throws:

javax.mail.MessagingException

See Also:

getSendProcessor()

getSendProcessor

public Processor<javax.mail.Message,? extends Exception> getSendProcessor()

See Also:

setSendProcessor(Processor)

setSendProcessor

public void setSendProcessor(Processor<javax.mail.Message,? extends Exception> processor)

allows to set a processor that will handle messages before they get sent

See Also:

send(Message)

sendEmails

public void sendEmails(Email email,
                       javax.mail.internet.InternetAddress[] recipients)
                throws javax.mail.MessagingException

sends the email individually to each address.

Throws:

javax.mail.MessagingException

sendEmails

public void sendEmails(Email email,
                       javax.mail.internet.InternetAddress[] recipients,
                       EmailCustomizer replacerCallback,
                       Monitor monitor)
                throws javax.mail.MessagingException

sends the email individually to each address. The from-address is taken from the email object rather than from this object's setting - if it exists; otherwise it defaults to the from settings of the account. The monitor can be used to cancel the operation while going through the recipients. The monitor is incremented per sent email and its task is run.

Throws:

javax.mail.MessagingException

createMessage

public javax.mail.internet.MimeMessage createMessage(Email email)
                                              throws javax.mail.MessagingException

if no 'from' address is configured, the embedded 'from' address is used

Throws:

javax.mail.MessagingException

createTextMessage

public javax.mail.internet.MimeMessage createTextMessage(String subject,
                                                         String body)
                                                  throws javax.mail.MessagingException

from-address is taken from this object's configuration

Throws:

javax.mail.MessagingException

load

public javax.mail.internet.MimeMessage load(File emlFile)
                                     throws javax.mail.MessagingException,
                                            IOException

Throws:

javax.mail.MessagingException

IOException

load

public javax.mail.internet.MimeMessage load(InputStream in)
                                     throws javax.mail.MessagingException

Throws:

javax.mail.MessagingException

toString

public String toString()

Overrides:

toString in class Object

loopTest

public boolean loopTest()

calls loopTest(20, 2*60).

See Also:

loopTest(int, int)

loopTest

public boolean loopTest(int waitBetweenTriesInSeconds,
                        int timeOutInSeconds)

this method tests this email account fully regarding its send/receive functionality. The method sends an email to itself and will then try to receive and delete it. A call to this method may last up to the given timeOut value - until it times out. Thus, this method should potentially called not in the main execution thread. This method loggs all worthwhile information using the Logger of this object. Between each email retrieval attempt there is a delay of 20 seconds.

Parameters:

waitBetweenTriesInSeconds - number of seconds to wait before a retry

timeOutInSeconds - number of seconds after which the method will time out and not try anymore to receive the test message

Returns:

true only if the loopTest ends after a complete cycle of sending/receiving an email

loopTest

public boolean loopTest(POP3Account account)

calls loopTest(account, 30, 5*60).

See Also:

loopTest(POP3Account, int, int)

loopTest

public boolean loopTest(POP3Account account,
                        int waitBetweenTriesInSeconds,
                        int timeOutInSeconds)

this method tests this email account externally against the given account for its sending/receiving capabilities. An email will be sent from this account to the given account and vice versa. Next, the method tries to receive and delete both messages. A call to this method may last up to the given timeOut value - until it times out. Thus, this method should potentially called not in the main execution thread. This method loggs all worthwhile information using the Logger of this object.

Parameters:

waitBetweenTriesInSeconds - number of seconds to wait before a retry

timeOutInSeconds - number of seconds after which the method will time out and not try anymore to receive the test message

account - the account used to test this account against

Returns:

true only if the loopTest ends after a complete cycle of sending/receiving an email

abortActions

public void abortActions()

allows to cancel long-running operations, such as loopTest()

See Also:

resetAbortStatus(), loopTest()

resetAbortStatus

public void resetAbortStatus()

resets the abort status, so that operations can normally proceed

See Also:

abortActions()

setHeaders

public static void setHeaders(javax.mail.Message msg,
                              Email.Header[] header)
                       throws javax.mail.MessagingException

all headers keys and values must be String objects

Throws:

javax.mail.MessagingException

expungePop3Message

public static void expungePop3Message(javax.mail.Message msg)
                               throws javax.mail.MessagingException

the associated folder must subsequently be closed with the flag set to true to actually delete the message from the inbox.

Parameters:

msg - must be a com.sun.mail.pop.POP3Message object

Throws:

javax.mail.MessagingException

loadAddressesFromFile

public static javax.mail.internet.InternetAddress[] loadAddressesFromFile(File file)
                                                                   throws IOException,
                                                                          javax.mail.internet.AddressException

calls loadAddressesFromText(String)

Throws:

IOException

javax.mail.internet.AddressException

loadAddressesFromText

public static javax.mail.internet.InternetAddress[] loadAddressesFromText(String text)
                                                                   throws javax.mail.internet.AddressException

each address is assumed to be in an individual line. Lines beginning with a hash (#) sign are assumed to be comments. This reads an alternative format to the static methods from InternetAddress.

Throws:

javax.mail.internet.AddressException

extractEmail

public Email extractEmail(javax.mail.Message msg)
                   throws javax.mail.MessagingException,
                          IOException

Throws:

javax.mail.MessagingException

IOException

retrieveAccountsFromFile

public static POP3Account[] retrieveAccountsFromFile(File file)
                                              throws IOException,
                                                     ParseException,
                                                     javax.mail.NoSuchProviderException,
                                                     javax.mail.internet.AddressException

constructs EmailAccount objects from a file containing the necessary configuration data. Each line in the given file represents one EmailAccount object. Lines beginning with a hash ("#") are considered comment lines. Each line is to contain the following data fields in the given order in a comma separated list where each data field is enclosed with quotes (quotes are necessary as e.g. user and password may itself contain commas; problems may currently occur if e.g. the password contains a quote):

• pop3Server
• smtpServer
• user
• fromAddress
• authentication (boolean value: "true" or "false")

Throws:

IOException

ParseException

javax.mail.NoSuchProviderException

javax.mail.internet.AddressException

See Also:

saveAccountsToFile(POP3Account[], File)

saveAccountsToFile

public static void saveAccountsToFile(POP3Account[] accounts,
                                      File file)
                               throws IOException

Throws:

IOException

See Also:

retrieveAccountsFromFile(File)

getMXCount

public static int getMXCount(String hostName)
                      throws NamingException

looks up the 'MX'-record of the given hostName to see how many email servers are running (code taken from public domain)

Returns:

the number of email servers found for the given hostName

Throws:

NamingException