Introduction Into Apache Pluto RI, Portal & Portlet Container Example Tutorial [Latest]

Developing of Portal and all accompanies APIs were unorganized efforts, in that every propriety has developed its own Portal/Portlet without giving any chance to be aligned with any of type of standards that makes the integration between all of implementations quite easy. Java Community has noticed that and for seeking a kind of standardization, they have released the first Java Specification Request (JSR-168) before introducing a JSR-286 in March 2008.

JSR-168 has defined set of APIs for Portal computing and addressing the areas of aggregation, presentation, security and personalization as it’s also enabled interoperability between Portlets and Portals. At the same time, JSR-286 has aligned with a Java EE containers and integrated with all Portlet relevant specifications like WSRP specification 2.0.

This tutorial will help you in getting started with developing and deploying your Portlet applications into a standard and compliant Portlet container. Following bullets point shows you the main subjects that you’re going to pass through before finally getting a HelloWorld sample developed and deployed.

Apache Pluto Portal – Introduction

Apache Pluto represents the reference implementation of both of the Java portlet specifications mentioned above. Apache Pluto is partitioned into these following main parts:

• Apache Pluto – Container: Is a Pluto container which is considered as a core component of the Apache Pluto. It’s meant to be embedded inside the Pluto Portal to provide Java Portlet Specification Compliance.
• Apache Pluto – Portal: Is a Pluto’s user interface components (web application), it’s just a user interface has embedded within it a lightweight environment for developing and testing portlets.
• Apache Pluto – Portal Driver: Is a driver library for the Pluto portlet container, that said, all of required services implementations and utilities for implementing a portal which utilizes the container are implemented inside the Portal Driver.
• 

Apache Pluto Portal – Installation

As we’ve stated earlier, Apache Pluto is a reference implementation for the specifications of portlet container. Using of Apache Pluto will help you getting your portlets developed, deployed and tested easily.

However, this section will help you mainly getting Apache Pluto installed and running through using of Eclipse IDE. Following below all required steps for doing that:

• Download Apache Pluto binary from Apache site. We have two versions of Apache Pluto, pluto-bundle that provides you a Pluto and Tomcat bundled together. Meanwhile, pluto-source-release which provides you the Pluto source code; requires you build and deploy Pluto into your own environment. Basically, we’d like download the bundled version that’s released under pluto-2.0.3-bundle.zip.
• Extract the bundle into your local storage. We’ve supposed D:Apache Plutopluto-2.0.3 path for tutorial purposes.
• Configure your tomcat-users.xml file. It looks like:

tomcat-users.xml

<?xml version='1.0' encoding='utf-8'?>
<tomcat-users>
	<role rolename="tomcat"/>
	<role rolename="role1"/>
	<role rolename="manager-gui"/>
	<user username="tomcat" password="tomcat" roles="tomcat"/>
	<user username="both" password="tomcat" roles="tomcat,role1"/>
	<user username="role1" password="tomcat" roles="role1"/>
	<user name="tomcat" password="tomcat" roles="tomcat,pluto,manager,manager-gui" />
	<user name="pluto" password="pluto" roles="pluto,manager,manager-gui" />
</tomcat-users>

• Start up your Tomcat server by executing D:Apache Plutopluto-2.0.3binstartup.bat.
• Waiting your Tomcat server to be started.
• 

• Open your browser and type in https://localhost:8080/pluto and you must see the below log in screen.
• 

• Log in into Apache Pluto Portal using username: tomcat and password: tomcat. Once you’ve logged in you should see the main page of Apache Pluto. In case you cannot, just double check into your tomcat-users.xml file and make sure it’s identical to that one provided.
• Main page of Apache Pluto is just a page addressed by https://localhost:8080/pluto/portal and it contains two portlets.
• 

• Shut down your Apache Pluto by closing the running console and open your eclipse IDE. For this purpose, we’ve used Eclipse IDE Kepler 4.3.
• From server window click on No servers are available. Click this link to create a new server ...
• 

• Select Tomcat v7.0 Server as a server type to be created and click next.
• Configure the Tomcat server by browsing the Apache Pluto home.
• 

