uk.co.weft.alert
Class Alert

java.lang.Object
  uk.co.weft.alert.Alert

public class Alert

extends java.lang.Object

An agent which can send a message to a user based on a template. This class (and consequently all classes which inherit from this class) knows about the following configuration parameters, which may be loaded from a file 'alert.properties' on the class path or passed into the constructor in a Map:

address_delimiter

String: the character or characters used to separate mail addresses in a list of mail addresses. Optional. Defaults to "|".

log_mail_sent

Boolean: if true, record all mail sent by printing to stdout. Optional. Defaults to false.

mail_bcc_address

String: email address to which a blind copy of each email should be sent. Optional. No default.

mail_cc_address

String: email address to which a carbon copy of each email should be sent. Optional. No default.

mail_character_set

String: the canonical name of the character set in which the sent mail should be encoded. Optional. Defaults to iso-8859-1

mail_from_address

String: the from address of the emails to be sent. Not optional. No default.

mail_host

String: the fully qualified domain name of the SMTP host through which to send mail. Optional. Defaults to localhost.

mail_subject

String: the subject of the email to be sent. Optional. Defaults to Alert!

mail_template_url

String: the URL or file path to a suitable template file. Not optional. No sensible default.

This class may be invoked as an application. In this configuration the class knows about the following command line switches:

-a address

Adds the email address address to the list of recipients. This switch may be repeated arbitrarily many times to send similar mail to many recipients.

-s keyvalue

Substitute value for all instances of the token key in the template, subject, or address list.

Any argument which is not protected by a -a or -s switch will be treated as the filename or URL of a template file. If a template file is specified on the command line that will over-ride that specified in the configuration. If more than one template file is specified on the command line they will be concatenated in the order specified.

It's desirable that in the future Alert should be able to distinguish between email addresses and other forms of contact address - perhaps including IM addresses and phone numbers, and direct messages via instant messaging or SMS where appropriate. The present incarnation, however, knows only about email.

Version:

$Revision: 1.17.4.5 $ This revision: $Author: simon $

Author:

Simon Brooke

Field Summary

protected java.lang.String	addressDelimiter the delimiter which may be used to separate mail addresses
static java.lang.String	ADDRESSDELIMITERTOKEN a token to identify the address delimiter in the configuration or alert context
static java.lang.String	BCCADDRESSTOKEN a token to identify any bcc address in the configuration context
static java.lang.String	CCADDRESSTOKEN a token to identify any cc address in the configuration context
protected java.lang.String	charset the character set in which to encode the mail
protected boolean	debug whether or not I'm in debug mode
static java.lang.String	DEBUGTOKEN a token to identify whether I'm in debug mode in the configuration context
static java.lang.String	FROMADDRESSTOKEN a token to identify the from address in the configuration context
protected boolean	logMail whether or not to log mail
static java.lang.String	LOGMAILTOKEN A token to identify whether to log mail as it is sent
protected InternetAddress	mailBCCAddress the BCC address for emails, if any
protected InternetAddress	mailCCAddress the BCC address for emails, if any
static java.lang.String	MAILCHARSETTOKEN a token to identify the character set for the mail which should be sent in the alert context
protected InternetAddress	mailFromAddress the from address for emails
protected java.lang.String	mailHost a host to send mail via
static java.lang.String	MAILHOSTTOKEN a token to identify the host via which mail should be sent in the alert context
protected Session	mailSession a mailer session
protected java.lang.String	mailSubject the default subject
static java.lang.String	MAILSUBJECTTOKEN a token to identify the subject for the mail which should be sent in the alert context
static java.lang.String	MAILTEMPLATETOKEN a token to identify the template for the mail which should be sent in the alert context
protected java.lang.String	mailTemplateURL the URL of the mail template file, if any
static java.lang.String	TOADDRESSTOKEN a token to identify the address to which the alert should be sent in the alert context

Constructor Summary

Alert()
create a new alert agent with configuration from the properties file

Alert(java.util.Map config)
create a new alert agent with this configuration

Method Summary

