Apache Pluto & Velocity Integration Tutorial Example

Velocity is a Project of Apache Software Foundation, it’s released under Apache Velocity Engine where it’s considered as a Template Engine that provides a Template language to reference objects defined in the Java code.

The major aim of Velocity is to ensure clean separation between the presentation tier and business tier in the web application, similar for numerous presentation technologies that we had used before.

However, you’re developed a Portlet using a JSP & Servlet for registering employees and that you were used a JSP as a presentation tier, Standard Portlet as a controller and a Servlet for handling registration business.

The same example would be used this time, with one difference, in that a Velocity Templates and Velocity Portlet would replace your used JSPs and Standard Portlet, respectively.

This tutorial is going to provide you a full-fledged scenario for how you can use Velocity Templates for getting full functional Portlet that can be used for saving your employees against your database.

Project Structure

Here, you’ll get a full depiction for the whole created project:


Employee Table

Before getting started looking into the way in which you can integrate a Velocity templates inside your application, take a glance for the Employee Table that would be used for retaining the employees and the SQL statement that’s used for creating the Table into your database.


Employee Model

According for MVC (Model-View-Controller) design pattern, the data must be retained inside a model, since it will be sent back and forth between the different components in the application (i.e. View & Controller). Since, we have single Employee Table, an Employee model will look like below:


RegisterEmployeePortlet Velocity Portlet

Creating of Velocity Portlet isn’t much complicated mission, as you may be familiar with many types of Portlets were introduced here. Like any normal Portlet, your Velocity one should look like below:


Here’s detailed explanation for the code mentioned above:

  • Your Portlet should extend org.apache.portals.bridges.velocity.GenericVelocityPortlet.
  • Like any standard Portlet, you have a chance of overriding required methods.
  • Typically, you have an access for different types of requests/responses.
  • As you may delegate the request into your JSP view as it happened in JSP & Servlet Tutorial, you have the ability to do the same thing with the Velocity markup Templates.
  • Since we have a default ViewPage value as init param, the calling of super.doView will give the registerEmployee.vm a chance to handle the request.
  • According for status parameter, you may get accessed success.vm or failure.vm.
  • You can reference your Velocity templates by using their defined path within your project, since they’re considered like any presentation technology you have dealt with. The path that we’ve suggested is /register/registerEmployee.vm, /register/success.vm and /register/faliure.vm.

RegisterEmployeePortlet Velocity Portlet Descriptor

Fortunately, there is not much details that you must be aware of when it comes to define your Portlet inside your Portlet deployment descriptor (Portlet.xml). However, like any Standard Portlet, your Portlet.xml should look like:


Here’s detailed explanation for the code typed above:

  • You should define ViewPage init param for getting registerEmployee.vm displayed once the Portlet accessed through its contained page.
  • Similar for ViewPage, you can add EditPage and HelpPage.
  • Supporting different views require you to tune your supports element.

Application Deployment Descriptor & Maven Build File

You may be asking about how the defined Velocity Templates got executed since no explicit declaration for the way in which that is done. In fact and indeed, a defined Servlet will handle the Velocity Templates interpretation process, so once your Portlet had delegated the request into any Velocity resources that ends with the *.vm, the Velocity Servlet get executed and the HTML output has returned. Look below at the deployment descriptor (web.xml):


As you can notice, BridgesVelocityServlet has used in conjunction with the mapping element. Let’s glance the used Maven build file:


Velocity Templates (Views)

As we’ve stated earlier, you can use a Velocity Templates instead of using default JSP for rendering your requested view. Similar for JSP, an implicit objects have been defined inside your Velocity Templates for getting used while you’re developing your views. Let’s look at the created views and see the major things that must be noticed.


Here’s detailed explanation for the code listed above:

  • Implicit objects that you may need are, RenderRequest, RenderResponse & PortletConfig.
  • You should use $renderRequest, $renderResponse & $portletConfig for getting referenced these objects, respectively.
  • Since these objects are Java Objects, so you have them with all accompanies relevant functions, just like you’re invoked them from within your Standard Portlet.
  • We created an actionUrl by calling $renderResponse.createActionURL().



Here’s detailed explanation for both of success and failure velocity templates:

  • We used $renderRequest.getContextPath() for specifying the context of the running application.
  • For getting safe code, since the Velocity Templates may contain the same JavaScript variable/code, you have the opportunity of making a unique identifier using $renderReponse.getNamespace().
  • You have the ability to get accessed specific request attributes by calling of $renderRequest.getParamater().
  • $renderResponse().createRenderURL() is used for rendering a render request against your Portlet.

Register Employee Business Handler

Handling of employee registration business isn’t a Portlet mission, as it’s considered like controller when it comes to map your components into MVC design. Regardless, of the type of Portlet you were used, we have a separate Servlet that’s responsible of handling the registration process; extract the request’s parameters and calling the database utilities for got employee saved.


Database Utility

Since our application has accessed the database for getting employee instance persisted, it’s important to handle the database code with the best practice we have own, EmployeeDAO ConnectionUtility are both classes used for accessing the database, safely and asynchronously.



Employee Registration Demo

We assumed that you have a running instance of Apache Pluto as you are also created a Portal page named JournalDev and you’re also familiar with the way which can be used for deploying your Portlet into your Portal page. In case, you’ve heard this for the first time, it’s worth for you to return back into our Apache Pluto Introduction for get everything relevant done.

Employee-Table (2)

Once the user has activated the register action, the Portlet’s processAction method has been executed and the Register Servlet would be invoked. The user will be informed instantly with the result of registration operation and whether it’s got finished successfully or not.

Now, what’s happened just in case you’ve tried to register another employee with the same identifier:

Employee-Table (2)


It’s fantastic, as you can create whatever you want of Portlets using the standard Portlet container specification. You’ve already faced a JSP & Servlet, PHP, JSF, Struts & now a Velocity Templates one. Your comments or notes are highly appreciated as you can find the downloaded source listed below for your practice.

By admin

Leave a Reply

%d bloggers like this: