Skip to content

Commit

Permalink
documentation and typos
Browse files Browse the repository at this point in the history
  • Loading branch information
@codylerum
codylerum committed Jun 21, 2012
1 parent 1cd8e08 commit 3c5b31e
Show file tree
Hide file tree
Showing 5 changed files with 240 additions and 12 deletions.
2 changes: 1 addition & 1 deletion api/src/main/java/org/jboss/seam/mail/core/EmailMessage.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,7 @@
import org.jboss.seam.mail.core.enumerations.MessagePriority;

/**
* Stores infomation about an EmailMessage while it is being build and after sending
* Stores information about an EmailMessage while it is being built and after sending
*
* @author Cody Lerum
*/
Expand Down
129 changes: 126 additions & 3 deletions docs/src/main/docbook/en-US/mail-advanced.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,16 +6,139 @@
<section>
<title>MailTransporter</title>
<para>
TO DO
MailTransporter is an interface that allows you to control how the message is handled when the send() method is called.
The default implementation simply sends the message with a javax.mail.Session. The main drawback of this is that the thread is blocked until
your configured email server accepts your messages. This can take milliseconds or minutes depending on the size of your message load on your SMTP
server. While this may be fine for most simple cases, larger applications may wish to employ a queuing function so that messages appear to send
instantly and do not block application execution.
</para>

<para>Overiding the default MailTransporter is simple</para>

<programlisting role="JAVA"><![CDATA[
MailTransporter myTransporter = new MailQueueTransporter();
MailMessage msg = mailMessage.get();
msg.setMailTransporter(myTransporter);]]>
</programlisting>

<para>
A simple implementation might convert the message into a MimeMessage for sending and then fire as a CDI event
so that a CDI @Observer can queue and send the message at a later time.
</para>

<para>
The MailTransporter might look something like this.
</para>

<programlisting role="JAVA"><![CDATA[
public class MailQueueTransporter implements Serializable, MailTransporter {
private static final long serialVersionUID = 1L;
@Inject
@QueuedEmail
private Event<MimeMessage> queueEvent;
@Inject
@ExtensionManaged
private Instance<Session> session;
@Override
public EmailMessage send(EmailMessage emailMessage) {
MimeMessage msg = MailUtility.createMimeMessage(emailMessage, session.get());
queueEvent.fire(msg);
emailMessage.setMessageId(null);
try {
emailMessage.setLastMessageId(msg.getMessageID());
}
catch (MessagingException e) {
throw new SendFailedException("Send Failed ", e);
}
return emailMessage;
}
}]]>
</programlisting>

</section>

<section>
<title>MailConfig</title>
<para>
TO DO
MailConfig supports the following options
</para>
</section>

<itemizedlist>
<listitem>
<para>serverHost - SMTP server to connect to</para>
</listitem>
<listitem>
<para>serverPort - Port to connect to SMTP server</para>
</listitem>
<listitem>
<para>domainName - Used to build the Message-ID header. Format is UUID@domainName (uses <literal>java.net.InetAddress.getLocalHost().getHostName()</literal> if unset)</para>
</listitem>
<listitem>
<para>username - Used when your SMTP server requires authentication</para>
</listitem>
<listitem>
<para>password - Used when your SMTP server requires authentication</para>
</listitem>
<listitem>
<para>enableTls - Allow TLS to be used on this connection</para>
</listitem>
<listitem>
<para>requireTls - Require TLS to be used on this connection</para>
</listitem>
<listitem>
<para>enableSsl - Allow SSL to be used on this connection</para>
</listitem>
<listitem>
<para>auth - Used when your SMTP server requires authentication</para>
</listitem>
<listitem>
<para>jndiSessionName - Load the javax.mail.Session via JNDI rather than creating a new one</para>
</listitem>
</itemizedlist>
</section>

<section>
<title>EmailMessage</title>

<para>
The MimeMessage as defined by javax.mail is a flexible and thus complicated object to work with in it's simplest configuration.
Once multiple content types and attachments are added it can be downright confusing. To make working messages easier to work with, Seam Mail provides the
EmailMessage.java class as part of it's core implementation. An instance of EmailMessage is returned from all of the send methods as well after
manually calling template merge methods.
</para>

<para>
While Seam Mail does not provide a mechanism to receive messages it does provide a way to convert a <literal>javax.mail.MimeMessage</literal>
or <literal>javax.mail.Message</literal> received via POP or IMAP back into a <literal>EmailMessage.java</literal> for easy of reading and
manipulation via the MessageConverter.
</para>

<programlisting role="JAVA"><![CDATA[
Session session = Session.getInstance(pop3Props, null);
Store store = new POP3SSLStore(session, url);
store.connect();
Folder inbox = store.getFolder("INBOX");
inbox.open(Folder.READ_ONLY);
Message[] messages = inbox.getMessages();
List<EmailMessage> emailMessages = new LinkedList<EmailMessage>();
for (Message m : messages) {
EmailMessage e = MessageConverter.convert(m);
emailMessages.add(e);
}
inbox.close(false);
store.close();]]>
</programlisting>
</section>
<!--
vim:et:ts=3:sw=3:tw=120
-->
Expand Down
66 changes: 62 additions & 4 deletions docs/src/main/docbook/en-US/mail-core.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -116,20 +116,78 @@
User user;
MailMessage m = mailMessage.get();
m.from("John Doe<john@test.com>")
.to(user)]]>
m.from("John Doe<john@test.com>");
m.to(user);]]>
</programlisting>

