The solutions works in Liferay 6.0 EE SP1 and can include portlets from Liferay itself as well as portlets coming from other plug-ins. Other versions of Liferay have not been tested yet.

I hope this snippet is as useful to you as it is to me!

package nl.liones.liferay;
import com.liferay.portal.kernel.exception.SystemException;
import com.liferay.portal.kernel.portlet.PortletBag;
import com.liferay.portal.kernel.portlet.PortletBagPool;
import com.liferay.portal.kernel.util.WebKeys;
import com.liferay.portal.service.PortletLocalServiceUtil;
import com.liferay.portal.theme.PortletDisplay;
import com.liferay.portal.theme.ThemeDisplay;
import com.liferay.portal.util.PortalUtil;
import com.liferay.portal.util.PortletKeys;
import javax.portlet.PortletRequest;
import javax.portlet.PortletResponse;
import javax.portlet.ValidatorException;
import javax.servlet.ServletException;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import java.io.IOException;
import java.util.Collections;
import java.util.Enumeration;
import java.util.HashMap;
import java.util.Map;
/**
 * Portlet embed utility method.
 *
 * @author Stef Busking (Liones), Bert Willems (Liones)
 */
public class RuntimePortletEmbedUtil {
    /**
     * Renders the given portlet as a runtime portlet and returns the portlet's HTML.
     *
     * @param request     The {@link PortletRequest}.
     * @param response    The {@link PortletResponse}.
     * @param portletId   The ID of the portlet to render, includes instance ID for instance portlets.
     * @param queryString The query string to use for the portlet.
     * @return The HTML for the given portlet.
     * @throws SystemException    on error.
     * @throws IOException        on error.
     * @throws ServletException   on error.
     * @throws ValidatorException on error.
     */
    public static String renderPortlet(final PortletRequest request, final PortletResponse response, final String portletId, final String queryString) throws SystemException, IOException, ServletException, ValidatorException {
        // Get servlet request / response
        HttpServletRequest servletRequest = PortalUtil.getOriginalServletRequest(PortalUtil.getHttpServletRequest(request));
        HttpServletResponse servletResponse = PortalUtil.getHttpServletResponse(response);
        // Get theme display
        final ThemeDisplay themeDisplay = (ThemeDisplay) servletRequest.getAttribute(WebKeys.THEME_DISPLAY);
        // Backup current state
        PortletDisplay portletDisplay = themeDisplay.getPortletDisplay();
        PortletDisplay portletDisplayClone = new PortletDisplay();
        portletDisplay.copyTo(portletDisplayClone);
        final Map<String, Object> requestAttributeBackup = new HashMap<String, Object>();
        for (final String key : Collections.list((Enumeration<String>) servletRequest.getAttributeNames())) {
            requestAttributeBackup.put(key, servletRequest.getAttribute(key));
        }
        // Render the portlet as a runtime portlet
        String result;
        try {
            PortletBag implPortletBag = PortletBagPool.get(PortletKeys.JOURNAL);
            com.liferay.portal.model.Portlet portlet = PortletLocalServiceUtil.getPortletById(PortalUtil.getCompanyId(request), portletId);
            servletRequest.setAttribute(WebKeys.RENDER_PORTLET_RESOURCE, Boolean.TRUE);
            result = PortalUtil.renderPortlet(implPortletBag.getServletContext(), servletRequest, servletResponse, portlet, queryString, false);
        } finally {
            // Restore the state
            portletDisplay.copyFrom(portletDisplayClone);
            portletDisplayClone.recycle();
            for (final String key : Collections.list((Enumeration<String>) servletRequest.getAttributeNames())) {
                if (!requestAttributeBackup.containsKey(key)) {
                    servletRequest.removeAttribute(key);
                }
            }
            for (final Map.Entry<String, Object> entry : requestAttributeBackup.entrySet()) {
                servletRequest.setAttribute(entry.getKey(), entry.getValue());
            }
        }
        return result;
    }
}

Using this code
The snippet below demos how to embed the Liferay Web Form portlet and how to set a preference for this embedded portlet.

final String portletId = "1_WAR_webformportlet_INSTANCE_abcd";
final ThemeDisplay themeDisplay = (ThemeDisplay) request.getAttribute(WebKeys.THEME_DISPLAY);
// get the preferences
final PortletPreferences prefs = PortletPreferencesUtilityLocalServiceUtil.getWrappedPortletPreferences(themeDisplay, portletId);
// set a preference
prefs.setValue("successURL", "some url");
// dont forget to store the preferences
formPrefs.store();
// get the HTML from the portlet
final String portletHtml = RuntimePortletEmbedUtil.renderPortlet(request, response, portletId, "");

But first let’s watch Thomas’s talk:

