com.opmath.mail
Class MailClient

java.lang.Object
  |
  +--java.lang.Thread
        |
        +--com.opmath.mail.MailClient

All Implemented Interfaces:

Runnable

public class MailClient

extends Thread

An email client accessible to any Java application.

The com.opmath.mail.MailClient class provides a simple email client. The client can send email using any named SMPT mail host. Because sending an email message is a time-consuming process, the email client allows for queuing of messages in an 'outbasket'. A queued message is sent as soon as the sender thread is able to do so - at any one time, the sender thread is either sending a message, or waiting for a message to be placed in the outbasket.

The client can be constructed with or without a debug mode - if the debug mode is on, the SMTP transcript is written to the console. (In the current version, you have to recompile to change the debug mode.) The client always logs queue and send activity to the give PrintStream log.

NOTE 1: There is a significant possibility that the sender thread will fail - the most common reason reason for this is that the connection to the SMTP server is lost, or the SMTP server ceases to respond. In such a case, it is difficult to recover the items in the outbasket queue. Thus, any application using com.opmath.mail.MailClient should keep the transaction log.

NOTE 2: This version of com.opmath.mail.MailClient does not support the receiving of IMAP or POP3 mail. Future versions might.

NOTE 3: The com.opmath.mail package requires at least JavaMail 1.1.3 and the Java Activation Framework (JAF) 1.0.1.

Copyright: (c) 2002 The Open Math Company Limited

The Terms of Distribution of this software are stipulated in the javadoc Overview for this project.

Since:

J2SE 1.3

Version:

1.0

Author:

Bruno Beloff bruno.beloff@opmath.com

Fields inherited from class java.lang.Thread

inheritableThreadLocals, MAX_PRIORITY, MIN_PRIORITY, NORM_PRIORITY, threadLocals

Constructor Summary

MailClient(String from, String fromName, PrintStream log)
Constructs an MailClient instance with a given client 'identity'.

MailClient(String from, String fromName, String filePath, PrintStream log)
Constructs an MailClient instance with a given client 'identity'.

Method Summary

boolean	nothingToSend() Returns the current state of the outbasket and sender thread.
MailMessage	queue(String subject, String to, String cc, String bcc, String text) Places an email message in the outbasket queue.
MailMessage	queue(String subject, String to, String cc, String bcc, String text, String fileName, String mimeType) Places an email message in the outbasket queue.
void	run() The run method for the sender thread.
protected void	send() Sends the email message at the front of the outbasket queue.
static void	setServer(String server) Sets the name of the SMTP server to server.
protected void	setSession() Constructs the session for this email client, on the basis of the arguments given to the constructor.
boolean	shutdown(int waitPeriod) Tells this email client's sender thread to shut down.
String	toString() Returns a String describing the queue.

Methods inherited from class java.lang.Thread

, activeCount, checkAccess, countStackFrames, currentThread, destroy, dumpStack, enumerate, getContextClassLoader, getName, getPriority, getThreadGroup, interrupt, interrupted, isAlive, isDaemon, isInterrupted, join, join, join, resume, setContextClassLoader, setDaemon, setName, setPriority, sleep, sleep, start, stop, stop, suspend, yield

Methods inherited from class java.lang.Object

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

Constructor Detail

MailClient

public MailClient(String from,
                  String fromName,
                  PrintStream log)
           throws IOException

Constructs an MailClient instance with a given client 'identity'. The identity is in the form of a 'From:' email address and 'From:' personal name. The local file path for attachments is set as the local directory, and the debug mode is set to off.

The final task for the constructor is to start the email sender thread. Thus, the email client starts running automatically as soon as it is constructed.

If the server name has not been set, the constructor will throw an IOException.

Parameters:

from - the String carrying the 'From:' address.

fromName - the String carrying the 'From:' personal name.

log - the PrintStream for the activity log.

Throws:

java.util.IOException - An exception thrown if the class has no server name.

Since:

JDK 1.2.2

See Also:

setServer(String)

MailClient

public MailClient(String from,
                  String fromName,
                  String filePath,
                  PrintStream log)
           throws IOException

Constructs an MailClient instance with a given client 'identity'. The identity is in the form of a 'From:' email address and 'From:' personal name. The local file path for attachments is set according to the parameter filePath. The debug mode is set to off.

The final task for the constructor is to start the email sender thread. Thus, the email client starts running automatically as soon as it is constructed.

If the server name has not been set, the constructor will throw an IOException.

Parameters:

from - the String carrying the 'From:' address.

fromName - the String carrying the 'From:' personal name.

fromName - the String carrying the file path (with trailing '/').