</section>

<section>
<title>Content</title>
<para>TODO</para>
<para>Adding content to a message is simply a matter of calling the appropriate method</para>

<para>For plain text body</para>
<programlisting role="JAVA"><![CDATA[
MailMessage m = mailMessage.get();
m.bodyText("This is the body of my message");]]>
</programlisting>

<para>For HTML body</para>
<programlisting role="JAVA"><![CDATA[
MailMessage m = mailMessage.get();
m.bodyHtml("This is the <b>body</b> of my message");]]>
</programlisting>

<para>For HTML + plain text alternative body</para>
<programlisting role="JAVA"><![CDATA[
MailMessage m = mailMessage.get();
m.bodyHtmlTextAlt("This is the <b>body</b> of my message", "This is a plain text alternative");]]>
</programlisting>

</section>

<section>
<title>Attachments</title>
<para>TODO</para>
<para>Attachments can be added using a few different implementations of the EmailAttachment.java interface</para>

<itemizedlist>
<listitem>
<para>BaseAttachment.java: byte[]</para>
</listitem>
<listitem>
<para>InputStreamAttachment.java: java.io.InputStream</para>
</listitem>
<listitem>
<para>FileAttachment.java: java.io.File</para>
</listitem>
<listitem>
<para>URLAttachment.java: Loads attachment from URL</para>
</listitem>
</itemizedlist>

<para>
Attachments are added by providing the relevant information per implementations as well as a ContentDisposition which
specifics if the attachment is simply "ATTACHMENT" or "INLINE" which allows the attachment to be referenced in the body
when using templating
</para>
<programlisting role="JAVA"><![CDATA[
MailMessage m = mailMessage.get();
m.addAttachment(new FileAttachment(ContentDispostion.ATTACHMENT, new File("myFile"));]]>
</programlisting>

<para>Here is how to reference an attachment inline. Inline attachments are referenced by their filename.</para>

<programlisting role="HTML"><![CDATA[
<html xmlns="http://www.w3.org/1999/xhtml">
<body>
<p><b>Dear <a href="mailto:$person.email">$person.name</a>,</b></p>
<p>This is an example <i>HTML</i> email sent by $version and Velocity.</p>
<p><img src="$mailContext.insert("seamLogo.png")" /></p>
<p>It has an alternative text body for mail readers that don't support html.</p>
</body>
</html>]]>
</programlisting>

</section>

</section>
Expand Down
2 changes: 1 addition & 1 deletion docs/src/main/docbook/en-US/mail-introduction.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,7 @@ public void sendMail() {

<para>
Very little is required to enable this level of functionality in your application. Let's
start off with a little required configuration.
start off with a little requenableTlsjndiSessionNamejava.net.InetAddress.getLocalHost()ired configuration.
</para>
</section>
<!--
Expand Down
53 changes: 50 additions & 3 deletions docs/src/main/docbook/en-US/mail-templating.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,18 +3,65 @@
<chapter id="mail-templating">
<title>Templating</title>

<section>
<title>Basics</title>
<para>
Instead of creating your message body as a String and setting it via the bodyText, bodyHtml and bodyHtmlTextAlt methods you can
use integrated templating to substitute variables for values. Seam Mail supports templating in any of the body parts as well as the subject.
</para>

<para>
The template can either be loaded as from a java.lang.String, java.io.File or java.io.InputStream
</para>

<para>
Values to be used in place of your template variables are loaded via the put method, as a Map or optionally resolved via EL in Velocity
</para>

</section>

<section>
<title>Velocity</title>
<para>
TO DO
Example Usage. See Velocity documentation for syntax.
</para>

<programlisting role="JAVA"><![CDATA[
MailMessage m = mailMessage.get();
m.subject(new VelocityTempalte("Weather for $city, $state")
m.bodyText(new VelocityTemplate(new File("myFile.template"));
m.put("city", "Boston");
m.put("state", "Massachusetts");
m.put("now", new Date());]]>
</programlisting>

<para>
A Velocity Template can be optionally created with an CDI injected CDIVelocityContext. This adds the ability to resolve your variables
via the built in velocity context and a fall through to resolve CDI beans which are @Named.
</para>

<programlisting role="JAVA"><![CDATA[
@Inject
private CDIVelocityContext cdiContext;
MailMessage m = mailMessage.get();
m.bodyText(new VelocityTemplate(new File("myFile.template"), cdiContext);]]>
</programlisting>
</section>

<section>
<title>Freemarker</title>
<title>FreeMarker</title>
<para>
TO DO
FreeMarker usage is essentially the same as Velocity except there is no EL functionality. Consult FreeMarker documentation for Syntax
</para>

<programlisting role="JAVA"><![CDATA[
MailMessage m = mailMessage.get();
m.subject(new FreeMarkerTemplate("ATTN: ${name}")
m.bodyText(new FreeMarkerTemplate("Hello ${name} you have won 1M USD!"));
m.put("name", "Ed Mcmahon");]]>
</programlisting>

</section>
<!--
vim:et:ts=3:sw=3:tw=120
Expand Down

0 comments on commit 3c5b31e

Please sign in to comment.