com.antelmann.net.mail
Class EmailAccount

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

All Implemented Interfaces:

Licensed

public class EmailAccount
extends Object
implements Licensed

EmailAccount provides an easy way to send and receive emails 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 the javax.mail API or J2EE

Since:

12/30/2003

Author:

Holger Antelmann

See Also:

JNewsletterManager, JEmailClient, EmailAccountTableModel

Constructor Summary

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

EmailAccount(File configFile)

EmailAccount(Properties props)

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

EmailAccount(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
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.
static Email	extractEmail(javax.mail.Message msg)
boolean	getAccessInboxBeforeSend() false by default
boolean	getAuthentication()
boolean	getDebug()
String	getFrom()
javax.mail.Folder	getInbox() returns the POP3 inbox from the given mail settings.
Logger	getLogger()
String	getPassword()
String	getPop3Server()
String	getSmtpPassword()
String	getSmtpServer()
String	getUser()
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(EmailAccount account) calls loopTest(account, 30, 5*60).
boolean	loopTest(EmailAccount account, int waitBetweenTriesInSeconds, int timeOutInSeconds) this method tests this email account externally against the given account for its sending/receiving capabilities.
boolean	loopTest(int waitBetweenTriesInSeconds, int timeOutInSeconds) this method tests this email account fully regarding its send/receive functionality.
Email[]	receiveEmails() fully downloads all messages from the inbox into Email objects (the messages remain on the server)
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 EmailAccount[]	retrieveAccountsFromFile(File file) constructs EmailAccount objects from a file containing the necessary configuration data.
static void	saveAccountsToFile(EmailAccount[] 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) all settings (including from address) is taken from the given Message object
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	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	setLogger(Logger logger)
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	setSession() recreates the embedded session and accounts for possibly changed System settings
void	setSmtpPassword(String smtpPassword) must only be set explicitly if different from the POP3 password
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

EmailAccount

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

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

Throws:

javax.mail.NoSuchProviderException

javax.mail.internet.AddressException

EmailAccount

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

Throws:

IOException

javax.mail.NoSuchProviderException

javax.mail.internet.AddressException

EmailAccount

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

Throws:

javax.mail.NoSuchProviderException

javax.mail.internet.AddressException

EmailAccount

public EmailAccount(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

EmailAccount

public EmailAccount(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

Method Detail

setSession

public void setSession()
                throws javax.mail.NoSuchProviderException

recreates the embedded session and accounts for possibly changed System settings

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

getLogger

public Logger getLogger()

setLogger

public void setLogger(Logger logger)

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()
                      throws javax.mail.MessagingException,
                             IOException

fully downloads all messages from the inbox into Email objects (the messages remain on the server)

Throws:

javax.mail.MessagingException

IOException

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

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(boolean) method after processing the returned messages. If the number of returned messages is 0, the store is closed automatically.

Throws:

javax.mail.MessagingException

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

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

Throws:

javax.mail.MessagingException

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

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

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

See Also:

loopTest(EmailAccount, int, int)

loopTest

public boolean loopTest(EmailAccount 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 static Email extractEmail(javax.mail.Message msg)
                          throws javax.mail.MessagingException,
                                 IOException

Throws:

javax.mail.MessagingException

IOException

retrieveAccountsFromFile

public static EmailAccount[] 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:

(EmaliAccount[], File)

saveAccountsToFile

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

Throws:

IOException

See Also:

retrieveAccountsFromFile(File)