• Click finish.
• Double click on the added server to specify the server path (catalina-base) and deploy path.
• Make sure your server configuration is configured like below
• 

• Start up your server from the Servers pane. Your Eclipse console should look like below
• 

• Open your browser and type the same url that’s already typed before and you will be able to see the same log in page. In case you’ve missed out the configuration step that’s already happened from inside the Eclipse IDE, you won’t be able to see your log in screen.
• After you’ve logged in into your Apache Pluto, just try to navigate into Pluto Admin to check the tomcat-users.xml configuration. Generally, you must be able to see the manager page that will be used for deploying/undeploying your portlet applications once you’ve clicked on Upload and deploy a new portlet war.
• 
• 

Setting Up HelloWorld Portlet Project

A Portlet application is just like any normal WAR file that you may create. Even it contains some sort of additional sources that serve both of Portal and Portlet Container environments, but it’s finally deployed as a WAR.

Before getting started build the first HelloWorld portlet and deploy it into Apache Pluto Portal, just let’s see the structure of the assumed WAR file that we’re going to create.

Here’s detailed explanation for the structure being shown in the previous figure:

• You are about getting normal WAR file.
• Your Portlet, is a normal Java class that’s located inside your source folder.
• ContextDefinition.xml is a Tomcat context deployment descriptor that must has the same name as your artifactId with an XML extension. This deployment descriptor will allow Pluto web application to access any required resources from your deployed Portlet application.
• Portlet.xml file that’s located beneath WEB-INF folder will be required by the Portlet container for defining the portlets.

Let’s now build up our HelloWorld Portlet application and see how can we use the Eclipse IDE & Maven for such that purpose. Following all required steps:

• Right-click from Project Explorer panel and make sure you are selecting New – Project – Other.
• 

• Expand Maven and select Maven Project and make a double next.
• From New Maven project, select maven-archetype-webapp.
• 

• Click next and fill in all required information (groupId, artifactId, version and package) to get ready-for-use project.
• 

• Click finish. Look below at the initial view.
• 

• In case you didn’t find your src/main/java, just create it as simple as that; on Java Resources – Right-click – New – Source Folder. Specify your Project name (i.e HelloWorldPortlet) and Folder name (i.e. src/main/java). May Eclipse tell you that this folder is already created, where it’s not. Just type src/main/jav and rename the folder after after then to be identical for what you did see int the figure above.
• Create your own Tomcat context file. Beneath of resources, create a HelloWorldPortlet.xml file. Make sure it contains the following lines as it’s named like your typed ArtifactId.

"HelloWorldPortlet.xml

<?xml version="1.0" encoding="UTF-8"?>
<Context path="/HelloWorldPortlet" docBase="HelloWorldPortlet" crossContext="true"></Context>

• Create your portlet deployment descriptor (portlet.xml) file and make it empty.

Prepare Maven Build File

Maven is a build automation and Project Management tool. Developers that they want to develop a portlet web application needs to read this portion thoroughly. Without proper using of Maven in creating your Portlet application, you may face a lot of obstacles specially when it comes to deployment phase. Following below required Maven build file that would help you avoiding a lot of work you must achieve for getting proper deployment WAR package.

pom.xml

<project xmlns="https://maven.apache.org/POM/4.0.0" xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="https://maven.apache.org/POM/4.0.0 https://maven.apache.org/maven-v4_0_0.xsd">
	<modelVersion>4.0.0</modelVersion>
	<groupId>com.journaldev</groupId>
	<artifactId>HelloWorldPortlet</artifactId>
	<packaging>war</packaging>
	<version>0.0.1-SNAPSHOT</version>
	<name>HelloWorldPortlet Maven Webapp</name>
	<url>https://maven.apache.org</url>
	<dependencies>
		<!-- Java Portlet Specification V2.0 -->
		<dependency>
			<groupId>org.apache.portals</groupId>
			<artifactId>portlet-api_2.0_spec</artifactId>
			<version>1.0</version>
			<scope>provided</scope>
		</dependency>
	</dependencies>
	<build>
          <plugins>
		    <!-- bind 'pluto2:assemble' goal to 'process-resources' lifecycle -->
		    <!-- This plugin will read your portlet.xml and web.xml and injects required lines -->
            <plugin>
                <groupId>org.apache.portals.pluto</groupId>
                <artifactId>maven-pluto-plugin</artifactId>
                <version>2.1.0-M3</version>
                <executions>
                    <execution>
                        <phase>generate-resources</phase>
                        <goals>
                            <goal>assemble</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>
            <!-- configure maven-war-plugin to use updated web.xml -->
            <!-- This plugin will make sure your WAR will contain the updated web.xml-->
            <plugin>
                <artifactId>maven-war-plugin</artifactId>
                <configuration>
                    <webXml>${project.build.directory}/pluto-resources/web.xml</webXml>
                </configuration>
            </plugin>
          </plugin>
	</build>
