to.etc.webapp.mailer

Class MailHelper

java.lang.Object

to.etc.webapp.mailer.MailHelper

public class MailHelper
extends Object

This is a simple mail builder class to help with writing nice emails in both HTML and text format. It has methods to handle simple HTML markup and has the ability to add embedded images as attachments.

Author:

Frits Jalvingh Created on May 7, 2012

Constructor Summary

Constructors

Constructor and Description
MailHelper()

Method Summary

Modifier and Type	Method and Description
protected void	addGreeting() Can be overridden to add a custom greeting.
String	addImage(String name, String rurl) Add a web resource as an image, and return the image's internal ID.
MailHelper	addTo(Address a)
MailHelper	addTo(String email)
protected void	addTrailer() Can be overridden to add a default trailer.
MailHelper	append(String s) Just add verbatim text, without anything else.
void	appendVerbatim(String s) Append the text without scanning for any kind of embedded links.
MailHelper	b(String s)
protected InputStream	getApplicationResource(String name)
String	getApplicationURL()
List<to.etc.webapp.mailer.MailHelper.Attachment>	getAttachmentList()
StringBuilder	getHtmlBuffer()
String	getSubject()
StringBuilder	getTextBuffer()
List<Address>	getTo()
void	htmlEndTag(String tag)
void	htmlTag(String tag, String... attrs) Render a html tag with optional attr=value pairs.
void	htmlText(String text) Split text into whitespace-separated things, and make sure lines are smaller than MAXLINE.
MailHelper	i(String s)
MailHelper	image(to.etc.webapp.mailer.MailHelper.Attachment a, String name) Add an image link for a specified attachment.
MailHelper	image(String name, Class<?> resourceClass, String resourceName) Add a class resource as an image.
MailHelper	image(String name, String rurl) Add a web resource as an image.
MailHelper	image(String name, String mime, File source) Append an image as an attachment, and embed the image in the HTML stream.
MailHelper	image(String name, String mime, String rurl) Add a web resource as an image.
MailHelper	link(String text, IIdentifyable<?> inst) Use the LinkedText mechanism to render a link to some entity.
MailHelper	link(String url, String text) Render a link in HTML, embedding "text" in the link.
MailHelper	linkNoText(String url, String text) Create a link in html only.
MailHelper	nl()
MailHelper	pre(String content)
void	send() Send the message using the BulkMailer's default instance, using a newly allocated connection.
void	send(QDataContext dc) Send the message using the BulkMailer using the specified connection.
void	send(SmtpTransport transport) Send the message immediately through the specified transport - only use this if the BulkMailer should not be used.
void	sendInternal(Object through) Queue the message for transmission.
void	setApplicationURL(String applicationURL) Set the root application URL.
MailHelper	setFrom(Address from)
MailHelper	setFrom(String from)
void	setLinkRenderer(ITextLinkRenderer linkRenderer)
void	setRoot(File root)
MailHelper	setSubject(String subject)
void	start(Address to, String subject)
MailHelper	ttl(String s)

Methods inherited from class java.lang.Object

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

Constructor Detail

MailHelper

public MailHelper()

Method Detail

setRoot

public void setRoot(File root)

start

public void start(Address to,
                  String subject)

htmlTag

public void htmlTag(String tag,
                    String... attrs)

Render a html tag with optional attr=value pairs.

Parameters:

tag -

attrs -

htmlEndTag

public void htmlEndTag(String tag)

htmlText

public void htmlText(String text)

Split text into whitespace-separated things, and make sure lines are smaller than MAXLINE.

Parameters:

text -

append

@Nonnull
public MailHelper append(@Nonnull
                                  String s)

Just add verbatim text, without anything else. Quotes all html content. This will decode text generated with LinkedText into something that might be edible by email.

Parameters:

s -

Returns:

appendVerbatim

public void appendVerbatim(@Nonnull
                           String s)

Append the text without scanning for any kind of embedded links.

Parameters:

s -

ttl

@Nonnull
public MailHelper ttl(@Nonnull
                               String s)

i

@Nonnull
public MailHelper i(String s)

b

@Nonnull
public MailHelper b(String s)

nl

@Nonnull
public MailHelper nl()

pre

@Nonnull
public MailHelper pre(String content)

link

@Nonnull
public MailHelper link(@Nonnull
                                String url,
                                @Nonnull
                                String text)

Render a link in HTML, embedding "text" in the link. The text message will show

 text (link)
 

Parameters:

url - The full URL to link to.

text - The link's text.

Returns:

link