java.lang.Object	getResource(java.lang.String key) return the value of the resource with the given key as whatever sort of object it happens to be.
java.lang.String	getResourceString(java.lang.String key) return as a string the value of the resource with the given key.
java.lang.String	grs(java.lang.String key) shorthand for getResourceString; identical to it.
protected void	init(java.util.Map config) initialise me from this configuration
static void	main(java.lang.String[] args) Main: in case you want to use the alerter from the command line
boolean	sendAlert(InternetAddress toAddress, java.util.Map context) send an alert to this address, using my default template and subject, and substituting values in from this context.
boolean	sendAlert(InternetAddress toAddress, java.lang.String subject, java.util.Map context) send an alert to this address, using my default template and substituting values in from this context.
boolean	sendAlert(InternetAddress toAddress, java.lang.String subject, java.lang.String templateName, java.util.Map context) send an alert to this addresses, using the template specified by this string and substituting values in from this context.
boolean	sendAlert(SMSAddress toAddress, java.util.Map context) send an alert to this address, using my default template and subject, and substituting values in from this context.
boolean	sendAlert(SMSAddress toAddress, java.lang.String subject, java.util.Map context) send an alert to this address, using my default template and substituting values in from this context.
boolean	sendAlert(SMSAddress toAddress, java.lang.String subject, java.lang.String templateName, java.util.Map context) send an alert to this addresses, using the template specified by this string and substituting values in from this context.
boolean	sendAlert(java.lang.String toAddress, java.util.Map context) send an alert to this address, using my default template and subject, and substituting values in from this context.
boolean	sendAlert(java.lang.String toAddress, java.lang.String subject, java.util.Map context) send an alert to this address, using my default template and substituting values in from this context.
boolean	sendAlert(java.lang.String toAddress, java.lang.String subject, MessageBuffer template, java.util.Map context) send an alert to this address using this template and sustituting values in from this context.
boolean	sendAlert(java.lang.String toAddress, java.lang.String subject, java.lang.String templateName, java.util.Map context) send an alert to this addresses, using the template specified by this string and substituting values in from this context.
boolean	sendAlert(java.util.Vector toAddresses, java.util.Map context) send an alert to this address, using my default template and subject, and substituting values in from this context.
boolean	sendAlert(java.util.Vector toAddresses, java.lang.String subject, MessageBuffer template, java.util.Map context) send an identical alert to each of these addresses using this template and sustituting values in from this context.
boolean	sendAlert(java.util.Vector toAddresses, java.lang.String subject, java.lang.String templateName, java.util.Map context) send an an identical alert to each of these addresses, using the template specified by this string and substituting values in from this context.

Methods inherited from class java.lang.Object

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

Field Detail

FROMADDRESSTOKEN

public static final java.lang.String FROMADDRESSTOKEN

a token to identify the from address in the configuration context

See Also:

Constant Field Values

BCCADDRESSTOKEN

public static final java.lang.String BCCADDRESSTOKEN

a token to identify any bcc address in the configuration context

See Also:

Constant Field Values

CCADDRESSTOKEN

public static final java.lang.String CCADDRESSTOKEN

a token to identify any cc address in the configuration context

See Also:

Constant Field Values

MAILTEMPLATETOKEN

public static final java.lang.String MAILTEMPLATETOKEN

a token to identify the template for the mail which should be sent in the alert context

Since:

Jacquard 1.10.7

See Also:

Constant Field Values

MAILHOSTTOKEN

public static final java.lang.String MAILHOSTTOKEN

a token to identify the host via which mail should be sent in the alert context

Since:

Jacquard 1.10.7

See Also:

Constant Field Values

MAILSUBJECTTOKEN

public static final java.lang.String MAILSUBJECTTOKEN

a token to identify the subject for the mail which should be sent in the alert context

Since:

Jacquard 1.10.7

See Also:

Constant Field Values

MAILCHARSETTOKEN

public static final java.lang.String MAILCHARSETTOKEN

a token to identify the character set for the mail which should be sent in the alert context

Since:

Jacquard 1.10.8

See Also:

Constant Field Values

TOADDRESSTOKEN

public static final java.lang.String TOADDRESSTOKEN

a token to identify the address to which the alert should be sent in the alert context

See Also:

Constant Field Values

LOGMAILTOKEN

public static final java.lang.String LOGMAILTOKEN

A token to identify whether to log mail as it is sent

See Also:

Constant Field Values

DEBUGTOKEN

public static final java.lang.String DEBUGTOKEN

a token to identify whether I'm in debug mode in the configuration context

See Also:

Constant Field Values

ADDRESSDELIMITERTOKEN

public static final java.lang.String ADDRESSDELIMITERTOKEN

a token to identify the address delimiter in the configuration or alert context

See Also:

Constant Field Values

mailBCCAddress

protected InternetAddress mailBCCAddress

the BCC address for emails, if any

mailCCAddress

protected InternetAddress mailCCAddress

the BCC address for emails, if any

mailFromAddress

protected InternetAddress mailFromAddress

the from address for emails

mailSession

protected Session mailSession

a mailer session

addressDelimiter

protected java.lang.String addressDelimiter

the delimiter which may be used to separate mail addresses

charset

protected java.lang.String charset

the character set in which to encode the mail