I will use the Kluwer Support portal I recently built as an example. I created a new portlet which was deployed into Liferay, an enterprise portal, which runs on top of the JBoss Application Server which is programmed in Java running on the Java Virtual Machine running on top of the CentOS operating system running on top of an Hardware Abstraction Layer running on top of hardware. Liferay uses Spring to inject services  in my portlet which retrieve data through Hibernate from MySQL.

In order to implement the customer requirements the portlet had to use Spring to separate presentation from business logic which connect to a SOAP web service through HTTP using Axis in order to retrieve data which was index by Solr, a Lucene based search server in order to be able to render a search form using JavaServer Pages and Velocity as HTML which is styled using CSS and made interactively using JavaScript.

If this technological enumeration (a total of 21) makes your head spin you got another thing coming because I only scratched the surface. I estimate it took an army of a million computer scientists over a billion man-hours to make this application work. A small miracle in my opinion!

But first lets have a quick look at the problem again: We needed to support different styles per portlet and ‘read more’ links which needed to work for both custom and out-of-the-box potlets. Let have a look at some of the different ‘web-content display portlet’ styles used in the portal:

Liferay, at least not version 5.2.8 EE, does not support these requirements out of the box (Not entirely true: Liferay does allow you to specify custom CSS rules per portlet instance, but you would need a front-end specialist to maintain the website which IMHO is not acceptable).

To make it even more difficult we were not allowed to use Liferay Ext or place many hooks or have impact on existing communities in the portal instance.

The solution that we came up with was to use an JSP hook to replace Liferays ‘look and feel’ page. We wrote some code which would add a new tab displaying theme specific properties to the page if the theme had a specific setting specifying the path to a velocity template which in turn would render the theme specific settings.

Some of the settings we included are:

• Custom CSS classes
• Display mode
• Read more link URL & label

However, we can easily add more, or less, properties depending on the requirements without having to touch the implementation code or break the theme for Kluwer Support.

Next we implemented a servlet which handles the storage of our custom properties. The servlet simple updates the portlet preferences with the custom properties. The properties are read by the theme and used to determine how to render the portlet.

We all implemented this in a separate deployment package except for the mentioned velocity template which resided in the theme package. By doing this, we solved the problem not only for this project but for upcoming projects as well: We will just implement a theme and the velocity template containing the custom properties for that particular project! I am willing to share some code, let met know if you want it.

I am very curious about the way you would have solved this problem and what you think of this solution so please write a comment.

But let’s have a look at the result first:

I hope you agree with me when I say that it looks great, I know for a fact a lot of people do. You can find the actual portal at http://www.kluwer.nl/support, although the portal is in Dutch, feel free to look around.

In the next few paragraphs I will share some challenges we faced and the lessons we learned while implementing the Kluwer Support portal.

Design

One of the challenges for us in this project was to transform the graphical design, created by Evident, into HTML and then into a Liferay theme. Our front-end specialist, Vincent Smedinga, first transformed the PSD into HMTL using the latest versions of HTML 5, CSS 3 and other best front-end practices like Modernizr en Selectivzr. These technologies enabled him to create the HTML semantically correct, let it display correctly in older, less compliant browsers while staying true to the graphical design.

The now finished HTML needed to be transformed into Liferay components like themes, layouts and the actual portlets. That task proofed to be quiet challenging for Stef Busking (one of our Liferay software engineers) and me. The reason why this task was challenging is that fact that we needed to reuse as much standard Liferay components as possible. The two things that it so difficult and almost impossible were the different styles per portlet and the ‘read more’ links. Let have a look at some of the different ‘web-content display portlet’ styles used in the portal:

Liferay, at least not version 5.2.8 EE, does not support these requirements out of the box (Not entirely true: Liferay does allow you to specify custom CSS rules per portlet instance, but you would need a front-end specialist to maintain the website which IMHO is not acceptable).

To make it even more difficult we were not allowed to use Liferay Ext or place many hooks or have impact on existing communities in the portal instance,  which, in my opinion, is a good thing. However, that forced us to think hard and we (although I should have said Stef here because he is the one who came up with the idea) found a clever solution to solve both problems with the use of one JSP hook.

I want you think about how you would have solved this problem in these fairly strict conditions. You can find the solution here.

Search

Another problem we faced were the search requirements like ‘auto complete’ and sorting web content (FAQ entries and videos) according to their structure. We decided that the default Liferay search option would not be sufficient because we would not be able to implement the ‘auto complete’.

After researching several alternatives we choose to use one of the most powerful open-source enterprise search engines available: Apache Solr. We implemented a client for it which uses the Liferay service bus to swap out the default Liferay search engine.

Now we had the proper infrastructure at our disposal it was a ‘trivial’ task to implement two custom portlets (search box in navigation bar and a result portlet). I quoted ‘trivial’ because it was not quiet trivial. We encountered a very annoying issue in the default web-content indexer Liferay provides:  it does not specify the structure ID nor the template ID in the document to be indexed.

I won’t go into specific how we solved this problem. It is sufficient to say that we are working on a robust solution which will ‘unpack’ the document  we receive from the indexer and enrich it with those fields before sending it to Solr for indexing.

Wrap up

Like always there is always more to share but that is really it for this post. Don’t forget to think about the ‘portlet design problem’ and stay tuned for our solution! As always: comments are most welcome.

The permission system in Liferay is pretty powerful: you configure permissions on roles or teams. Next you apply roles to either groups (communities, organizations) or individual users. In this article we will define a new permission: the permission to access our “very exiting business logic” sayHello. After all, we have invested countless hours in developing it; we don’t want everybody to use it without us knowing .

I hope this article is useful to you. Please let me know if you have any questions or comments; just drop me a message and I will get back to you as soon as I can.

0. Project Setup

I have made some modifications to the code since my last article, so please download and unzip the starting point of our application. Please familiarize yourself with the project structure. I have refactored the view of the SayHelloPortlet to render using a JSP called sayHello.jsp, this will help us further along in this article.

Please note that I have modified the service contract specified in HelloWorldService.java. I have added the groupId parameter which we will use later in this article. Here is the new service contract:

String sayHello(long groupId, String name);

I have updated all the service implementation files as well to reflect changes in the contract.

1. Implement the permission check on the service

The first step is to implement the actual check on permission in our service implementation. Replace the sayHello method in HelloWorldServiceImpl.java with the following code (note the marked lines are new lines):

public String sayHello(long groupId, String name) {
    try {
        if (!getPermissionChecker().hasPermission(groupId, "nl.devatwork.hello.world.service", groupId, "SAY_HELLO"))
            return "Hah, I don't think you can use my service. You don't have permission";
    } catch (PrincipalException ex) {
        return "security blew up";
    }

    return "Hello, " + name;
}

Lets dissect this code: The first thing we do is to get the instance of the PermissionChecker from our base class PrincipalBean. The PermissionChecker will do the heavy lifting for us, that is convenient isn’t it?

The second step is the call to the method hasPermission. This method performs the actual check for us. The method has the following signature:

public boolean hasPermission(long groupId, String name, long primKey, String actionId);

The first argument, groupId, determines the scope of the check. Remember I told you that you can apply roles to communities and organizations? Those things are groups with and ID. In the next step I will show you how we will get the value for groupId.

The second argument, name, is the name of our permission. The convention is we pass a String representation of our package in which the service lives.

The third argument, primKey, is the primary key of the resource we are protecting. Our service is a so-called top level resource which do not have a primary key that is why we will use the value of groupId. If we would have a model stored in the database we would specify the ID of the model here.

The final argument, actionId, is the identifier of the action. We will use a capitalized version of the method name here.

I think that is enough info about these few lines of code.

2. Getting the scope

Now that our service checks for permission we need to modify our portlet to provide the correct groupId in order for Liferay to scope the authorization properly. Please add the highlighted lines to SayHelloPortlet.java:

public void doView(RenderRequest request, RenderResponse response) throws PortletException, java.io.IOException {
    ThemeDisplay themeDisplay = (ThemeDisplay) request.getAttribute(WebKeys.THEME_DISPLAY);
    long groupId = themeDisplay.getScopeGroupId();

    String msg = HelloWorldServiceUtil.sayHello(groupId, "Liferay Dev");
    request.setAttribute("msg", msg);
    request.setAttribute("groupId", groupId);

    getPortletContext().getRequestDispatcher("/WEB-INF/jsp/sayHello.jsp").include(request, response);
}

As you can see Liferay provides a nice utility called ThemeDisplay from which we can get the scope groupId.

3. Telling Liferay about our new permission

So far we have implemented the necessary code to check for permission. Now we have to inform Liferay that there is a new permission, otherwise you won’t be able to configure it and that would be a waste of effort, wouldn’t it? Create a new file called portlet.properties in the resource folder of the portlet application and paste the following content into it:

resource.actions.configs=resource-actions/default.xml

This properties file tells Liferay to look for resource actions (permissions) in default.xml in the folder resource-actions. Lets create that file now and paste the following content into it:

<?xml version="1.0" encoding="UTF-8"?>
<resource-action-mapping>
    <model-resource>
        <model-name>nl.devatwork.hello.world.service</model-name>
        <portlet-ref>
            <portlet-name>SayHelloPortlet</portlet-name>
        </portlet-ref>

        <supports>
            <action-key>SAY_HELLO</action-key>
        </supports>

        <community-defaults/>
        <guest-defaults/>
        <guest-unsupported/>

    </model-resource>
</resource-action-mapping>

I have highlighted the important lines. Please take a look at the first highlighted line. Does it look familiar to you? Yes, it is the same as the value of the name argument of the hasPermission method.

The second highlighted line tells Liferay that the SayHelloPortlet can configure this permission, I will show you how in the next step.

The final highlighted line should also look familiar to you. It is the same as the value of the actionId argument of the hasPermission method.