@Nonnull
public MailHelper link(@Nonnull
                                String text,
                                @Nonnull
                                IIdentifyable<?> inst)

Use the LinkedText mechanism to render a link to some entity. There must be some TextLinkInfo registered for the class.

Parameters:

text -

inst -

Returns:

linkNoText

@Nonnull
public MailHelper linkNoText(String url,
                                      String text)

Create a link in html only.

Parameters:

url -

text -

Returns:

image

@Nonnull
public MailHelper image(String name,
                                 String mime,
                                 File source)
                          throws Exception

Append an image as an attachment, and embed the image in the HTML stream. The text stream just contains a reference like (see image xxx). The image must be a supported mime type.

Parameters:

name -

source -

Returns:

Throws:

Exception

image

@Nonnull
public MailHelper image(String name,
                                 Class<?> resourceClass,
                                 String resourceName)
                          throws Exception

Add a class resource as an image.

Parameters:

name -

resourceClass -

resourceName -

Returns:

Throws:

Exception

image

@Nonnull
public MailHelper image(@Nonnull
                                 String name,
                                 @Nonnull
                                 String mime,
                                 @Nonnull
                                 String rurl)
                          throws Exception

Add a web resource as an image. For this to work you must override getApplicationResource(String).

Parameters:

name -

mime -

rurl -

Returns:

Throws:

Exception

image

@Nonnull
public MailHelper image(@Nonnull
                                 String name,
                                 @Nonnull
                                 String rurl)
                          throws Exception

Add a web resource as an image. For this to work you must override getApplicationResource(String).

Parameters:

name -

rurl -

Returns:

Throws:

Exception

addImage

@Nonnull
public String addImage(@Nonnull
                                String name,
                                @Nonnull
                                String rurl)
                         throws Exception

Add a web resource as an image, and return the image's internal ID. For this to work you must override getApplicationResource(String).

Parameters:

name -

rurl -

Returns:

Throws:

Exception

image

public MailHelper image(@Nonnull
                        to.etc.webapp.mailer.MailHelper.Attachment a,
                        @Nonnull
                        String name)
                 throws Exception

Add an image link for a specified attachment.

Parameters:

a -

name -

Returns:

Throws:

Exception

send

public void send()
          throws Exception

Send the message using the BulkMailer's default instance, using a newly allocated connection.

Throws:

Exception

send

public void send(@Nonnull
                 SmtpTransport transport)
          throws Exception

Send the message immediately through the specified transport - only use this if the BulkMailer should not be used. If the sending fails it will not be repeated (an exception will be thrown).

Parameters:

transport -

Throws:

Exception

send

public void send(@Nonnull
                 QDataContext dc)
          throws Exception

Send the message using the BulkMailer using the specified connection. The message will be sent only when that connection is commited, storing the data into the database for the BulkMailer to find.

Parameters:

dc -

Throws:

Exception

sendInternal

public void sendInternal(@Nullable
                         Object through)
                  throws Exception

Queue the message for transmission.

Throws:

Exception

getHtmlBuffer

@Nonnull
public StringBuilder getHtmlBuffer()

getTextBuffer

@Nonnull
public StringBuilder getTextBuffer()

getAttachmentList

@Nonnull
public List<to.etc.webapp.mailer.MailHelper.Attachment> getAttachmentList()

getTo

@Nonnull
public List<Address> getTo()

addTo

public MailHelper addTo(@Nonnull
                        Address a)

addTo

@Nonnull
public MailHelper addTo(@Nonnull
                                 String email)

setFrom

@Nonnull
public MailHelper setFrom(@Nonnull
                                   String from)

setFrom

@Nonnull
public MailHelper setFrom(@Nonnull
                                   Address from)

getSubject

@Nullable
public String getSubject()

setSubject

@Nonnull
public MailHelper setSubject(@Nonnull
                                      String subject)

setLinkRenderer

public void setLinkRenderer(@Nonnull
                            ITextLinkRenderer linkRenderer)

setApplicationURL

public void setApplicationURL(@Nonnull
                              String applicationURL)

Set the root application URL. This URL should always end with "/".

Parameters:

applicationURL -

getApplicationURL

@Nullable
public String getApplicationURL()

addGreeting

protected void addGreeting()

Can be overridden to add a custom greeting.

addTrailer

protected void addTrailer()
                   throws Exception

Can be overridden to add a default trailer.

Throws:

Exception

getApplicationResource

@Nonnull
protected InputStream getApplicationResource(@Nonnull
                                                      String name)
                                               throws Exception

Throws:

Exception