mailHost

protected java.lang.String mailHost

a host to send mail via

mailSubject

protected java.lang.String mailSubject

the default subject

mailTemplateURL

protected java.lang.String mailTemplateURL

the URL of the mail template file, if any

debug

protected boolean debug

whether or not I'm in debug mode

logMail

protected boolean logMail

whether or not to log mail

Constructor Detail

Alert

public Alert(java.util.Map config)
      throws AlertingException

create a new alert agent with this configuration

Alert

public Alert()
      throws AlertingException

create a new alert agent with configuration from the properties file

Method Detail

main

public static void main(java.lang.String[] args)
                 throws java.lang.Exception

Main: in case you want to use the alerter from the command line

Throws:

java.lang.Exception

getResource

public java.lang.Object getResource(java.lang.String key)
                             throws java.util.MissingResourceException

return the value of the resource with the given key as whatever sort of object it happens to be. In the end if the resource cannot be found throw an exception.

Parameters:

key - the key to search for

Throws:

java.util.MissingResourceException - if the key cannot be found.

getResourceString

public java.lang.String getResourceString(java.lang.String key)

return as a string the value of the resource with the given key. If in the end the resource cannot be found just return the key.

Parameters:

key - the key to search for

grs

public java.lang.String grs(java.lang.String key)

shorthand for getResourceString; identical to it.

See Also:

getResourceString(String)

sendAlert

public boolean sendAlert(java.util.Vector toAddresses,
                         java.lang.String subject,
                         MessageBuffer template,
                         java.util.Map context)
                  throws AlertingException

send an identical alert to each of these addresses using this template and sustituting values in from this context. Note that if there is any difference between the messages you wish to send different users (for example, unsubscribe address) you should not use this method.

Parameters:

toAddresses - a vector of Strings, InternetAddresses or SMSAddresses. If strings each must be pareseable as a valid email address or SMS address

subject - the subject of the emails to send, or null to use the default. May incorporate substitutable tokens.

template - the template into which substitutions should be made.

context - a map containing substitutions to make into the template, such that the tokens to be substituted for are the keys and the values to be substituted in are the associated values

Returns:

true if the message was successfully despatched.

Throws:

AlertingException

sendAlert

public boolean sendAlert(java.lang.String toAddress,
                         java.lang.String subject,
                         MessageBuffer template,
                         java.util.Map context)
                  throws AlertingException

send an alert to this address using this template and sustituting values in from this context.

Parameters:

toAddress - a String which is a valid email or SMS address, or a sustitution token, or a delimiter separated list of such addresses and tokens

subject - the subject of the emails to send, or null to use the default. May incorporate substitutable tokens.

template - the template into which substitutions should be made

context - a map containing substitutions to make into the template, such that the tokens to be substituted for are the keys and the values to be substituted in are the associated values

Returns:

true if the message was successfully despatched.

Throws:

AlertingException

sendAlert

public boolean sendAlert(java.util.Vector toAddresses,
                         java.lang.String subject,
                         java.lang.String templateName,
                         java.util.Map context)
                  throws AlertingException

send an an identical alert to each of these addresses, using the template specified by this string and substituting values in from this context. Note that if there is any difference between the messages you wish to send different users (for example, unsubscribe address) you should not use this method.

Parameters:

toAddresses - a vector of Strings each of which is a valid email address

subject - the subject of the emails to send, or null to use the default. May incorporate substitutable tokens.

templateName - a URL or filename from which the template can be fetched

context - a map containing substitutions to make into the template, such that the tokens to be substituted for are the keys and the values to be substituted in are the associated values

Returns:

true if the message was successfully despatched.

Throws:

AlertingException

sendAlert

public boolean sendAlert(java.lang.String toAddress,
                         java.lang.String subject,
                         java.lang.String templateName,
                         java.util.Map context)
                  throws AlertingException

send an alert to this addresses, using the template specified by this string and substituting values in from this context.

Parameters:

toAddress - a String which is a valid email address

subject - the subject of the emails to send, or null to use the default. May incorporate substitutable tokens.

templateName - a URL or filename from which the template can be fetched, or null to use the default

context - a map containing substitutions to make into the template, such that the tokens to be substituted for are the keys and the values to be substituted in are the associated values

Returns:

true if the message was successfully despatched.

Throws:

AlertingException

sendAlert

public boolean sendAlert(InternetAddress toAddress,
                         java.lang.String subject,
                         java.lang.String templateName,
                         java.util.Map context)
                  throws AlertingException

send an alert to this addresses, using the template specified by this string and substituting values in from this context.

Parameters:

toAddress - an InternetAddress