log - the PrintStream for the activity log.

Throws:

java.util.IOException - An exception thrown if the class has no server name.

Since:

JDK 1.2.2

See Also:

setServer(String)

Method Detail

setServer

public static void setServer(String server)

Sets the name of the SMTP server to server. This will be the SMTP server for all MailClient instances.

NOTE: The server name can only be set once. Subsequent attempts to set the server name are ignored.

Parameters:

server - the String identifying the server.

Since:

JDK 1.2.2

setSession

protected void setSession()
                   throws IOException

Constructs the session for this email client, on the basis of the arguments given to the constructor. Only called by the constructors.

Throws:

java.util.IOException - An exception thrown if the session could not be constructed.

Since:

JDK 1.2.2

run

public void run()

The run method for the sender thread. The sender thread continues to run, until both the shutdown flag is raised, and the outbasket is empty.

Overrides:

run in class Thread

Since:

JDK 1.2.2

queue

public MailMessage queue(String subject,
                         String to,
                         String cc,
                         String bcc,
                         String text,
                         String fileName,
                         String mimeType)
                  throws MessagingException

Places an email message in the outbasket queue. The message carries an attachment, which is a file. The MIME type of this file attachment must be specified. The message will me sent automatically, at some time in the future.

There are only three obligatory parameters for this queue(..) method:

• to - There must always be at least one 'To:' address for the message.
• fileName - The file to be attached to the email message.
• mimeType - The MIME type of the attached file.

Where a paremeter value is not required, it may be given as null.

If the outbasket queue is full, queue(..) will throw a MessagingException. The outbasket can hold up to 100 queued messages.

Parameters:

subject - a String subject text, or null.

to - a String list of email addresses.

cc - a String list of email addresses, or null.

bcc - a String list of email addresses, or null.

text - a String ascii plain text message, or null.

fileName - a String name for one attachment file.

mimeType - a String MIME type identifier, for the attachment.

Returns:

the MailMessage constructed as part of the queueing operation.

Throws:

MessagingException - An exception thrown if the parameters were malformed, the attachment file could not be accessed, or the queue was full.

Since:

JDK 1.2.2

See Also:

setServer(String)

queue

public MailMessage queue(String subject,
                         String to,
                         String cc,
                         String bcc,
                         String text)
                  throws MessagingException

Places an email message in the outbasket queue. The message will me sent automatically, at some time in the future.

There is only one obligatory parameter for this queue(..) method:

• to - There must always be at least one 'To:' address for the message.

Where a paremeter value is not required, it may be given as null.

If the outbasket queue is full, queue(..) will throw a MessagingException. The outbasket can hold up to 100 queued messages.

Parameters:

subject - a String subject text, or null.

to - a String list of email addresses.

cc - a String list of email addresses, or null.

bcc - a String list of email addresses, or null.

text - a String ascii plain text message, or null.

Returns:

the MailMessage constructed as part of the queueing operation.

Throws:

MessagingException - An exception thrown if the parameters were malformed, or the queue was full.

Since:

JDK 1.2.2

See Also:

setServer(String)

shutdown

public boolean shutdown(int waitPeriod)

Tells this email client's sender thread to shut down.

Once in shutdown state, this email client will not accept any more messages to enqueue. During this time, shutdown() inspects the outbasket, to see if it is empty. If it is not empty, then shutdown() continues to inspect the queue once every second, until either the queue is empty, or the given 'wait period' has expired.

NOTE: shutdown() does not act on the sender thread, it simply reports on sender thread activity. Thus, if shutdown() returns true, then the sender thread is exiting, or has exited. If shutdown() returns false, then the sender thread is still running.

Parameters:

waitPeriod - the int time in seconds to wait for the outbasket to become empty.

Returns:

a boolean indicating whether the sender thread is exiting.

Since:

JDK 1.2.2

See Also:

nothingToSend()

nothingToSend

public boolean nothingToSend()

Returns the current state of the outbasket and sender thread.

nothingToSend() returns true only if the outbasket is empty and the sender thread is idle.

Returns:

a boolean reporting the state of the email client.

Since:

JDK 1.2.2

send

protected void send()

Sends the email message at the front of the outbasket queue. If there are no messages in the outbasket queue, send() will wait.

send() always reports to log.

WARNING: The send() method could take for ever to complete. It should always be executed by a dedicated thread.

Since:

JDK 1.2.2

See Also:

setServer(String)

toString

public String toString()

Returns a String describing the queue.

Overrides:

toString in class Thread

Returns:

a String reporting the state of the queue.

Since:

JDK 1.2.2