Holger's Java API

## 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`

(c) Holger Antelmann since 2001- all rights reserved (contact: info@antelmann.com)
see www.antelmann.com/developer for further details and available downloads