4. Create configure permissions link

This is the final step, we implemented the check, we told Liferay about our new permission. Now we need a place to configure it. Modify sayHello.jsp:

<%@ page contentType="text/html" isELIgnored="false" %>
<%@ include file="/WEB-INF/jsp/include.jsp" %>
<liferay-security:permissionsURL
        modelResource="nl.devatwork.hello.world.service"
        modelResourceDescription="Hello Service Permissions"
        resourcePrimKey="${groupId}"
        var="permissionURL"/>

<p>the msg was: ${msg}</p>

<div>
    <p>lets <a href="${permissionURL}">configure</a> the permission for our service</p>
</div>

We have added a link to configure permission to our service. Notice that modelResource is again the same as the value of the name argument of the hasPermission method.

Now that we have implemented all the necessary changes we can compile and deploy the new JAR’s and WAR’s and start our application. Go ahead and add permissions, remove them, login and logout under different accounts. Our permission is working like a charm. If you haven’t followed all the steps above you can download the finished project.

That is it for now,I hope you have learned something. Let me know if you have any questions or comments. Bye.

Liferay exposes the services based on Axis using a separate web application called tunnel-web. We will hook into tunnel-web so our service will be exposed in exactly the same way Liferay services are externalized. Let’s get started.

0. Project Setup

We will pick up from where we ended in the previous article. I have you haven’t followed the previous article you can download the initial project setup here. Please take a minute to familiarize yourself with the project structure.

We need to add a new dependencies to the pom of the service contract library:

<dependency>
    <groupId>com.liferay.portal</groupId>
    <artifactId>portal-service</artifactId>
    <version>${liferay.version}</version>
    <scope>provided</scope>
</dependency>
<dependency>
    <groupId>com.liferay.portal</groupId>
    <artifactId>portal-kernel</artifactId>
    <version>${liferay.version}</version>
    <scope>provided</scope>
</dependency>
<dependency>
    <groupId>com.liferay.portal</groupId>
    <artifactId>portal-impl</artifactId>
    <version>${liferay.version}</version>
    <scope>provided</scope>
</dependency>

1. Prepare the portal

Make sure tunnel-web is installed in your application server. See the Liferay administration guide for details. The access to the web-service is restricted based on IP address. Open your portal-ext.properties and add the following lines to allow specified IP addresses to access to the web-services.

axis.servlet.hosts.allowed=127.0.0.1,SERVER_IP
axis.servlet.https.required=false

2. Add the Service Classes

Ok lets get down to business. The first step is to create the web service class in the service contract library. Create a new class called HelloWorldServiceSoap in the package nl.devatwork.hello.world.service.http and copy the following code into it:

package nl.devatwork.hello.world.service.http;

import com.liferay.portal.kernel.log.Log;
import com.liferay.portal.kernel.log.LogFactoryUtil;
import nl.devatwork.hello.world.service.HelloWorldServiceUtil;

import java.rmi.RemoteException;

public class HelloWorldServiceSoap {
    private static Log _log = LogFactoryUtil.getLog(HelloWorldServiceSoap.class);

    public static String sayHello(String name)
            throws RemoteException {
        String result;
        try {
            result = HelloWorldServiceUtil.sayHello(name);
        } catch (Exception e) {
            _log.error(e, e);

            throw new RemoteException(e.getMessage());
        }

        return result;
    }
}

This class wraps SOAP calls and maps them to the appropriate service call.

You can now build the service contract library by executing the following command in the /hello-world-service/ folder:

mvn clean package

Copy the resulting JAR file (/hello-world-service/target/hello-world-service-1.0.0-SNAPSHOT.jar) to the /lib/ext folder of your application server.

3. Apply Glue

The final step is a bit of handwork. We need to manually register the new service to the tunnel-web application. Open the server-config.wsdd located in the deploy directory/tunnel-web/WEB-INF folder of your application server. Add the following code just above the end of the XML:

<service name="Portlet_DevAtWork_HelloWorldService" provider="java:RPC" style="rpc" use="encoded">
	<parameter name="wsdlTargetNamespace" value="urn:http.service.world.hello.devatwork.nl"/>
	<parameter name="wsdlServiceElement" value="HelloWorldServiceSoapService"/>
	<parameter name="wsdlServicePort" value="Portlet_DevAtWork_HelloWorldService"/>
	<parameter name="className" value="nl.devatwork.hello.world.service.http.HelloWorldServiceSoap"/>
	<parameter name="wsdlPortType" value="HelloWorldServiceSoap"/>
	<parameter name="typeMappingVersion" value="1.2"/>
	<operation xmlns:operNS="urn:http.service.world.hello.devatwork.nl" name="sayHello" qname="operNS:sayHello" soapAction="">
		<parameter xmlns:tns="http://www.w3.org/2001/XMLSchema" qname="name" type="tns:string"></parameter>
	</operation>
	<parameter name="allowedMethods" value="sayHello"/>
