com.ccg.net.email
Class Mailer

java.lang.Object
  com.ccg.net.email.Mailer

public class Mailer
extends Object

Class to help in the creation and sending of email messages (uses Java Mail API). Many options are set via a lookup table, the following properties are recognized:

mail.smtp.host=IP

Hostname (or numeric IP) to use as SMTP transport.

mail.smtp.port=PORT

Reserved for future use.

mail.smtp.user=TEXT

User ID (set if SMTP requires authentication).

mail.smtp.password=TEXT

Password (set if SMTP requires authentication).

mail.smtp.

from.address=USER@DOMAIN

Email address for "From:" (RFC 821).

from.name=TEXT

Name associated with "From:" address.

replyto.address=USER@DOMAIN

Email address for "Replyto:" (RFC 822).

replyto.name=TEXT

Name associated with "Replyto:" address.

dest.N.address=USER@DOMAIN

Email destination address (N starts a 0 and keeps incrementing for each address to distribute to) (RFC 822).

dest.N.name=TEXT

Name associated with dest.N.address

dest.N.type=to|cc|bcc

Sets recipient type for dest.N.address default is "to" if omitted.

Some of the following will/may need to be implemented in the future (Ron pointed these functions as being available in the Windows Blat utility and standard RFC protocols):

organization: Organization field
X-Header: Custom 'X-' header (general text)
Request return receipt.
Request disposition notification.
prevent X-Mailer header entirely

mailfrom    The RFC 821 MAIL From: statement
returnpath  The RFC 822 Return-Path: statement
sender      The RFC 822 Sender: statement

Since:

1.0

Version:

$Revision: 1.2 $

Author:

$Author: pkb $ #see [class][#method]|Text

Constructor Summary

Mailer()
Initializes object to...

Method Summary

void	addAttachment(String src) Add a attachment to the outbound mail.
javax.mail.Message	buildMessage() Construct and send email message based on contents of bean.
javax.mail.Transport	connectToSmtpHost() One line summary...
javax.mail.internet.MimeMessage	createMessage() Creates a new message to be sent.
javax.mail.Authenticator	getAuthenticator() Get the Authenticator used to prompt user for mail transport login ID/password (when required).
String	getBodyText() Get the text to appear in the main part of the body of the message.
DistributionList	getDistributionList() Get the distribution list used when creating messages.
javax.mail.Address	getFromAddress() Get the "from" address to be associated with each new message created.
AtMacros	getInterpreter() Get the macro interpreter used to process text strings and files.
MimeTypes	getMimeTypes() Get the MimeTypes used to map file name extensions to their corresponding MIME type.
javax.mail.Address	getReplyToAddress() Get the "reply-to" address to be associated with each new message created.
javax.mail.Session	getSession() Get the Session object used to connect to the mail transports.
String	getSmtpHost() Get the SMTP host to connect to.
String	getSmtpPassword() Get the SMTP user's password (if necessary).
String	getSmtpUser() Get the SMTP user login (not normally necessary).
String	getSubject() Get the subject to use in the outbound mail.
String	interpret(InputStream src) Creates a new message to be sent.
boolean	isDebugEnabled() Should debug output be generated from the Java Mail API code?
void	sendMessage(javax.mail.Message m) One line summary...
void	setAuthenticator(javax.mail.Authenticator val) Set the Authenticator used to prompt user for mail transport login ID/password (when required).
void	setBodyFrom(InputStream is, MimeType mt) Set the body of the text by doing a macro interpretation of a input stream.
void	setBodyText(String val, MimeType mt) Set the text to appear in the main part of the body of the message.
void	setDebugEnabled(boolean val) Set whether debug output be generated from the Java Mail API code?
void	setFromAddress(javax.mail.Address val) Set the "from" address to be associated with each new message created.
void	setFromConfig(String cfgName) One line summary...
void	setFromLookup(Lookup l) One line summary...
void	setInterpreter(AtMacros val) Set the macro interpreter used to process text strings and files.
void	setMimeTypes(MimeTypes val) Set the MimeTypes used to map file name extensions to their corresponding MIME type.
void	setReplyToAddress(javax.mail.Address val) Set the "reply-to" address to be associated with each new message created.
void	setSession(javax.mail.Session val) Set the Session object used to connect to the mail transports.
void	setSmtpHost(String val) Set the SMTP host to connect to.
void	setSmtpPassword(String val) Set the SMTP user's password (if necessary).
void	setSmtpUser(String val) Set the SMTP user login (not normally necessary).
void	setSubject(String val) Set the subject to use in the outbound mail.
String	toString() One line summary...

Methods inherited from class java.lang.Object

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

Constructor Detail

Mailer

public Mailer()

Initializes object to... It performs the following tasks:

• Initializes

Since:

1.0 #see [class][#meth]|Text

Method Detail

setFromConfig

public void setFromConfig(String cfgName)
                   throws IOException,
                          ConfigException

One line summary... Describe...

Parameters:

arg1 - arg1-describe

arg2 - arg2-describe

Throws:

exc - Why thrown

IOException

ConfigException

Since:

1.0 #see [class][#meth]|Text

setFromLookup

public void setFromLookup(Lookup l)

One line summary... Describe...

Parameters:

arg1 - arg1-describe

arg2 - arg2-describe

Throws:

exc - Why thrown

Since:

1.0 #see [class][#meth]|Text

setSession

public void setSession(javax.mail.Session val)

Set the Session object used to connect to the mail transports.

Parameters:

val - New Session value to assign.

See Also:

getSession()

getSession

public javax.mail.Session getSession()

Get the Session object used to connect to the mail transports.

Returns:

Current Session value assigned - if one has never been assigned, a new instance will be created (and we'll initialize the properties with the property file $HOME/.etc/com/ccg/net/email/default.Mailer.

See Also:

setSession(javax.mail.Session)

setAuthenticator

public void setAuthenticator(javax.mail.Authenticator val)

Set the Authenticator used to prompt user for mail transport login ID/password (when required).

Parameters:

val - New Authenticator value to assign.

See Also:

getAuthenticator()

getAuthenticator

public javax.mail.Authenticator getAuthenticator()

Get the Authenticator used to prompt user for mail transport login ID/password (when required).

Returns:

Current Authenticator value assigned - if one has never been assigned, a default Swing implementation will be used.

See Also:

setAuthenticator(javax.mail.Authenticator)

setDebugEnabled

public void setDebugEnabled(boolean val)

Set whether debug output be generated from the Java Mail API code?

Parameters:

val - New boolean value to assign.

See Also:

isDebugEnabled()

isDebugEnabled

public boolean isDebugEnabled()

Should debug output be generated from the Java Mail API code?

Returns:

Current boolean value assigned.

See Also:

setDebugEnabled(boolean)

createMessage

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

Creates a new message to be sent.

This method will create a new message and initializes with the following information:

• The "from" address (if available).
• The "to" address (if available).
• The "destination" address(es) (if available).

After invoking this method, you typically only need to set the subject and message content for the message. Here is a quick example:

 static void foo(Mailer mailer, String sub, String body) {
    try {
      Message m = mailer.createMessage();
      m.setSubject(sub);
      m.setContent(body,"text/plain");
      mailer.send(m);
    } catch (Exception e) {
      e.printStackTrace();
    }
 }
 

Returns:

New message object.

Throws:

javax.mail.MessagingException - If there is a problem creating a message for the current Session (probably due to lack of being properly configured), or one of the addresses we tried to set was not in a valid form.

Since:

1.0

interpret

public String interpret(InputStream src)
                 throws IOException,
                        InterpretException

Creates a new message to be sent.

This method will create a new message and initializes with the following information:

• The "from" address (if available).
• The "to" address (if available).
• The "destination" address(es) (if available).
• It sets the subject line (if
• It then loads the contents of the message

After invoking this method, you typically only need to set the subject and message content for the message. Here is a quick example:

 static void foo(Mailer mailer, String sub) {
    try {
      Message m = mailer.createMessage();
      m.setSubject(sub);
      m.setContent(mailer.interpret(System.in),"text/plain");
      mailer.send(m);
    } catch (Exception e) {
      e.printStackTrace();
    }
 }
 

Returns:

String value of the interpretted information.

Throws:

IOException - If there is a problem reading information from the source input stream.

InterpretException - If there is a problem interpretting the contents read.

Since:

1.0

setInterpreter

public void setInterpreter(AtMacros val)

Set the macro interpreter used to process text strings and files.

Parameters:

val - New AtMacros value to assign.

See Also:

getInterpreter()

getInterpreter

public AtMacros getInterpreter()

Get the macro interpreter used to process text strings and files.

Returns:

Current AtMacros interpreter being used to process text - if never set/or reset to null a new one will be created.

See Also:

setInterpreter(com.ccg.macros.AtMacros)

sendMessage

public void sendMessage(javax.mail.Message m)
                 throws javax.mail.internet.AddressException,
                        javax.mail.MessagingException,
                        UnsupportedEncodingException

One line summary... Describe...

Parameters:

arg1 - arg1-describe

arg2 - arg2-describe

Throws:

exc - Why thrown

javax.mail.internet.AddressException

javax.mail.MessagingException

UnsupportedEncodingException

Since:

1.0 #see [class][#meth]|Text

buildMessage

public javax.mail.Message buildMessage()
                                throws javax.mail.MessagingException,
                                       UnsupportedEncodingException

Construct and send email message based on contents of bean.

Throws:

IllegalStateException - If the bean has not be properly initialized (not enough information to generate a message).

javax.mail.MessagingException

UnsupportedEncodingException

Since:

1.0

connectToSmtpHost

public javax.mail.Transport connectToSmtpHost()
                                       throws javax.mail.NoSuchProviderException,
                                              javax.mail.MessagingException

One line summary... Describe...

Parameters:

arg1 - arg1-describe

arg2 - arg2-describe

Returns:

ret-description

Throws:

exc - Why thrown

javax.mail.NoSuchProviderException

javax.mail.MessagingException

Since:

1.0

toString

public String toString()

One line summary... Describe...

Overrides:

toString in class Object

Parameters:

arg1 - arg1-describe

arg2 - arg2-describe

Returns:

ret-description

Throws:

exc - Why thrown

Since:

1.0 #see [class][#meth]|Text

getDistributionList

public DistributionList getDistributionList()

Get the distribution list used when creating messages.

Whenever you create a new message, the recipients are set to all of the entries in this distribution list. You can add/remove items from it as needed.

Returns:

Current DistributionList value assigned - never returns null, but might return a distribution list with no entries.

setFromAddress

public void setFromAddress(javax.mail.Address val)

Set the "from" address to be associated with each new message created.

Initially this value is 'null' (and you may set it to null), indicating that the "from" address should not be set by this class.

Parameters:

val - New Address value to assign.

See Also:

getFromAddress()

getFromAddress

public javax.mail.Address getFromAddress()

Get the "from" address to be associated with each new message created.

Returns:

Current Address value assigned, or null if no from address is yet associated.

See Also:

setFromAddress(javax.mail.Address)

setReplyToAddress

public void setReplyToAddress(javax.mail.Address val)

Set the "reply-to" address to be associated with each new message created.

Initially this value is 'null' (and you may set it to null), indicating that the "reply-to" address should not be set by this class.

Parameters:

val - New Address value to assign.

See Also:

getReplyToAddress()

getReplyToAddress

public javax.mail.Address getReplyToAddress()

Get the "reply-to" address to be associated with each new message created.

Returns:

Current Address value assigned, or null if no reply-to address is yet associated.

See Also:

setReplyToAddress(javax.mail.Address)

setSmtpHost

public void setSmtpHost(String val)

Set the SMTP host to connect to.

Parameters:

val - New String value to assign.

See Also:

getSmtpHost()

getSmtpHost

public String getSmtpHost()

Get the SMTP host to connect to.

Returns:

Current String value assigned, or null if the SMTP host has never been set.

See Also:

setSmtpHost(java.lang.String)

setSmtpUser

public void setSmtpUser(String val)

Set the SMTP user login (not normally necessary).

Parameters:

val - New String value to assign.

See Also:

getSmtpUser()

getSmtpUser

public String getSmtpUser()

Get the SMTP user login (not normally necessary).

Returns:

Current String value assigned, or null if never set.

See Also:

setSmtpUser(java.lang.String)

setSmtpPassword

public void setSmtpPassword(String val)

Set the SMTP user's password (if necessary).

Parameters:

val - New String value to assign.

See Also:

getSmtpPassword()

getSmtpPassword

public String getSmtpPassword()

Get the SMTP user's password (if necessary).

Returns:

Current String value assigned - or null if never set.

See Also:

setSmtpPassword(java.lang.String)

setMimeTypes

public void setMimeTypes(MimeTypes val)

Set the MimeTypes used to map file name extensions to their corresponding MIME type.

Parameters:

val - New MimeTypes value to assign.

See Also:

getMimeTypes()

getMimeTypes

public MimeTypes getMimeTypes()

Get the MimeTypes used to map file name extensions to their corresponding MIME type.

Returns:

Current MimeTypes value assigned - never returns null (creates new one if not yet specified).

See Also:

setMimeTypes(com.ccg.net.MimeTypes)

setSubject

public void setSubject(String val)

Set the subject to use in the outbound mail.

Parameters:

val - New String value to assign.

See Also:

getSubject()

getSubject

public String getSubject()

Get the subject to use in the outbound mail.

Returns:

Current String value assigned.

See Also:

setSubject(java.lang.String)

setBodyText

public void setBodyText(String val,
                        MimeType mt)

Set the text to appear in the main part of the body of the message.

Parameters:

val - New text value to assign (or null to clear).

mt - MimeType for text (or null if you want me to guess).

See Also:

getBodyText()

getBodyText

public String getBodyText()

Get the text to appear in the main part of the body of the message.

Returns:

Current String value assigned.

See Also:

setBodyText(java.lang.String, com.ccg.net.MimeType)

setBodyFrom

public void setBodyFrom(InputStream is,
                        MimeType mt)
                 throws IOException,
                        InterpretException

Set the body of the text by doing a macro interpretation of a input stream.

This method uses the interpret method to macro process the input stream passed and sets the body of the message to the resulting string.

Parameters:

is - The InputStream to read from - must not be null.

mt - The MIME type associate with the stream (can be null if you want us to guess).

Throws:

IOException - If there is a problem reading information from the source input stream.

InterpretException - If there is a problem interpretting the contents read.

Since:

1.0

addAttachment

public void addAttachment(String src)

Add a attachment to the outbound mail.

Parameters:

src - Name of the source input to attach (can be a file name or URL).

Since:

1.0