</project>

Here’s detailed explanation for code listed above:

• Portlet API is just the only required library that you should add. Several libraries are needed, but all of them will already be provided by the Apache Tomcat itself.
• To make sure your web.xml file will contain all needed lines for getting your Portlet deployed properly, you should use Maven Pluto Plugin. This plugin will read your portlet.xml file and updated your web.xml file with all required lines. This plugin will generate the updated web.xml file and put it into your target/pluto-resources folder.
• You won’t get the updated web.xml file into your generated WAR if you’ve not used the Maven WAR plugin. This plugin will read your generated web.xml file that’s located beneath target/pluto-resources and export it with your generated WAR.

Create HelloWorld Portlet

After building up your Project and setting your Maven file, it’s time to get into developing your first Portlet mission. Portlet is just like any Servlet you’ve ever created before, but instead of putting your code inside doGet, doPost, and so on, you are requesting to put your code inside doView, doEdit and doHelp.

Developing of Servlet was very easy, as you can print directly into your browser using of response.getWrite().print(). That’s applicable also when you’re working with Portlet. Next coming tutorials will highlight all of these concepts more than your expectation, so let’s see a simple HelloWorldPortlet that print out a hello message.

package com.journaldev.portlet;
import java.io.IOException;
import javax.portlet.GenericPortlet;
import javax.portlet.PortletException;
import javax.portlet.RenderRequest;
import javax.portlet.RenderResponse;
public class HelloWorldPortlet extends GenericPortlet{
    public void doView( RenderRequest request, RenderResponse response )
            throws PortletException, IOException {
    		response.getWriter().print("Jounral Dev Provides you Hello World Portlet !");
        }
}

Here’s detailed explanation for the code listed above:

• HelloWorldPortlet is a Java class that extends GenericPortlet.
• GenericPortlet is a ready-made class that’s imported from javax.portlet package.
• javax.portlet package represents the API of Java Portlet Specification 2.0 that’s imported by the Maven build file.
• Even that you cannot invoke your Portlet directly through using of url typed into address – as you did with Servlet – instead of that, you’re defining a Portal page that contains your Portlet.
• Once you’ve requested a Portal page, the Portal will communicate with the Portlet container and execute your doView as a callback for your request.

Our portlet class is ready, but let’s see what are the lines you need to add into your portlet.xml.

portlet.xml

<?xml version="1.0" encoding="UTF-8"?>
<portlet-app xmlns="https://java.sun.com/xml/ns/portlet/portlet-app_1_0.xsd"
	version="1.0" xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="https://java.sun.com/xml/ns/portlet/portlet-app_1_0.xsd
                        https://java.sun.com/xml/ns/portlet/portlet-app_1_0.xsd">
	<portlet>
		<description>Write here a short description about your portlet.</description>
		<portlet-name>HelloWorldPortlet</portlet-name>
		<display-name>HelloWorldPortlet Portlet</display-name>
		<portlet-class>com.journaldev.portlet.HelloWorldPortlet</portlet-class>
		<supports>
			<mime-type>text/html</mime-type>
			<portlet-mode>VIEW</portlet-mode>
		</supports>
		<supported-locale>en</supported-locale>
                <portlet-info>
                        <title>Hello World Portlet</title>
                        <short-title>Hello World</short-title>
                        <keywords>Hello,pluto</keywords>
                </portlet-info>
	</portlet>