</service>

This will register our service within tunnel-web.

Start your application server and navigate to http://127.0.0.1:8080/tunnel-web/axis. Here you will find a list of all the services currently exposed by Liferay. In the list you will find our service (Portlet_DevAtWork_HelloWorldService). You can view the WSDL by clicking on the link behind the service.

That wasn’t to bad now was it? If you are to lazy to copy the code you can download the complete project here.

I hope you learned how you can expose services as web services in Liferay. In the upcoming article I will show you how you can add security to the web service.

That is it for now. Let me know if you have any comments or questions.

In this article we will build a simple hello world service, nothing to fancy (I want to leave something for you to do yourself ). We will code the service from scratch without using tools like service builder.

The project will contain 3 modules:

1. A library containing the service contract
2. A web application implementing the service contract
3. A web application consuming the service

I hope you like this article, please let me know if you have any questions or comments. Lets get started. I assume you have read my previous article about using Maven to build Liferay applications. If not please read it first.

0. Project Setup

Please download and unzip the empty project and load it into an IDE of choice or use the command shell if you want. The project contains empty files. Please familiarizes yourself with the project structure and notice the dependencies in the different pom.xml files. Nothing special going on though.

1. Service Contract

This library contains the code contract of our HelloWorld service and a utility class which will provide easy access for non Spring portlets. Lets first set up our service contract, copy he following code into HelloWorldService.java:

package nl.devatwork.hello.world.service;

public interface HelloWorldService {
    String sayHello(String name);
}

That wasn’t so bad now was it? I think you have written more complex service contracts .

Lets implement the access utility class. Copy the following code into HelloWorldServiceUtil.java:

package nl.devatwork.hello.world.service;

public class HelloWorldServiceUtil {
    private static HelloWorldService _service;

    public static HelloWorldService getService() {
        if (_service == null) {
            throw new RuntimeException("HelloWorldService is not set");
        }

        return _service;
    }

    public void setService(HelloWorldService service) {
        _service = service;
    }

    public static String sayHello(String name) {
        return getService().sayHello(name);
    }
}

Again a really simple class. It has a getter and a setter which will be used to inject our service instance into this utility class. The static sayHello method is a proxies the service method.

You can build the service contract library by executing the following command in the /hello-world-service/ folder:

mvn clean package

Copy the resulting JAR file (/hello-world-service/target/hello-world-service-1.0.0-SNAPSHOT.jar) to the /lib/ext folder of your application server. You have to do this in order to avoid class loader issues. We will use this library later.

2. Service Implementation

Now we will implement the service in a self contained web application.  This application can be deployed using the auto deploy mechanism of your application server.

Lets implement the base class for our service implementation which implements the required plumbing. Copy the following code into HelloWorldServiceBaseImpl.java:

package nl.devatwork.hello.world.service.base;

import com.liferay.portal.SystemException;
import com.liferay.portal.kernel.annotation.BeanReference;
import com.liferay.portal.service.base.PrincipalBean;
import com.liferay.portal.util.PortalUtil;
import nl.devatwork.hello.world.service.HelloWorldService;

public abstract class HelloWorldServiceBaseImpl extends PrincipalBean implements HelloWorldService {
    @BeanReference(name = "nl.devatwork.hello.world.service.HelloWorldService.impl")
    protected HelloWorldService helloWorldService;

    public HelloWorldService getHelloWorldService() {
        return helloWorldService;
    }

    public void setHelloWorldService(HelloWorldService helloWorldService) {
        this.helloWorldService = helloWorldService;
    }

    protected void runSQL(String sql) throws SystemException {
        try {
            PortalUtil.runSQL(sql);
        } catch (Exception e) {
            throw new SystemException(e);
        }
    }
}

Now that we have the plumbing in place lets concentrate on our state of the art business logic. Copy the following code into HelloWorldServiceImpl.java:

package nl.devatwork.hello.world.service.impl;

import nl.devatwork.hello.world.service.base.HelloWorldServiceBaseImpl;

public class HelloWorldServiceImpl extends HelloWorldServiceBaseImpl {
    public String sayHello(String name) {
        return "Hello, " + name;
    }
}

Very exiting business logic isn’t it? .

Ok, now that we have our code in place lets apply some glue to make it all work. Copy the following content to service.properties:

##
## Properties Override
##

    #
    # Specify where to get the overridden properties. Updates should not be made
    # on this file but on the overridden version of this file.
    #
    include-and-override=service-ext.properties

##
## Build
##

    build.namespace=DevAtWork
    build.number=1
    build.date=1269952033689
    build.auto.upgrade=true

##
## Spring
##

    #
    # Input a list of comma delimited Spring configurations. These will be
    # loaded after the bean definitions specified in the
	# portalContextConfigLocation parameter in web.xml.
    #
    spring.configs=\
        WEB-INF/classes/META-INF/portlet-spring.xml