subject - the subject of the emails to send, or null to use the default. May incorporate substitutable tokens.

templateName - a URL or filename from which the template can be fetched, or null to use the default

context - a map containing substitutions to make into the template, such that the tokens to be substituted for are the keys and the values to be substituted in are the associated values

Returns:

true if the message was successfully despatched.

Throws:

AlertingException

sendAlert

public boolean sendAlert(SMSAddress toAddress,
                         java.lang.String subject,
                         java.lang.String templateName,
                         java.util.Map context)
                  throws AlertingException

send an alert to this addresses, using the template specified by this string and substituting values in from this context.

Parameters:

toAddress - an SMSAddress

subject - the subject of the emails to send, or null to use the default. May incorporate substitutable tokens.

templateName - a URL or filename from which the template can be fetched, or null to use the default

context - a map containing substitutions to make into the template, such that the tokens to be substituted for are the keys and the values to be substituted in are the associated values

Returns:

true if the message was successfully despatched.

Throws:

AlertingException

sendAlert

public boolean sendAlert(java.lang.String toAddress,
                         java.lang.String subject,
                         java.util.Map context)
                  throws AlertingException

send an alert to this address, using my default template and substituting values in from this context.

Parameters:

toAddress - a String which is a valid email or SMS address, or a sustitution token, or a delimiter separated list of such addresses and tokens

subject - the subject of the emails to send, or null to use the default. May incorporate substitutable tokens.

context - a map containing substitutions to make into the template, such that the tokens to be substituted for are the keys and the values to be substituted in are the associated values

Returns:

true if the message was successfully despatched.

Throws:

AlertingException

sendAlert

public boolean sendAlert(InternetAddress toAddress,
                         java.lang.String subject,
                         java.util.Map context)
                  throws AlertingException

send an alert to this address, using my default template and substituting values in from this context.

Parameters:

toAddress - an InternetAddress

subject - the subject of the emails to send, or null to use the default. May incorporate substitutable tokens.

context - a map containing substitutions to make into the template, such that the tokens to be substituted for are the keys and the values to be substituted in are the associated values

Returns:

true if the message was successfully despatched.

Throws:

AlertingException

sendAlert

public boolean sendAlert(SMSAddress toAddress,
                         java.lang.String subject,
                         java.util.Map context)
                  throws AlertingException

send an alert to this address, using my default template and substituting values in from this context.

Parameters:

toAddress - an SMSAddress which is a valid email address

subject - the subject of the emails to send, or null to use the default. May incorporate substitutable tokens.

context - a map containing substitutions to make into the template, such that the tokens to be substituted for are the keys and the values to be substituted in are the associated values

Returns:

true if the message was successfully despatched.

Throws:

AlertingException

sendAlert

public boolean sendAlert(java.util.Vector toAddresses,
                         java.util.Map context)
                  throws AlertingException

send an alert to this address, using my default template and subject, and substituting values in from this context.

Parameters:

toAddresses - a Vector of usable addresses

context - a map containing substitutions to make into the template, such that the tokens to be substituted for are the keys and the values to be substituted in are the associated values

Returns:

true if the message was successfully despatched.

Throws:

AlertingException

sendAlert

public boolean sendAlert(java.lang.String toAddress,
                         java.util.Map context)
                  throws AlertingException

send an alert to this address, using my default template and subject, and substituting values in from this context.

Parameters:

toAddress - a String which is a valid email address or SMS address, or a sustitution token, or a delimiter separated list of such addresses and tokens

context - a map containing substitutions to make into the template, such that the tokens to be substituted for are the keys and the values to be substituted in are the associated values

Returns:

true if the message was successfully despatched.

Throws:

AlertingException

sendAlert

public boolean sendAlert(InternetAddress toAddress,
                         java.util.Map context)
                  throws AlertingException

send an alert to this address, using my default template and subject, and substituting values in from this context.

Parameters:

toAddress - an InternetAddress

context - a map containing substitutions to make into the template, such that the tokens to be substituted for are the keys and the values to be substituted in are the associated values

Returns:

true if the message was successfully despatched.

Throws:

AlertingException

sendAlert

public boolean sendAlert(SMSAddress toAddress,
                         java.util.Map context)
                  throws AlertingException

send an alert to this address, using my default template and subject, and substituting values in from this context.

Parameters:

toAddress - a SMSAddress

context - a map containing substitutions to make into the template, such that the tokens to be substituted for are the keys and the values to be substituted in are the associated values

Returns:

true if the message was successfully despatched.

Throws:

AlertingException

init

protected void init(java.util.Map config)
             throws AlertingException

initialise me from this configuration

Throws:

AlertingException