</portlet-app>

Here’s detailed explanation for the code listed above:

• Your Portlet must be defined inside your portlet.xml ( Portlet deployment descriptor).
• You define your portlet inside a block that begins with <portlet> and ends with </portlet>.
• You specify your portlet’s description, portlet-name, display-name, portlet-class, mime-type, portlet mode and supported locales. There are very amount of options that can be provided here, and they will be explained later on.
• Make sure you are adding a portlet-info, in case you’ve missed them out, you will get an exception says Can’t find bundle resources.

Deploying HelloWorld Portlet

Now, it’s time to get your Portlet installed into your Portal, but before going forward, let’s see the form of the web.xml file before executing Pluto maven’s plugin.

web.xml

<!DOCTYPE web-app PUBLIC
 "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"
 "https://java.sun.com/dtd/web-app_2_3.dtd" >
<web-app>
  <display-name>Archetype Created Web Application</display-name>
</web-app>

As you’ve noticed, nothing defined here. Just open your command and navigate into your Project and type mvn clean package followed by enter. Your Deployment Descriptor will look like:

web.xml

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN" "https://java.sun.com/dtd/web-app_2_3.dtd">
<web-app>
	<display-name>Archetype Created Web Application</display-name>
	<servlet>
		<servlet-name>HelloWorldPortlet</servlet-name>
		<servlet-class>org.apache.pluto.container.driver.PortletServlet</servlet-class>
		<init-param>
			<param-name>portlet-name</param-name>
			<param-value>HelloWorldPortlet</param-value>
		</init-param>
		<load-on-startup>1</load-on-startup>
	</servlet>
	<servlet-mapping>
		<servlet-name>HelloWorldPortlet</servlet-name>
		<url-pattern>/PlutoInvoker/HelloWorldPortlet</url-pattern>
	</servlet-mapping>
</web-app>

Here’s detailed explanation for the code listed above:

• Pluto maven plugin has read your portlet.xml file and update your deployment descriptor accordingly. Note that the updated web.xml file will be part of the WAR file only, the source file in the project will not be updated.
• Portlet container is built on Servlet container and it has Servlet Container feature for achieving its work. So that a new Servlet HelloWorldPortlet has been defined and a special url pattern added also.

Now, copy your generated WAR file into Apache Pluto Tomcat webapps folder.

Find your Eclipse console, as you should notice that a new WAR has been deployed and a new Portlet has been registered.

As you’ve noticed, messages of deploying a web application archive and registering a new Portlet are displayed into your Eclipse console. If you were reached into this phase, you can say that about of 90% of the work has been done.

Just open your Apache Pluto application and ensure that your Portlet is deployed successfully.

Another way to ensure that your deployment went properly just enter the manager of the Apache Tomcat itself and find your deployment there.

Define Apache Pluto Portal Page

As we’ve stated earlier, Portlet hasn’t been separated component like Servlet, in order to see a Portlet, you must include it inside a Portal Page. Creating of Portal Page against Apache Pluto isn’t a complicated mission.

If you were laying on Pluto Admin, you can use Add Page to add a new Page. Let’s add a new Pluto page and called it JournalDev.

For now, you have a new page called JournalDev, as you can add whatever you want of Portlet inside it by using the Portlet Applications. Just make sure you’re selected the JournalDev page and by navigating Portlet Applications, choose HelloWorldPortlet-0.0.1-SNAPSHOT and select HelloWorldPortlet after then. Finally click on Add Portlet located at the end of the page.

As you’ve noticed a new Page JournalDev has been added at the most right position. So you can navigate into by clicking on. There you will see your HelloWorldPortlet like below.

Final HelloWorld Portlet Application Structure

Find below final Project Structure image.

Summary

Apache Pluto is a reference implementation for Java Specification Portlet API 2.0. This tutorial intended to provide you the whole steps required for getting Portlet application developed and deployed against Apache Pluto Portal. Contribute us by commenting below and find a full downloaded source code for your reference.