Notice the last two lines. This tells Liferay to load our Spring configuration.

Lets create our Spring configuration now. Copy the following code to portlet-spring.xml:

<?xml version="1.0" encoding="UTF-8"?>

<beans xmlns="http://www.springframework.org/schema/beans" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" default-init-method="afterPropertiesSet" xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-2.5.xsd">
    <bean id="nl.devatwork.hello.world.service.HelloWorldService.impl" class="nl.devatwork.hello.world.service.impl.HelloWorldServiceImpl"/>
    <bean id="nl.devatwork.hello.world.service.HelloWorldServiceUtil" class="nl.devatwork.hello.world.service.HelloWorldServiceUtil">
        <property name="service" ref="nl.devatwork.hello.world.service.HelloWorldService.impl"/>
    </bean>
</beans>

We register two beans into the Spring container. One for our service implementation instance and one for our service util.

Lets add the following code to web.xml:

<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns="http://java.sun.com/xml/ns/j2ee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd" version="2.4">

    <listener>
        <listener-class>com.liferay.portal.kernel.spring.context.PortletContextLoaderListener</listener-class>
    </listener>

</web-app>

This will load the Spring configuration for us.

Add the following code to liferay-plugin-package.properties:

name=Hello World Service Implementation
module-group-id=nl.devatwork.service.impl
module-incremental-version=1
short-description=
change-log=
page-url=http://www.devatwork.nl
author=Dev @ Work
licenses=Free

portal-dependency-jars=hello-world-service-1.0.0-SNAPSHOT.jar

Notice that we declare a dependency on the library we deployed earlier. Liferay will load the library on our class path.

We are ready with the service implementation now. You can build the service implementation by executing the following command in the /hello-world-service-impl/ folder:

mvn clean package

