Senthilkumar Gopal

thoughts, code, ramblings and notes

01 October 2010

Introduction to Velocity

Velocity is an open source templating tool developed by an international volunteer community and hosted by the Apache Software Foundation's Jakarta Project. You can download the freely available source code at the Jakarta Velocity Project Website.

Simple Velocity Template Example

Any application using Velocity requires two parts. The first is the template

Helloworld.vm

  Hello $name!  Welcome to Velocity!

HelloWorld.java:

  import java.io.StringWriter;
  import org.apache.velocity.Template;
  import org.apache.velocity.VelocityContext;
  import org.apache.velocity.app.Velocity;
  public class HelloWorld{
      public static void main( String[] args ) throws Exception {
          /*  Get the Template  */
          Template t = Velocity.getTemplate("Helloworld.vm" );
          /*  create a context and add data */
          VelocityContext context = new VelocityContext();
          context.put("name", "World");
          /* now render the template into a StringWriter */
          StringWriter writer = new StringWriter();
          t.merge( context, writer );
          /* show the World */
          System.out.println( writer.toString() );
      }
  }

Output

  Hello World!  Welcome to Velocity!

Introduction to JAVA MAIL API

The Java Mail API provides the capability to develop email clients and mail-enabled Java applications. It supports the creation of sophisticated user interfaces for mail clients. It includes appropriate convenience classes, which encapsulate common mail functions and protocols. It fits with other packages for the Java platform in order to facilitate its use with other Java APIs. It provides a mail and messaging framework addition to the Java platform.

Although the Java Mail API contains many more classes than those discussed here, concentrating on some of the core classes to start with makes it easy to understand the essence of the API. The following is a brief description of the core classes:

javax.mail.Session

The javax.mail.Session class is the top-level entry class for the Java Mail API, and its most commonly used methods provide the ability to control and load the classes that represent the service provider implementations (SPI) for various mail protocols (Note: A service provider is a developer and/or vendor that provides an implementation for an API; examples of Java Mail API implementations include POP3, SMTP, and IMAP4 -- some are available from Sun, others via third parties.)

javax.mail.Transport

The javax.mail.Transport class is another provider-implemented class and is used for sending a message over a specific protocol.

javax.mail.Message

The javax.mail.Message class is implemented by a provider and models all the details of an actual e-mail message, such as the subject line, sender/recipient e-mail address, sent date, and so on. The guidelines for providers who implement the javax.mail.Message dictate that the actual fetching of e-mail message components should be delayed as long as possible in order to make this class as lightweight as possible.

Simple JAVA Mail Example

  import java.beans.*;
  import javax.mail.*;
  import javax.mail.internet.*;
  import java.io.*;
  import java.util.*;
   public class MailBean {
        public MailBean(String from, String userName, String subject, String content){
           try{
              mail(from, userName, subject, content);
           }catch(MessagingException e)  {}
         }
         public String getBenaInfo(){
              return "A Bean that sends mail";
        }
       public void mail(String from, String userName, String subject, String content)throws MessagingException{
          String smtpHost = "00.00.00.00";
          //start a session
          java.util.Properties properties = System.getProperties();
          properties.put("mail.smtp.host",smtpHost);
          Session session = Session.getInstance(properties,null);

          //Construct a message object
          MimeMessage message = new MimeMessage(session);
          message.setFrom(new InternetAddress(from));
          message.addRecipient(Message.RecipientType.TO,new InternetAddress(userName));
          message.setSubject(subject);
          message.setText(content);
          message.setSentDate(new java.util.Date());

          //connect to transport
          Transport transport = session.getTransport("smtp");
          transport.connect(smtpHost,"", "");

          //send the message and close the connection
          transport.sendMessage(message,message.getAllRecipients());
          transport.close();
       }
   }

As there are a lot of tutorials available for Velocity and Java Mail, this tutorial deals only with the integration of Velocity for easier and more customized mailing abilities.

Project Usage

Our Project required nearly fifty different mail formats to be sent on various stages of the application. The difficult part being that the templates contained loads of dynamic data. Also these templates were being updated on a regular basis making it more difficult for developing the application.

We used Velocity Templates for storing the design and the layout of the mail which needs to be sent and used them for integrating the dynamic attributes into the layout and hence providing a seamless abstraction between the presentation and the business layer.

Step-by-Step Explanation of the Code

SendMessage.java

Velocity Template Merging

JAVA Mail - E-Mail Creation

For adding the image to the e-mail

Adding the Message body content to the e-mail

Sending the E-Mail

Mail.vm

Image Path Macro

This macro is used to return the path to be used as SRC by the images in the HTML. It takes a parameter imgName and returns the string,

  https://$host/$context/images/$imgName

where $host, $context are context variables placed by the JAVA code

The macro looks like this

  #macro( IMGURL $imgName )
      https://$host/$context/images/$imgName
  #end

Example:

  <img src="#IMGURL('mailheader.GIF')" border="0" width="980" height="61">

This will get generated as:

  <img src="https://localhost/myapp/images/mailheader.GIF" border="0" width="980" height="61">

Accessing the Bean Object

The variables in the MailBean object placed in the context can be accessed using, $MailBean.\[variable-name\]
Example: Mail Content : $MailBean.content

mail.properties

This file contains the connection and the other context parameter properties used by the java code

Advantages

Designed as an easy-to-use general templating tool, Velocity is useful in any Java application area that requires data formatting and presentation. Their salient advantages being:
* It adapts to many application areas.
* It offers a simple, clear syntax for the template designer.
* It offers a simple programming model for the developer.
* Because templates and code are separate, you can develop and maintain them independently.
* The Velocity engine easily integrates into any Java application environment, especially Servlets.
* Velocity enables templates to access any public method of data objects in the context.

References