Copy the resulting WAR file (/hello-world-service-impl/target/hello-world-service-impl-1.0.0-SNAPSHOT.war to the auto deploy folder of your application server. The service implementation will be installed now.

3. Consumer Implementation

Now that we have the service contract and implementation in place lets create a portlet which consumes the service.

Copy the following code into SayHelloPortlet.java:

package nl.devatwork.hello.world.portlets;

import nl.devatwork.hello.world.service.HelloWorldServiceUtil;

import javax.portlet.GenericPortlet;
import javax.portlet.PortletException;
import javax.portlet.RenderRequest;
import javax.portlet.RenderResponse;

public class SayHelloPortlet extends GenericPortlet {
    public void doView(RenderRequest request, RenderResponse response) throws PortletException, java.io.IOException {
        String msg = HelloWorldServiceUtil.sayHello("Liferay Dev");
        response.setContentType("text/html");
        response.getWriter().print(msg);
    }
}

Copy the following code to portlet.xml:

<?xml version="1.0" encoding="UTF-8"?>
<portlet-app xmlns="http://java.sun.com/xml/ns/portlet/portlet-app_2_0.xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" version="2.0"
             xsi:schemaLocation="http://java.sun.com/xml/ns/portlet/portlet-app_2_0.xsd http://java.sun.com/xml/ns/portlet/portlet-app_2_0.xsd">

    <portlet>
        <portlet-name>SayHelloPortlet</portlet-name>
        <display-name>Say Hello Portlet</display-name>
        <portlet-class>nl.devatwork.hello.world.portlets.SayHelloPortlet</portlet-class>
        <expiration-cache>0</expiration-cache>
        <supports>
            <mime-type>text/html</mime-type>
            <portlet-mode>view</portlet-mode>
        </supports>
        <portlet-info>
            <title>Say Hello Portlet</title>
            <short-title>Say Hello Portlet</short-title>
            <keywords>DevAtWork</keywords>
        </portlet-info>
    </portlet>

</portlet-app>

Copy the following code to liferay-plugin-package.properties:

name=Hello World Portlets
module-group-id=nl.devatwork.portlets
module-incremental-version=1
short-description=
change-log=
page-url=http://www.devatwork.nl
author=Dev @ Work
licenses=Free

portal-dependency-jars=hello-world-service-1.0.0-SNAPSHOT.jar

Copy the following code to web.xml:

<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns="http://java.sun.com/xml/ns/j2ee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd" version="2.4">
</web-app>

We are ready with the consumer implementation now. You can build the portlet by executing the following command in the /hello-world-portlets/ folder:

mvn clean package

Copy the resulting WAR file (/hello-world-portlets/target/hello-world-portlets-1.0.0-SNAPSHOT.war to the auto deploy folder of your application server. The portlet will be installed now. Add the new portlet to a page and if everything works well then it should display the message: ‘Hello, Liferay Dev’.

You can download the complete project here.

That is it for this article, I hope you enjoyed reading it and that you learned something. If you have any questions or comments please post a comment and I will get back to you as soon as I can. In the next article I will show you how you can expose the HelloWorld service as a web service so it can be consumed by external applications.

The next version of Liferay, release date end Q1 begin Q2, will have complete support for maven including custom archetypes. Some of the steps described in this article will be obsolete then, but lets get started.

Installing Maven

The first step is to actually install Maven. You can find the download and installation instructions on the Maven website http://maven.apache.org/. Confirm that Maven is installed properly by executing the following command:

mvn --version

You should see the Maven version number.

Installing the Liferay dependencies into your local Maven repository

The next step is to install the Liferay portal-kernel and portal-service into your local repository. This manual step is required in order for Maven to resolve the Liferay portal dependencies. Navigate the ‘%JBOSS_HOME%/server/default/lib/ext’ folder where the JARs are located. Execute the following commands:

mvn install:install-file -Dfile="portal-kernel.jar" -DgroupId="com.liferay.portal" -DartifactId="portal-kernel" -Dversion="5.2.3-RELEASE" -Dpackaging=jar
mvn install:install-file -Dfile="portal-service.jar" -DgroupId="com.liferay.portal" -DartifactId="portal-service" -Dversion="5.2.3-RELEASE" -Dpackaging=jar

Now that you have installed the required dependencies let set up a quick Hello World portlet using Maven.

Setting up the Hello World Portlet

Now that we have all the required dependencies installed in our local Maven repository we can start building an application. Download the complete source here. Create the following folder structure:

/pom.xml
/src/main/java/nl/devatwork/HelloWorldPortlet.java
/src/main/webapp/WEB-INF/portlet.xml
/src/main/webapp/WEB-INF/web.xml

First let set up the POM so our dependencies can be loaded. Notice that I have set the Liferay dependencies as being provided. Add the following code to the pom.xml file you have just created:

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <groupId>devatwork</groupId>
    <version>1.0.0-SNAPSHOT</version>
    <artifactId>maven-hello-world</artifactId>
    <packaging>war</packaging>
    <name>Maven Hello World Portlet</name>
    <dependencies>
        <!-- Java dependencies -->
        <dependency>
            <groupId>javax.portlet</groupId>
            <artifactId>portlet-api</artifactId>
            <version>2.0</version>
            <scope>provided</scope>
        </dependency>
        <!-- liferay dependencies -->
        <dependency>
            <groupId>com.liferay.portal</groupId>
            <artifactId>portal-service</artifactId>
            <version>5.2.3-RELEASE</version>
            <scope>provided</scope>
        </dependency>
        <dependency>
            <groupId>com.liferay.portal</groupId>
            <artifactId>portal-kernel</artifactId>
            <version>5.2.3-RELEASE</version>
            <scope>provided</scope>
        </dependency>
    </dependencies>
</project>

The portlet will be a very simple portlet. It will  print a string and the name of the current theme. Add the following code to the HelloWorldPortlet.java file:

package nl.devatwork;

import com.liferay.portal.kernel.util.WebKeys;
import com.liferay.portal.theme.ThemeDisplay;

import javax.portlet.GenericPortlet;
import javax.portlet.PortletException;
import javax.portlet.RenderRequest;
import javax.portlet.RenderResponse;

public class HelloWorldPortlet extends GenericPortlet {
    protected void doView(RenderRequest request, RenderResponse response) throws PortletException, java.io.IOException {
        ThemeDisplay themeDisplay = (ThemeDisplay) request.getAttribute(WebKeys.THEME_DISPLAY);
        response.setContentType("text/html");
        response.getWriter().print("Hello World, " + themeDisplay.getTheme().getName());
    }
}

The next step is to set up the web.xml file, just copy the following code into it:

<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns="http://java.sun.com/xml/ns/j2ee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd" version="2.4">
</web-app>

The final step of this sample portlet is the portlet.xml, again really straight forward. Just copy in the following code:

<?xml version="1.0" encoding="UTF-8"?>
<portlet-app xmlns="http://java.sun.com/xml/ns/portlet/portlet-app_2_0.xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" version="2.0" xsi:schemaLocation="http://java.sun.com/xml/ns/portlet/portlet-app_2_0.xsd http://java.sun.com/xml/ns/portlet/portlet-app_2_0.xsd">
    <portlet>
        <portlet-name>HelloWorldPortlet</portlet-name>
        <display-name>Maven Hello World Portlet</display-name>
        <portlet-class>nl.devatwork.HelloWorldPortlet</portlet-class>
        <expiration-cache>0</expiration-cache>
        <supports>
            <mime-type>text/html</mime-type>
            <portlet-mode>view</portlet-mode>
        </supports>
    </portlet>
</portlet-app>

Now that the application is finished you can package it by executing the following command in the root of your application:

mvn clean package

Deploy the WAR to your application server and test it. Download the complete source here.

Now you are able to build Liferay plug-ins using Maven. I hope you liked this article. Please let me know if you have any questions or comments. Bye for now!

However, Liferay has a nice method of controlling the URL the portal generates for a portlet, the ‘FriendlyURLMapper‘. You can implement this interface, registerd it in the liferay-portlet.xml and you will have nice URLs. In the following example I will show how to implement it and what each individual method does.

I assume you have installed Liferay and the plugin SDK and that you know how to develop Liferay portlets.

The first step is to create a new class which will implement the ‘FriendlyURLMapper‘ interface. To make things easies we will derive that class from ‘BaseFriendlyURLMapper‘. You have to implement several methods yourself but don’t worry I will show you how.

The getMapping method

The ‘getMapping‘ method must return an identifier for the mapping. The mapping identifier is used by Liferay to map URLs to instances of the ‘FriendlyURLMapper‘. For example Liferay will resolve the following URL ‘/seoPortlet/123/view’ to a ‘FriendlyURLMapper‘ instance with mapping ‘seoPortlet‘. You can choose whatever mapping you want, just make sure your custom URLs always start with the mapping identifier.

To implement the ‘getMapping‘ method just return an unique identifier for the URL mapper.

public String getMapping() {
    return "seoPortlet";
}

The buildPath method

The ‘buildPath‘ method builds the actual URL. Here you implement the URL generation logic. You have access to the ‘LiferayPortletURL‘ object for which the URL is generated. You can extract the portletId, parameters, window state, etc. from it. The method should return a string containing the friendly URL for that particular portletURL, when the method returns null the default portletURL is used.

For each parameter (p_p_id for example) you move from the query string to the URL, you need to call ‘portletURL.addParameterIncludedInPath(“p_p_id”)‘. This will tell Liferay to not include the parameter in the query string. Parameters who are not marked as ‘included in path’ will be added to the query string automatically by Liferay.

Here is an example which maps URLs with a parameter named event to a friendly URL.

public String buildPath(final LiferayPortletURL portletURL) {
    String friendlyURLPath = null;

    // get the value
    final String portletId = portletURL.getPortletId();
    final String eventName = GetterUtil.getString(portletURL.getParameter("event"));

    if (Validator.isNotNull(portletId) && Validator.isNotNull(eventName)) {
        friendlyURLPath = StringPool.FORWARD_SLASH + "seoPortlet"+ StringPool.FORWARD_SLASH + portletId + StringPool.FORWARD_SLASH + eventName;
        portletURL.addParameterIncludedInPath("event");
    }

    // add other pararmeters
    if (Validator.isNotNull(friendlyURLPath)) {
        portletURL.addParameterIncludedInPath("p_p_id");
    }

    return friendlyURLPath;
}

Notice that we are including the mapping prefix ‘seoPortlet’ and that we are excluding the ‘p_p_id’ and ‘event’ parameters from the URL.

The getPortletId method

This method is used by the ‘BaseFriendlyURLMapper‘ super class to retrieve the portlet id. This will be used by ‘populateParams‘ method.

To implement the ‘getPortletId‘ method just return the value of a backing field with the name portletId. See example:

private String portletId;
public String getPortletId() {
    return portletId;
}

The populateParams method

This method will be called by Liferay each time a request is made with the mapping identifier in the URL. This method is responsible for mapping the parameters we removed from the query string and added to the path back to parameters: reversing the work we did in the ‘buildPath’ method.

Here is an example implementation.

public void populateParams(final String friendlyURLPath, final Map<String, String[]> params) {
    // get the values
    final String[] parts = StringUtil.split(friendlyURLPath, StringPool.SLASH);
    portletId = parts[2];
    final String event = parts[3];
    final String namespace = getNamespace();

    params.put("p_p_id", new String[]{portletId});
    params.put("p_p_state", new String[]{WindowState.NORMAL.toString()});
    params.put(namespace + "event", new String[]{event});
}

The method takes apart the ‘friendlyURLPath‘ and assembles parameters from it’s parts. Notice that in order to avoid parameter clashes between portlets the event parameter is prefixed with the portlet namespace, generated by the ‘BaseFriendlyURLMapper”s ‘getNamespace‘ method. The ‘getNamespace‘ method consumes the portletId using the ‘getPortletId‘ method.

liferay-portlet.xml

Now that the mapper is finished we need to tell Liferay to start using it. Add the friendly-url-mapper-class declaration to the portlet declaration and set its content to point to the class you just wrote:

<friendly-url-mapper-class>com.sample.FriendlyURLMapper</friendly-url-mapper-class>

That is it, know you can assemble your own FriendlyURLMapper now. I hope this article was useful to you. Please let me know if you have any questions or comments.

A quick summary of what we have learned during this course:

• Setting up Liferay, the plugin SDK and the Ext environment (allows you to customize the Liferay core)
• Setting up MySQL for Liferay
• Setting up a basic portlet
• Setting up a Liferay entity & service, a portlet which consumes it and hook those two up including validation and localization
• Creating a hook
• Creating a theme
• And a lot more…

I think this will be the last update regarding the Frankfurt training.