Copyright © 2000, 2007 Liferay Inc.

<?xml version="1.0"?>
<!DOCTYPE liferay-portlet-app PUBLIC "-//Liferay//DTD Portlet Application 4.2.0//EN" "http://www.liferay.com/dtd/liferay-portlet-app_4_2_0.dtd">

<liferay-portlet-app>
	<portlet>
		<portlet-name>1</portlet-name>
		<struts-path>mail</struts-path>
		<preferences-unique-per-layout>false</preferences-unique-per-layout>
		<preferences-owned-by-group>false</preferences-owned-by-group>
		<use-default-template>false</use-default-template>
		<restore-current-view>false</restore-current-view>
		<maximize-edit>true</maximize-edit>
		<private-request-attributes>false</private-request-attributes>
		<render-weight>0</render-weight>
	</portlet>
...
</liferay-portlet-app>

<?xml version="1.0"?>
<!DOCTYPE liferay-portlet-app PUBLIC "-//Liferay//DTD Portlet Application 4.2.0//EN" "http://www.liferay.com/dtd/liferay-portlet-app_4_2_0.dtd">

<liferay-portlet-app>
...
	<role-mapper>
		<role-name>user</role-name>
		<role-link>User</role-link>
	</role-mapper>
	<custom-user-attribute>
		<name>user.name.random</name>
		<custom-class>com.liferay.portlet.CustomUserAttributes</custom-class>
	</custom-user-attribute>
</liferay-portlet-app>

<display>
	<category name="category.admin">
		<portlet id="9" />
		<portlet id="40" />
		<portlet id="79" />
		<portlet id="80" />
	</category>
	<category name="category.cms">
		<category name="category.alfresco">
			<portlet id="91" />
		</category>
	</category>
...
<display>

Chapter 3. Liferay Portlet Frameworks

Table of Contents

1. Writing a Simple JSPPortlet

2. StrutsPortlet Tutorial

2.1. Writting a Very Simple Struts Portlet

2.2. Adding an action

2.3. Conclusion

In the next sections, you will learn how to develop a JSR 168 portlet leveraging two frameworks offered by Liferay to make deployment easier. First you will also learn how to create a simple JSPPortlet before moving on to the more complicated StrutsPortlet.

Both of these frameworks are available through the extension environment, so the rest of this section will assume that you already have it installed in a directory called ext. If you need more information about the extension environment, please read the Liferay Portal 4 – Development in the Extension Environment guide.

Note that by using these portlet frameworks your portlets will only work in Liferay Portal but not in other JSR-168 compliant portlets. Use them also if you need to speed your development and do not plan to deploy your portlets in other portal in the near term.

1. Writing a Simple JSPPortlet

Although a JSPPortlet does little more than display content, there is still some work that needs to be done. Let’s start by creating a new directory called myjspportlet within ext\ext-web\docroot\html\portlet\ext Next, open portlet-ext.xml within ext\ext-web\docroot\WEB-INF\.

	Note
	If you are using Eclipse, you may need to associate .xml files to Eclipse if your .xml files are being opened in a separate editor. You can do this by selecting Window from the menu bar and then Preferences. Expand the Workbench navigation, and click on File Associations. From there you can add *.xml as a new File type and associate it to open in Eclipse.

Notice how the portlets are uniquely identified by their portlet-name (also referred within Liferay Portal as the portlet id). As such, you will want to create a new portlet that is an increment of the portlet name, such as EXT_2. Since we are creating a JSPPortlet, you will want the portlet-class to reference the full class name: com.liferay.portlet.JSPPortlet. For this tutorial, add the following to your portlet-ext.xml (you may find it easier to copy and paste EXT_1 and just make the necessary changes):

<portlet>
  <portlet-name>EXT_2</portlet-name>
  <display-name>My JSPPortlet</display-name>
  <portlet-class>com.liferay.portlet.JSPPortlet</portlet-class>
  <init-param>
    <name>view-jsp</name>
    <value>/portlet/ext/myjspportlet/view.jsp</value>
  </init-param>
  <expiration-cache>300</expiration-cache>
  <supports>
    <mime-type>text/html</mime-type>
  </supports>
  <portlet-info>
    <title>My JSP Portlet</title>
  </portlet-info>
  <security-role-ref>
    <role-name>Power User</role-name>
  </security-role-ref>
  <security-role-ref>
    <role-name>User</role-name>
  </security-role-ref>
</portlet>

Here is a basic summary of what each of the elements represents:

portlet-name	The portlet-name element contains the canonical name of the portlet. Each portlet name is unique within the portlet application.
display-name	The display-name type contains a short name that is intended to be displayed by tools. It is used by display-name elements. The display name need not be unique.
portlet-class	The portlet-class element contains the fully qualified class name of the portlet.
init-param	The init-param element contains a name/value pair as an initialization param of the portlet.
expiration-cache	Expiration-cache defines expiration-based caching for this portlet. The parameter indicates the time in seconds after which the portlet output expires. -1 indicates that the output never expires.
supports	The supports element contains the supported mime-type. Supports also indicates the portlet modes a portlet supports for a specific content type. All portlets must support the view mode.
portlet-info	Portlet-info defines portlet information.
security-role-ref	The security-role-ref element contains the declaration of a security role reference in the code of the web application. Specifically in Liferay, the role-name references which role’s can access the portlet. (A Power User can personalize the portal, whereas a User cannot.)

Now that you have configured your portlet-ext.xml, the next step is to create the jsp pages. Within your /myjspportlet directory, add a file called init.jsp. Within this file, add the following two lines of code:

<%@ include file="/html/common/init.jsp" %>
<portlet:defineObjects />

These two lines import all the common class files and also set common variables used by each portlet. If you need to import portlet specific classes or initialize portlet specific variables, be sure to add them to their directory specific init.jsp, as opposed to the common/init.jsp.

These two lines import all the common class files and also set common variables used by each portlet. If you need to import portlet specific classes or initialize portlet specific variables, be sure to add them to their directory specific init.jsp, as opposed to the common/init.jsp.

Now, add a view.jsp. This jsp file will hold the content of your JSPPortlet. Write “Hello [your name here]‿ within the jsp. So the question is then, how does the portal know how to load these particular files? If you look back at the portlet element that was added within portlet-ext.xml, you will notice that you initialized a view-jsp parameter as having the value /ext/myjspportlet/view.jsp. By specifying this init-param, you are giving the portlet a default jsp to load.

Finally, in order to be able to add your portlet to the portal, you need to define the name within Language-ext.properties by adding the following line:

javax.portlet.title.EXT_2=My JSP Portlet

Since you have setup the Extension Environment, you need to deploy the changes you have made to your application server by running ant deploy from the ext directory.

	Note
	Eclipse users may use the Ant view to run ant commands. In this case just double click the deploy [default].

Start Tomcat again as soon as the deployment finishes. Browse to the Home tab of the portal, and in the Add Portlet to Wide Column dropdown add “My JSP Portlet‿ to your portal.

2. StrutsPortlet Tutorial

This section will take you through an example-driven tutorial on how to develop a StrutsPortlet. It is assumed that you have an extension environment installed in a directory called ext. It is also assumed that you will be using Tomcat as the application server.

2.1. Writting a Very Simple Struts Portlet

The goal of this section is to create a Struts Portlet within Liferay.

1. Define the portlet
   • portlet-ext.xml
   • liferay-portlet-ext.xml
2. Define the page flow and layout
   • struts-config.xml
   • tiles-defs.xml
3. Create the JSP
   • view.jsp

Key Concepts

What are the main differences between a JSP Portlet and a Struts Portlet?

• struts-config.xml
• tiles-defs.xml

Instead of forwarding directly to a JSP

• struts-config.xml – define the page flow
• tiles-defs.xml – define the page layout

Why Use Struts?

• Struts implements MVC. Although there are other frameworks that implement MVC, Struts is the most widely used and mature technology.
• What is MVC? MVC separates the presentation code from the business logic code.
• Struts provides centralized page-flow management in the form of struts-config.xml. This makes it highly scalable and allows you to modularize the coding process.
• By using Struts, you will be using a number of best practices that have been built into the framework.

Why Use Tiles?

A page layout is typically designed using include statements. If there are 100 JSPs and the header and footer need to be swapped, all 100 JSPs need to be changed. With Tiles, a single template can be used to determine the page layout. Only the template needs to be changed, and all the pages will be updated accordingly.

High Level Overview

• A URL or URI is passed to the Controller.
• The Controller determines what page should be displayed.
  

Example:

How does Liferay determine which JSP is displayed first?

• Our starting point is portlet-ext.xml view-action
• Controller MainServlet.java
  

Detailed View:

Directory Structure

Configuration files are located in this directory: …\ext\ext-web\docroot\WEB-INF

JSPs will be placed in this directory: …\ext\ext-web\docroot\html\portlet\ext

Portlet Definition

Add the following portlet definition to the portlet-ext.xml file:

<portlet>
	<portlet-name>EXT_4</portlet-name>
	<display-name>Library Portlet</display-name>
	<portlet-class>com.liferay.portlet.StrutsPortlet</portlet-class>
	<init-param>
		<name>view-action</name>
		<value>/ext/library/view</value>
	</init-param>
	<expiration-cache>0</expiration-cache>
<supports>
		<mime-type>text/html</mime-type>
	</supports>
	<resource-bundle>com.liferay.portlet.StrutsResourceBundle</resource-bundle>
	<security-role-ref>
		<role-name>power-user</role-name>
	</security-role-ref>
	<security-role-ref>
		<role-name>user</role-name>
	</security-role-ref>
</portlet>

Next add the following Liferay specific info to liferay-portlet-ext.xml:

<portlet>
	<portlet-name>EXT_4</portlet-name>
	<struts-path>ext/library</struts-path>
	<use-default-template>false</use-default-template>
</portlet>

• The struts-path is used to implement security.
• http://localhost:8080/c/portal/layout?p_l_id=PRI.15.1&p_p_id=EXT_4&p_p_action=1&p_p_state=maximized&p_p_mode=view&p_p_col_id=column-1&p_p_col_pos=5&p_p_col_count=6&_EXT_4_struts_action=%2Fext%2Flibrary%2Fview
• struts_action=“/ext/library/view”

struts-config.xml

struts-config.xml defines the page flow

<action path="/ext/library/view" forward="portlet.ext.library.view" />

What is /ext/library/view?

portlet-ext.xml:

<init-param>
	<name>view-action</name>
	<value>/ext/library/view</value>
</init-param>

What is portlet.ext.library.view?

It is the forward that is used to look up the tiles definition.

tiles-defs.xml

tiles-defs.xml defines the page layout

<definition name="portlet.ext.library" extends="portlet" />

<definition name="portlet.ext.library.view" extends="portlet.ext.library">
	<put name="portlet_content" value="/portlet/ext/library/view.jsp" />
</definition>

What is portlet.ext.library.view?

• From struts-config.xml

  <action path="/ext/library/view" forward="portlet.ext.library.view" />
  <definition name="portlet.ext.library" extends="portlet" />
  
  <definition name="portlet.ext.library.view" extends="portlet.ext.library">
  	<put name="portlet_content" value="/portlet/ext/library/view.jsp" />
  </definition>

What is /portlet/ext/library/view.jsp?

For reference: portlet-ext.xml from JSP Portlet Training

	<init-param>
		<name>view-jsp</name>
		<value>/portlet/ext/jsp_portlet/view.jsp</value>
	</init-param>

For the JSP Portlet, the JSP was pointed directly from portlet-ext.xml. For Struts portlets, this is done through tiles-defs.xml

<definition name="portlet.ext.library" extends="portlet" />

<definition name="portlet.ext.library.view" extends="portlet.ext.library">
	<put name="portlet_content" value="/portlet/ext/library/view.jsp" />
</definition>

What is portlet?

Portlet is the template that will be used (portlet.jsp). See …\portal\portal-web\docroot\WEB-INF\tiles-defs.xml for more information.

What is portlet.ext.library?

• portlet.ext.library extends portlet. This means that portlet.ext.library will use the portlet.jsp as its template.
• portlet.ext.library.view extends portlet.ext.library. This means that portlet.ext.library.view will also use portlet.jsp for its template.

Create the JSP

The next step is to create the JSP.

• Create a directory called library here: …\ext\ext-web\docroot\html\portlet\ext
• Your directory structure should now look like this: …\ext\ext-web\docroot\html\portlet\ext\library
• Create view.jsp in the library directory: …\ext\ext-web\docroot\html\portlet\ext\library\view.jsp
• Enter “Simple Struts Portlet!” in view.jsp

Deploy the Files to Tomcat

Once you have finished modifying all of the files, deploy them to Tomcat.

1. Open up a cmd prompt.
2. Click Start, Run, and then type cmd.
3. Navigate to your ext directory and then type ant deploy.
   • …\ext>ant deploy

Check the Tomcat Directory

Verify that the files were deployed to Tomcat.

1. Go to …\tomcat\webapps\ROOT\WEB-INF and open portlet-ext.xml, liferay-portlet-ext.xml, struts-config-ext.xml, and tiles-defs-ext.xml to check that the files were deployed correctly.
2. Go to …\tomcat\webapps\ROOT\html\portlet\ext\library and open up view.jsp to see that it was deployed correctly.

Final Steps

1. Restart Tomcat.
2. Open up a new browser and type:
   • http://localhost:8080
   • LOGIN: test@liferay.com
   • PASSWORD: test
3. Click Add Content>Undefined.
4. Click javax.portlet.title.EXT_4.

Key Concepts

Now that we’ve finished building the framework for our portlet, let’s move on to the next exercise. In this exercise, we will:

• Create a new file called init.jsp where we will add commonly used variables and declarations.
• Set the portlet title.
• Add the portlet to a category.

init.jsp

Create init.jsp in the library directory: …\ext\ext-web\docroot\html\portlet\ext\library\init.jsp

Enter the following in init.jsp:

	<%@ include file="/html/common/init.jsp" %>
	<p>Add commonly used variables and declarations here!</p>

What file are we including with this line?

	<%@ include file="/html/common/init.jsp" %>
…\portal\portal-web\docroot\html\common\init.jsp

This will gives us access to the Liferay tag libraries.

view.jsp

• Add this line above “Simple Struts Portlet!” in view.jsp:

  <%@ include file="/html/portlet/ext/library/init.jsp" %>
  	Simple Struts Portlet!

• This will give us access to the init.jsp located here:

  …\ext\ext-web\docroot\html\portlet\ext\library\init.jsp

• Ant deploy. You do not have to restart Tomcat.
• The following should now be displayed: Add commonly used variables and declarations here! Simple Struts Portlet

Set the Portlet Title

• Go to Language-ext.properties and add the following line:

  …\ext\ext-ejb\classes\content\Language-ext.properties

  javax.portlet.title.EXT_4=Library

• Ant deploy and Restart Tomcat.
• The portlet title will now be “Library.”

Add the Portlet to a Category

1. Go to liferay-display.xml and add the following line:

   …\ext\ext-web\docroot\WEB-INF\liferay-display.xml

   	<category name="category.test">
   		<portlet id=“EXT_3" />
   		<portlet id="EXT_4" />
   		...
   	</category>

2. You will now be able to select your portlet from the “Test” category.

Review of <struts-path>

<portlet>
	<portlet-name>EXT_4</portlet-name>
	<struts-path>ext/library</struts-path>
	<use-default-template>false</use-default-template>
</portlet>

Liferay will check the struts-path to check whether a user has the required roles to access the portlet.

Note: When you see the error message: You do not have the required roles to access this portlet.

1. Check to see that you have defined the roles correctly in portlet-ext.xml.
2. Check the <struts-path> to see if you have defined it correctly.

2.2. Adding an action

The goal of this section is to add an Action Class to the Struts Portlet and to display an success page.

1. Define the Action.
   • struts-config.xml
   • tiles-defs.xml
2. Update existing JSP files.
   • view.jsp
   • init.jsp
3. Create success and error JSP files.
   • error.jsp
   • Success.jsp
4. Create Action Class to process submit.
   • AddBookAction.java

Review Key Concepts

What are the main differences between a JSP Portlet and a Struts Portlet?

• JSP Portlet goes directly to a JSP
• Struts Portlet has an page flow

Where does the page flow get defined?

• struts-config.xml – define the page flow
• tiles-defs.xml – define the page layout

struts-config.xml

struts-config.xml defines the page flow

<action path="/ext/library/view" forward="portlet.ext.library.view" />

Lets add another path to the page flow

<action path="/ext/library/add_book" type="com.ext.portlet.library.action.AddBookAction">
	<forward name="portlet.ext.library.error" path="portlet.ext.library.error" />
	<forward name="portlet.ext.library.success" path="portlet.ext.library.success" />
</action>

What is type?

• Type is a Struts defined way of passing control to the AddBookAction class.

Lets look at the forward nodes:

<forward name="portlet.ext.library.error" path="portlet.ext.library.error" />
<forward name="portlet.ext.library.success" path="portlet.ext.library.success" />

What is name?

• It the unique identifier for that forward node.

What is path?

• This is your link to the tiles-def.xml.

tiles-defs.xml

tiles-defs.xml defines the page layout

<definition name="portlet.ext.library" extends="portlet" />

<definition name="portlet.ext.library.view" extends="portlet.ext.library">
	<put name="portlet_content" value="/portlet/ext/library/view.jsp" />
</definition>

Lets add the error and success paths

<definition name="portlet.ext.library.error" extends="portlet.ext.library">
	<put name="portlet_content" value="/portlet/ext/library/error.jsp" />
</definition>

<definition name="portlet.ext.library.success" extends="portlet.ext.library">
	<put name="portlet_content" value="/portlet/ext/library/success.jsp" />
</definition>

init.jsp

Update init.jsp in the library directory

…\ext\ext-web\docroot\html\portlet\ext\library\init.jsp

Remove the following:

<p>Add commonly used variables and declarations here!</p>

init.jsp should only contain this line:

<%@ include file="/html/common/init.jsp" %>

Review: What does including this file give us?

<%@ include file="/html/common/init.jsp" %>
…\portal\portal-web\docroot\html\common\init.jsp

This will give access to the Liferay tag libraries.

view.jsp

<%@ include file="/html/portlet/ext/library/init.jsp" %>

<br/>
Add a book entry to the Library:
<br/><br/>
<form action="<portlet:actionURL windowState="<%= WindowState.MAXIMIZED.toString() %>"><portlet:param name="struts_action" value="/ext/library/add_book" /></portlet:actionURL>" method="post" name="<portlet:namespace />fm">	

	Book Title:

	<input name="<portlet:namespace />book_title" size="20" type="text" value=""><br/><br/>

	<input type="button" value="Submit" onClick="submitForm(document.<portlet:namespace />fm);">
</form>
<br/>

What does “struts_action” do?

• Struts_action is the ActionMapping to the struts-config.xml path.

  <action path="/ext/library/add_book" type="com.ext.portlet.library.action.AddBookAction">

• value="/ext/library/add_book“
  • This is the link to the ActionPath.
• Review

  What does “struts_action” connect us to?

  It connects us to the struts-config.xml

error.jsp

• error.jspPath:

  ext-web/docroot/html/portlet/ext/library/error.jsp

• error.jsp Contents:

  ERROR!

success.jsp

• success.jsp Path:

  ext-web/docroot/html/portlet/ext/library/success.jsp

• success.jsp Contents:

  SUCCESS!

AddBookAction.java

• AddBookAction Class Path:

  ext/ext-ejb/src/com/ext/portlet/library/action/AddBookAction.java

• AddBookAction Class Contents:

  package com.ext.portlet.library.action;
  
  import javax.portlet.ActionRequest;
  import javax.portlet.ActionResponse;
  import javax.portlet.PortletConfig;
  import javax.portlet.RenderRequest;
  import javax.portlet.RenderResponse;
  
  import org.apache.struts.action.ActionForm;
  import org.apache.struts.action.ActionForward;
  import org.apache.struts.action.ActionMapping;
  public class AddBookAction extends PortletAction {
  public void processAction(
  			ActionMapping mapping, ActionForm form, PortletConfig config,
  			ActionRequest req, ActionResponse res)
  
  		throws Exception {
  
  		String bookTitle = req.getParameter("book_title");
  
  		if ( null == bookTitle || "".equals(bookTitle) ) {
  			setForward(req, "portlet.ext.library.error");
  		} else {
  			setForward(req, "portlet.ext.library.success");
  		}
  	}
  
  	public ActionForward render(ActionMapping mapping, ActionForm form,
  		PortletConfig config, RenderRequest req, RenderResponse res)
  		throws Exception {
  		if (getForward(req) != null && !getForward(req).equals("")) {
  			return mapping.findForward(getForward(req));
  		} else {
  			return mapping.findForward("portlet.ext.library.view");
  		}
  	}
  }

• Main code:

  String bookTitle = req.getParameter("book_title");
  
  if ( null == bookTitle || "".equals(bookTitle) ) {
  	setForward(req, "portlet.ext.library.error");
  } else {
  	setForward(req, "portlet.ext.library.success");
  }

• Where does “book_title” come from?

  It comes from to the view.jsp form.

• What is the if/else statement doing?
  • It is detecting if the book title was submitted.
  • According to the detected state, it sets the forward path.
• Error forward path:

  if ( null == bookTitle || "".equals(bookTitle) ) {
  	setForward(req, "portlet.ext.library.error");
  } else {
  	setForward(req, "portlet.ext.library.success");
  }

• Success forward path:

  if ( null == bookTitle || "".equals(bookTitle) ) {
  	setForward(req, "portlet.ext.library.error");
  } else {
  	setForward(req, "portlet.ext.library.success");
  }

• Error and Success forward path is linked to the the path in struts-config.xml:

  <forward name="portlet.ext.library.error" path="portlet.ext.library.error" />
  <forward name="portlet.ext.library.success" path="portlet.ext.library.success" />

Struts Action Mapping

Deploy the Files to Tomcat

Once you have finished modifying all of the files, deploy them to Tomcat.

1. Open up a cmd prompt.
   • Click Start>Run and then type cmd.
2. Navigate to your ext directory and then type ant deploy.
   • …\ext>ant deploy

Check the Tomcat Directory

Verify that the files were deployed to Tomcat

• Go to …\tomcat\webapps\ROOT\WEB-INF and open portlet-ext.xml, liferay-portlet-ext.xml, struts-config-ext.xml, and tiles-defs-ext.xml and check to see that the files were deployed correctly.
• Next, go to …\tomcat\webapps\ROOT\html\portlet\ext\library and open up view.jsp to see that it was deployed correctly.

Final Steps

1. Restart Tomcat
2. Open up a new browser and type:

   http://localhost:8080

   LOGIN: test@liferay.com

   PASSWORD: test

Key Concepts

Objectives

Now that we’ve finished redirecting with an action. Lets make the success page display the submitted value.

• Update success.jsp to display the submitted value.

success.jsp

success.jsp Path:

• ext-web/docroot/html/portlet/ext/library/success.jsp

success.jsp Contents:

<%@ include file="/html/portlet/ext/library/init.jsp" %>
<%
	String bookTitle = request.getParameter("book_title");
%>
<table align="center" cellspacing="10" cellpadding="3">
<tr>
	<td style="font-weight:bold">Book Title:</td>
	<td><%= bookTitle %></td>
</tr>
</table>

• Add init.jsp

  <%@ include file="/html/portlet/ext/library/init.jsp" %>

• This will give us access to the init.jsp located here:

  …\ext\ext-web\docroot\html\portlet\ext\library\init.jsp

• Get the submitted value

  String bookTitle = request.getParameter("book_title");

• Display the submitted value in success.jsp

  <%= bookTitle %>

Deploy the Files to Tomcat

Once you have finished modifying success.jsp, deploy it to Tomcat

1. Open up a cmd prompt.
   • Click Start>Run and then type cmd.
2. Navigate to your ext directory and then type ant deploy.
   • …\ext>ant deploy

2.3. Conclusion

You’ve learned how to create a StrutsPortlet using some of the patterns used to create the portlets bundled with Liferay. The next recommended steps are to read the code of those portlets and to look for more information about Struts itself.

	<target name="deploy">
		<java
			classname="com.liferay.portal.tools.PortletDeployer"
			classpathref="project.classpath"
			fork="true"
			newenvironment="true">

				<!-- Required Arguments -->

				<jvmarg value="-Ddeployer.base.dir=./" />
				<jvmarg value="-Ddeployer.dest.dir=${app.server.deploy.dir}" />
				<jvmarg value="-Ddeployer.app.server.type=${app.server.type}" />
				<jvmarg value="-Ddeployer.portlet.taglib.dtd=${project.dir}/web-sites/liferay.com-web/docroot/WEB-INF/tld/liferay-portlet.tld" />
				<jvmarg value="-Ddeployer.unpack.war=true" />

				<!-- Optional Arguments -->

				<jvmarg value="-Ddeployer.tomcat.lib.dir=${app.server.tomcat.lib.global.dir}" />

				<!-- Dependent Libraries -->

				<arg value="${project.dir}/lib/util-bridges.jar" />
				<arg value="${project.dir}/lib/util-java.jar" />
				<arg value="${project.dir}/web-sites/liferay.com-web/docroot/WEB-INF/lib/util-taglib.jar" />

				<!-- Specific WARs -->

				<arg line="${deploy.specific.wars}" />
		</java>
	</target>

Chapter 5. Liferay Services

Table of Contents

1. Security and Permissions Service

1.1. Introduction

1.2. Overview

1.3. Implementing Permissions

1.4. Summary

1.5. Information

2. User service

Portlet applications may invoke the services provided by Liferay Portal by using the portal-client.jar client library.

It is also possible to use Liferay Service Builder to develop your portlets using the same service oriented architecture that Liferay Portal is based on.

The following sections describe the most important services that can be used. Refer the documentation in the public Liferay wiki for more information

1. Security and Permissions Service

The Permissions service is provided by Liferay Portal to developers to write security related functionality in their own portlets. Currently this functionality is only provided for portlets developed within the Liferay sources or through the extension environment.

1.1. Introduction

Fine grain permissioning is one of the main new features of Liferay Portal 4. Developers can now implement access security into their custom portlets, giving administrators and users a lot more control over their portlets and contents. This document will provide a reference for implementing this new security feature into their custom portlets. Developers should first read the Security and Permissions section of the Liferay User Guide before continuing with this document.

1.2. Overview

Adding fine grain permissioning to custom portlets consists of four main steps (also known as DRAC):

1. Define all resources and their permissions.
2. For all the resources defined in step 1, register them into the permission system. This is also known simply as “adding resources.”
3. Associate the necessary permissions to these resources.
4. Check permission before returning resources.

1.3. Implementing Permissions

In this section, each of the four main steps in adding Liferay’s security feature into custom portlets (built on top of the Liferay portal) will be explained. The following are two definitions that are important to remember.

Resouce

A generic term for any object represented in the portal. Example of resources includes portlets (e.g., Message Boards, Calendar, etc.), Java classes (e.g., Message Board Topics, Calendar Events, etc.), and files (e.g., documents, images, etc.)

Permission

An action acting on a resource. For example, the view in “viewing the calendar portlet” is defined as a permission in Liferay.

Keep in mind that the permission for a portlet resource is implemented a little differently from the other resources such as Java classes and files. In each of the subsections below, the permission implementation for the portlet resource is explained first, then the model (and file) resource.

Defining Resources and Actions

For your custom portlet, Liferay portal needs to know whether there are resources that require permission and whether there are custom permissions. The default configuration is encapsulated in an XML file found in the portal/portal-ejb/classes/resource-actions directory, you might use it as a reference to create a similar file for your portlet. If your portlet only needs the view and the configuration permission, and that the portlet doesn’t use any models with permission, then you do not need to create this XML file. The reason is that all portlets in Liferay automatically inherit these permissions. However, if your portlet does have custom permission and/or uses models that have custom permissions, then you will need to create an XML file defining the resources and actions. Let’s take a look at blogs.xml in portal/portal-ejb/classes/resource-actions and see how the blogs portlet defined these resources and actions:

<?xml version="1.0"?>

<resource-action-mapping>
	<portlet-resource>
		<portlet-name>33</portlet-name>
		<supports>
			<action-key>ADD_ENTRY</action-key>
			<action-key>CONFIGURATION</action-key>
			<action-key>VIEW</action-key>
		</supports>
		<community-defaults>
			<action-key>VIEW</action-key>
		</community-defaults>
		<guest-defaults>
			<action-key>VIEW</action-key>
		</guest-defaults>
		<guest-unsupported>
			<action-key>ADD_ENTRY</action-key>
		</guest-unsupported>
	</portlet-resource>
	<model-resource>
		<model-name>com.liferay.portlet.blogs.model.BlogsCategory</model-name>
		<portlet-ref>
			<portlet-name>33</portlet-name>
		</portlet-ref>
		<supports>
			<action-key>DELETE</action-key>
			<action-key>PERMISSIONS</action-key>
			<action-key>UPDATE</action-key>
			<action-key>VIEW</action-key>
		</supports>
		<community-defaults>
			<action-key>VIEW</action-key>
		</community-defaults>
		<guest-defaults>
			<action-key>VIEW</action-key>
		</guest-defaults>
		<guest-unsupported>
			<action-key>UPDATE</action-key>
		</guest-unsupported>
	</model-resource>
	<model-resource>
		<model-name>com.liferay.portlet.blogs.model.BlogsEntry</model-name>
		<portlet-ref>
			<portlet-name>33</portlet-name>
		</portlet-ref>
		<supports>
			<action-key>ADD_COMMENT</action-key>
			<action-key>DELETE</action-key>
			<action-key>PERMISSIONS</action-key>
			<action-key>UPDATE</action-key>
			<action-key>VIEW</action-key>
		</supports>
		<community-defaults>
			<action-key>VIEW</action-key>
		</community-defaults>
		<guest-defaults>
			<action-key>VIEW</action-key>
		</guest-defaults>
		<guest-unsupported>
			<action-key>UPDATE</action-key>
		</guest-unsupported>
	</model-resource>
</resource-action-mapping>

Portlet Resource

In the XML, the first thing defined is the portlet itself. Right under the root element <resource-action-mapping>, we have a child element called <portlet-resource>. In this element, we define the portlet name, which is 33 in our case. Next, we list all the actions this portlet supports under the <supports> tag. Keep in mind that this is at the portlet level. To understand what should be listed here, developers should ask themselves what actions belong to the portlet itself or what actions are performed on the portlet that may require a security check. In our case, users need permission to add an entry (ADD_ENTRY), configure blogs portlet settings (CONFIGURATION), and view the blogs itself (VIEW). Each of these supported permissions is within its own <action-key> tag. After we’ve defined all the actions that require a check, we move on to define some of the default permission settings. The community-defaults tag defines what actions are permitted by default for this portlet on the community (group) page the portlet resides. Put it another way, what should a user that has access to the community this portlet resides be able to do minimally? For the blogs portlet, a user with access to the community containing the blogs portlet should be able to view it. Likewise, the guest-defaults tag defines what actions are permitted by default to guests visiting a layout containing this portlet. So if a guest has access to the community page that contains a blogs portlet, the guest should, at the very least, be able to view the portlet according to blogs.xml (not necessarily the content of the portlet). Otherwise, the guest will see an error message within the portlet. Depending on your custom portlet, you may add more actions here that make sense. The guest-unsupported tag contains actions that a visiting guest should never be able to do. For example, the guest visiting the blogs portlet should never be able to add a blog entry since the blog belongs to either a user or a group of users. So even if a user wants to grant guests the ability to add a blog entry to her blog, there is no way for her to grant that permission because the blogs.xml doesn’t permit such an action for guests.

Model Resource

After defining the portlet as a resource, we move on to define models within the portlet that also require access check. The model resource is surrounded by the <model-resource> tag. Within this tag, we first define the model name. This must be the fully qualified Java class name of the model. Next we define the portlet name that this model belongs to under the portlet-ref tag. Though unlikely, a model can belong to multiple portlets, which you may use multiple <portlet-name> tags to define. Similar to the portlet resource element, the model resource element also allows you to define a supported list of actions that require permission to perform. You must list out all the performable actions that require a permission check. As you can see for a blog entry, a user must have permission in order to add comments to an entry, delete an entry, change the permission setting of an entry, update an entry, or simply to view an entry. The <community-defaults> tag, the <guest-defaults> tag, and the <guest-unsupported> tag are all similar in meaning to what’s explained for portlet resource in section 3.1.1.

Default.xml

After defining your permission scheme for your custom portlet, you then need to tell Liferay the location of this file. For Liferay core, the XML file would normally reside in portal/portal-ejb/classes/resource-actions and a reference to the file would appear in the default.xml file. For the extension environment, the recommended setup is to put your XML file in ext/ext-ejb/classes/resource-actions. Create a file called default-ext.xml and model it after the default.xml file. Add all your custom resource-action XML files in the default-ext.xml file. Then copy the property resource.actions.configs found in portal.properties and paste it into portal-ext.properties. Lastly, add a comma to the end of the property value and then add the path to your default-ext.xml file. (i.e. resource.actions.configs=resource-actions/default.xml,resource-actions/default-ext.xml) Below is an example of the default.xml file.

<?xml version="1.0"?>

<resource-action-mapping>
	<resource file="resource-actions/portal.xml" />
	<resource file="resource-actions/blogs.xml" />
	<resource file="resource-actions/bookmarks.xml" />
	<resource file="resource-actions/calendar.xml" />
	<resource file="resource-actions/communities.xml" />
	<resource file="resource-actions/documentlibrary.xml" />
	<resource file="resource-actions/imagegallery.xml" />
	<resource file="resource-actions/journal.xml" />
	<resource file="resource-actions/messageboards.xml" />
	<resource file="resource-actions/polls.xml" />
	<resource file="resource-actions/shopping.xml" />
	<resource file="resource-actions/wiki.xml" />
</resource-action-mapping>

Adding Resources

After defining resources and actions, the next task is to write code that adds resources into the permissioning system. A lot of the logic to add resources is encapsulated in the ResourceLocalServiceImpl class. So adding resources is as easy as calling the add resource method in ResourceLocalServiceUtil class.

public void addResources(
	String companyId, String groupId, String userId, String name,
	String primKey, boolean portletActions,
	boolean addCommunityPermissions, boolean addGuestPermissions);

For all the Java objects that require access permission, you need to make sure that they are added as resources every time a new one is created. For example, every time a user adds a new entry to her blog, the addResources(…) method is called to add the new entry to the resource system. Here’s an example of the call from the BlogsEntryLocalServiceImpl class.

ResourceLocalServiceUtil.addResources(
	entry.getCompanyId(), entry.getGroupId(), entry.getUserId(),
	BlogsEntry.class.getName(), entry.getPrimaryKey().toString(),
	false, addCommunityPermissions, addGuestPermissions);

The parameters companyId, groupId, and userId should be self explanatory. The name parameter is the fully qualified Java class name for the resource object being added. The primKey parameter is the primary key of the resource object. As for the portletActions parameter, set this to true if you’re adding portlet action permissions. In our example, we set it to false because we’re adding a model resource, which should be associated with permissions related to the model action defined in blogs.xml. The addCommunityPermissions and the addGuestPermissions parameters are inputs from the user. If set to true, ResourceLocalService will then add the default permissions to the current community group and the guest group for this resource respectively.

UI Interface

If you would like to provide your user the ability to choose whether to add the default community permission and the guest permission for the resources within your custom portlet, Liferay has a custom JSP tag you may use to quickly add that functionality. Simply insert the <liferay-ui:input-permissions /> tag into the appropriate JSP and the checkboxes will show up on your JSP. Of course, make sure the tag is within the appropriate <form> tags.

Deleting Resources

To prevent having a lot of dead resources taking up space in the Resource_ database table, you must remember to remove them from the Resource_ table when the resource is no longer applicable. Simply call the deleteResource(…) method in ResourceLocalServiceUtil. Here’s an example of a blogs entry being removed:

ResourceLocalServiceUtil.deleteResource(
	entry.getCompanyId(), BlogsEntry.class.getName(),
	Resource.TYPE_CLASS, Resource.SCOPE_INDIVIDUAL,
	entry.getPrimaryKey().toString());

Adding Permission

Portlet Permission

On the portlet level, no code needs to be written in order to have the permission system work for your custom portlet. Your custom portlet will automatically have all the permission features. If you’ve defined any custom permissions (supported actions) in your portlet-resource tag in section 3.1, those are automatically added to a list of permissions and users can readily choose them. Of course, for your custom permissions to have any value, you’ll need to show or hide certain functionality in your portlet. You can do that by checking the permission first before performing the intended functionality. This will be covered in section 3.4.

Model Permission

In order to allow a user to set permissions on the model resources, you will need to expose the permission interface to the user. This can be done by adding two Liferay UI tag to your JSP. The first one is the <liferay-security:permissionsURL> tag which returns a URL that takes the user to the page to configure the permission settings. The second tag is the <liferay-ui:icon> tag that shows a permission icon to the user. Below is an example found in the file view_entry_content.jsp.

<liferay-security:permissionsURL
	modelResource="<%= BlogsEntry.class.getName() %>"
	modelResourceDescription="<%= entry.getTitle() %>"
	resourcePrimKey="<%= entry.getPrimaryKey().toString() %>"
	var="entryURL"
/>

<liferay-ui:icon image="permissions" url="<%= entryURL %>" />

The attributes you need to provide to the first tag are modelResource, modelResourceDescription, resourcePrimKey, and var. The modelResource attribute is the fully qualified Java object class name. It then gets translated in Language.properties to a more readable name (underlined in red in figure 3.3.2.1).

model.resource.com.liferay.portlet.blogs.model.BlogsEntry=Entry

As for the modelResourceDescription attribute, you can pass in anything that best describes this model instance. In the example, the blogs title was passed in, which is reflected in figure 3.3.2.1 with the blue underline. The resourcePrimKey attribute is simply the primary key of your model instance. The var attribute is the variable name this URL String will get assigned to. This variable is then passed to the <liferay-ui:icon> tag so the permission icon will have the proper URL link. There’s also an optional attribute redirect that’s available if you want to override the default behavior of the upper right arrow link shown in figure 3.3.2.1. That is all you need to do to enable users to configure the permission settings for model resources!!

Checking Permissions

The last major step to implementing permission to your custom portlet is to check permission. This may be done in a couple of places. For example, your business layer should check for permission before deleting a resource, or your user interface should hide a button that adds a model (e.g., a calendar event) if the user does not have permission to do so.

Checking Portlet Resource Permission

Similar to the other steps, the default permissions for the portlet resources are automatically checked for you. You do not need to implement anything for your portlet to discriminate whether a user is allowed to view or to configure the portlet itself. However, you do need to implement any custom permission you have defined in your resource-actions XML file. In the blogs portlet example, one custom supported action is ADD_ENTRY. There are two places in the source code that check for this permission. The first one is in the file view_entries.jsp. The presence of the add entry button is contingent on whether the user has permission to add entry (and also whether the user is in tab one).

<%
boolean showAddEntryButton = tabs1.equals("entries") && PortletPermission.contains(permissionChecker, plid, PortletKeys.BLOGS, ActionKeys.ADD_ENTRY);
%>

The second place that checks for the add entry permission is in the file BlogsEntryServiceImpl. (Notice the difference between this file and the BlogsEntryLocalServiceImpl.) In the addEntry(…) method, a call is made to check whether the incoming request has permission to add entry.

PortletPermission.check(
	getPermissionChecker(), plid, PortletKeys.BLOGS,
	ActionKeys.ADD_ENTRY);

If the check fails, it throws a PrincipalException and the add entry request aborts. You’re probably wondering what the PortletPermission class and the PermissionChecker class do. Let’s take a look at these two classes.

PermissionChecker

The PermissionChecker class has a method called hasPermission(…) that checks whether a user making a resource request has the necessary access permission. If the user is not signed in (guest user), it checks for guest permissions. Otherwise, it checks for user permissions. This class is available to you in two places. First in your business logic layer, you can obtain an instance of the PermissionChecker by calling the getPermissionChecker() method inside your ServiceImpl class. This method is available because all ServiceImpl (not LocalServiceImpl) extends the PrincipalBean class, which implements the getPermissionChecker() method. The other place where you can obtain an instance of the PermissionChecker class is in your JSP files. If your JSP file contains the portlet tag <portlet:defineObjects /> or includes another JSP file that does, you’ll have an instance of the PermissionChecker class available to you via the permissionChecker variable. Now that you know what the PermissionChecker does and how to obtain an instance of it, let’s take a look at Liferay’s convention in using it.

PortletPermission

PortletPermission is a helper class that makes it easy for you to check permission on portlet resources (as oppose to model resources, covered later in section 3.4.2). It has two static methods called check(…) and another two called contains(…). They are all essentially the same. The two differences between them are:

1. Only one check(…) method and one contains(…) method take in the portlet layout ID variable (plid).
2. The check(…) methods throw a new PrincipalException if user does not have permission, and the contains(…) methods return a boolean indicating whether user has permission.

The contains(…) methods are meant to be used in your JSP files since they return a boolean instead of throwing an exception. The check(…) methods are meant to be called in your business layer (ServiceImpl). Let’s revisit the blogs portlet example below. (The addEntry(…) method is found in BlogsEntryServiceImpl.)

public BlogsEntry addEntry(
		String plid, String categoryId, String[] tags, String title,
		String content, int displayDateMonth, int displayDateDay,
		int displayDateYear, int displayDateHour, int displayDateMinute,
		boolean addCommunityPermissions, boolean addGuestPermissions)
throws PortalException, SystemException {

	PortletPermission.check(
		getPermissionChecker(), plid, PortletKeys.BLOGS,
		ActionKeys.ADD_ENTRY);

	return BlogsEntryLocalServiceUtil.addEntry(
		getUserId(), plid, categoryId, tags, title, content,
		displayDateMonth, displayDateDay, displayDateYear, displayDateHour,
		displayDateMinute, addCommunityPermissions, addGuestPermissions);
}

Before the addEntry(…) method calls BlogsEntryLocalServiceUtil.addEntry(…) to add a blogs entry, it calls PortletPermission.check(…) to validate user permission. If the check fails, a PrincipalException is thrown and an entry will not be added. Note the parameters passed into the method. Again, the getPermissionChecker() method is readily available in all ServiceImpl classes. The plid variable is passed into the method by its caller (most likely from a PortletAction class). PortletKeys.BLOGS is just a static String indicating that the permission check is against the blogs portlet. ActionKeys.ADD_ENTRY is also a static String to indicate the action requiring the permission check. You’re encouraged to do likewise with your custom portlet names and custom action keys.

Whether you need to pass in a portlet layout ID (plid) depends on whether your custom portlet supports multiple instances. Let’s take a look at the message board portlet for example. A community may need three separate page layouts, each having a separate instance of the message board portlet. Only by using the portlet layout ID will the permission system be able to distinguish the three separate instances of the message board portlet. This way, permission can be assigned separately in all three instances. Though in general, most portlets won’t need to use the portlet layout ID in relation to the permission system.

Service vs. LocalService

Since the ServiceImpl class extends the PrincipalBean class, it has access to information of the current user making the service request. Therefore, the ServiceImpl class is the ideal place in your business layer to check user permission. Liferay’s convention is to implement the actual business logic inside the LocalServiceImpl methods, and then the ServiceImpl calls these methods via the LocalServiceUtil class after the permission check completes successfully. Your PortletAction classes should make calls to ServiceUtil (wrapper to ServiceImpl) guaranteeing that permission is first checked before the request is fulfilled.

Checking Model Resource Permission

Checking model resource permission is very similar to checking portlet resource permission. The only major difference is that instead of calling methods found in the PortletPermission class mention previously, you need to create your own helper class to assist you in checking permission. The next section will detail how this is done.

Custom Permission Class

It is advisable to have a helper class to help check permission on your custom models. This custom permission class is similar to the PortletPermission class but is tailored to work with your custom models. While you can implement this class however you like, we encourage you to model after the PortletPermission class, which contains four static methods. Let’s take a look at the BlogsEntryPermission class.

public class BlogsEntryPermission {

	public static void check(
			PermissionChecker permissionChecker, String entryId,
			String actionId)
		throws PortalException, SystemException {

		if (!contains(permissionChecker, entryId, actionId)) {
			throw new PrincipalException();
		}
	}

	public static void check(
			PermissionChecker permissionChecker, BlogsEntry entry,
			String actionId)
		throws PortalException, SystemException {

		if (!contains(permissionChecker, entry, actionId)) {
			throw new PrincipalException();
		}
	}

	public static boolean contains(
			PermissionChecker permissionChecker, String entryId,
			String actionId)
		throws PortalException, SystemException {

		BlogsEntry entry = BlogsEntryLocalServiceUtil.getEntry(entryId);

		return contains(permissionChecker, entry, actionId);
	}

	public static boolean contains(
			PermissionChecker permissionChecker, BlogsEntry entry,
			String actionId)
		throws PortalException, SystemException {

		return permissionChecker.hasPermission(
			entry.getGroupId(), BlogsEntry.class.getName(),
			entry.getPrimaryKey().toString(), actionId);
	}
}

Again, the two check(…) methods are meant to be called in your business layer, while the two contains(…) methods can be used in your JSP files. As you can see, it’s very similar to the PortletPermission class. The two notable differences are:

1. Instead of having the portletId as one of the parameters, the methods in this custom class take in either an entryId or a BlogsEntry object.
2. None of the methods need to receive the portlet layout ID (plid) as a parameter. (Your custom portlet may choose to use the portlet layout ID if need be.)

Let’s see how this class is used in the blogs portlet code.

public BlogsEntry getEntry(String entryId) throws PortalException, SystemException {

	BlogsEntryPermission.check(
		getPermissionChecker(), entryId, ActionKeys.VIEW);

	return BlogsEntryLocalServiceUtil.getEntry(entryId);
}

In the BlogsEntryServiceImpl class is a method called getEntry(…). Before this method returns the blogs entry object, it calls the custom permission helper class to check permission. If this call doesn’t throw an exception, the entry is retrieved and returned to its caller.

<c:if test="<%= BlogsEntryPermission.contains(permissionChecker, entry, ActionKeys.UPDATE) %>">
	<portlet:renderURL windowState="<%= WindowState.MAXIMIZED.toString() %>" var="entryURL">
		<portlet:param name="struts_action" value="/blogs/edit_entry" />
		<portlet:param name="redirect" value="<%= currentURL %>" />
		<portlet:param name="entryId" value="<%= entry.getEntryId() %>" />
	</portlet:renderURL>

	<liferay-ui:icon image="edit" url="<%= entryURL %>" />
</c:if>

In the view_entry_content.jsp file, the BlogsEntryPermission.contains(…) method is called to check whether or not to show the edit button. That’s all there is to it!

1.4. Summary

Let’s review what we’ve just covered. Implementing permission into your custom portlet consists of four main steps. First step is to define any custom resources and actions. Next step is to implement code to register (or add) any newly created resources such as a BlogsEntry object. The third step is to provide an interface for the user to configure permission. Lastly, implement code to check permission before returning resources or showing custom features. Two major resources are portlets and Java objects. There is not a lot that needs to be done for the portlet resource to implement the permission system since Liferay Portal has a lot of that work done for you. You mainly focus your efforts on any custom Java objects you’ve built. You’re now well on your way to implement security to your custom Liferay portlets! For other user guides, please visit the Liferay documentation page

1.5. Information

Roles

If you’re wondering how the Liferay user roles, community roles, and organization / location roles should be implemented in your custom portlet, this brief section will address that. The short answer is, nothing needs to be developed specifically for user, community, and organization / location roles to work with your custom portlets. Liferay’s permission system has all that provided for you. When the hasUserPermission(…) method is called within the PermissionChecker class, Liferay checks all the roles the current user has, whether they’re organization / location roles, community roles, or user roles.

Using Your Own Security System in Liferay

Here’s a brief outline of how you can use your own security system in Liferay.

• Create your own PermissionChecker class that extends Liferay’s PermissionChecker class.
• Register this new class in portal.properties (or portal-ext.properties for the EXT environment) under the permissions.checker property.
• Override the hasUserPermission(…) method and the hasGuestPermission(…) method with your own calls to your permission system.
• You can call the setValues(…) method to pull in parameters from the request object that your permission checker might need (e.g., userId, projected, etc).
• You can call the resetValues(…) method to wipe out old parameters.
• Override the isAdmin(…) method.

Database Schema View

Reviewing how Liferay stores all the permission information in the database may help you gain a better understanding to the entire permission system.

• The resource_ table contains all the registered resources outlined in section 3.2.
• Every possible secure action that can be done to a resource will result in a row in the permission_ table. For example, a BlogsEntry resource may have a row in permission_ for the view action, and another for the update action.
  
• Whether a user has permission to a resource depends on the roles the user has, or the community (groups) and organization the user is in (green tables). If those roles or groups contain the needed permissionId in the permissions table (in blue), then the user has access to the resource.
  

2. User service

The User service allows the management of the portal user and it’s communities (aka Groups), Roles and UserGroups. It can be accessed through the static methods of UserServiceUtil. Following is a description of it’s most important methods:

	public static com.liferay.portal.model.User addUser(
		java.lang.String companyId, boolean autoUserId,
		java.lang.String userId, boolean autoPassword,
		java.lang.String password1, java.lang.String password2,
		boolean passwordReset, java.lang.String emailAddress,
		java.util.Locale locale, java.lang.String firstName,
		java.lang.String middleName, java.lang.String lastName,
		java.lang.String nickName, java.lang.String prefixId,
		java.lang.String suffixId, boolean male, int birthdayMonth,
		int birthdayDay, int birthdayYear, java.lang.String jobTitle,
		java.lang.String organizationId, java.lang.String locationId,
		boolean sendEmail)
		throws com.liferay.portal.PortalException,
			com.liferay.portal.SystemException, java.rmi.RemoteException;

Add a new user inserting in its profile the provided information

	public static com.liferay.portal.model.User updateUser(
		java.lang.String userId, java.lang.String password,
		java.lang.String emailAddress, java.lang.String languageId,
		java.lang.String timeZoneId, java.lang.String greeting,
		java.lang.String resolution, java.lang.String comments,
		java.lang.String firstName, java.lang.String middleName,
		java.lang.String lastName, java.lang.String nickName,
		java.lang.String prefixId, java.lang.String suffixId, boolean male,
		int birthdayMonth, int birthdayDay, int birthdayYear,
		java.lang.String smsSn, java.lang.String aimSn, java.lang.String icqSn,
		java.lang.String jabberSn, java.lang.String msnSn,
		java.lang.String skypeSn, java.lang.String ymSn,
		java.lang.String jobTitle, java.lang.String organizationId,
		java.lang.String locationId)
		throws com.liferay.portal.PortalException,
			com.liferay.portal.SystemException, java.rmi.RemoteException;

Update a user’s profile with the provided information.

	public static void addGroupUsers(java.lang.String groupId,
		java.lang.String[] userIds)
		throws com.liferay.portal.PortalException,
			com.liferay.portal.SystemException, java.rmi.RemoteException;

Add a set of users to a give community (aka Group) identified by the groupId.

	public static void addRoleUsers(java.lang.String roleId,
		java.lang.String[] userIds)
		throws com.liferay.portal.PortalException,
			com.liferay.portal.SystemException, java.rmi.RemoteException;

Add a set of users to a give Role identified by the roleId.

For more information check the Portal Javadocs.

What we are going to do

During developing Pet Catalog for Liferay we will:

• Install Liferay and Liferay Plugins SDK;
• Create Simple Project;
• Configure Eclipse to use it (it is not necessary and any other IDE may be used);
• Discuss technologies used inside Liferay;
• Developing DB entities & Services with using Service Builder;
• Developing UI with using JSPPortlet.

Some Liferay specific UI features (like tags to implement tables with paginator) will be discussed also.
Not so much – but it is only first tutorial and I hope (if it will be interesting) to continue this series with more tutorials explained basic Liferay functionality and services.

All sources for this step available at SVN: https://emforge.svn.sourceforge.net/svnroot/emforge/experiments/petcatalog-portlet/step1/petcatalog-portlet/ or you can browse them via Project Sources

Install Liferay and Plugins SDK

Simplest way to start using liferay – is download Liferay version bundled with some server – for example tomcat 6.0 (default configuration) from SourceForge site (https://sourceforge.net/projects/lportal/files/Liferay%20Portal/5.2.3/liferay-portal-tomcat-6.0-5.2.3.zip/download). After download unzip it somewhere (lets say <path_to_liferay>), go to tomcat bin directory (<path_to_liferay>/tomcat-6.0.18/bin) and run tomcat (./startup.sh)
Liferay ships with tomcat preconfigured to run liferay, so, all required memory settings, as well as preinstalled applications are ready to use – and simple run should work (ok, in my case it is working in 99%). To be sure liferay started well – you need to check logs (<path_to_liferay>/tomcat-6.0.18/log/catalina.out). After about 3-5 minutes – server should be run and ready to use.
To validate it – navigate your browser to http://localhost:8080 – you should see default liferay page with 7Coz demo. To login as Admin simple click on “Login as Bruno Admin” link
There are different ways to develop portlets for Liferay – more details you can read in liferay wiki (http://www.liferay.com/web/guest/community/wiki/-/wiki/Main/How+do+you+develop+-+Development+Strategies). We will use Plugin SDK Environment. To develop portlets in Plugins Environment we need to download Plugins SDK (again, from SourceForge: https://sourceforge.net/projects/lportal/files/Liferay%20Portal/5.2.3/liferay-plugins-sdk-5.2.3.zip/download), unzip it somewhere (<path_to_plugins>) and edit <path_to_plugins>/build.properties to point correct portal installation (uncommented property app.server.dir should point to <path_to_liferay> in our case).

Create Portlet Project

To start new portlet project switch to <path_to_plugins>/portlets and call

# ant -Dportlet.name=petcatalog -Dportlet.display.name="Pet Catalog" create

(I hope you have ant and java installed!)
As result, it will create folder petcatalog-portlet with required project structure and some initial files

What we have inside

Inside we have:

• build.xml – is an ant-file to build/deploy our project. Please, note – since this file is referenced to ant-files from plugins-sdk – this project cannot be moved somethere out of plugins-sdk;
• docroot – root of portlet – actually it is root of web-application;
• docroot/WEB-INF – standard folder with configuration files;
• docroot/WEB-INF/portlet.xml & docroot/WEB-INF/liferay-portlet.xml – description of portlets implemented in plugin;
• docroot/WEB-INF/liferay-display.xml – file defined how this portlet displayed in applications menu in liferay;
• docroot/WEB-INF/liferay-plugin-package.properties – file contains some packaging options for the project;
• docroot/WEB-INF/src – java-sources;

Configure Eclipse Project

This step is not required – actually you can do everything described later in any IDE and command-line, but I’ve used to use Eclipse and feel myself much more comfortable in it. So, we will setup eclipse project to work on portlet. To do it switch into portlet folder (<path_to_liferay>/portlets/petcatalog-portlet) and call

# ant setup-eclipse

This command will create required Eclipse project files.
Before we will import generated project into Eclipse workspace, we need to get portal sources. It is not required fro command-line build, but project generated has some dependencies to this portal project, so, we need to have it in workspace. Simple import portal project from SVN http://svn.liferay.com/repos/public/portal/tags/5.2.3/ into workspace (please not – it will take some – quite long – time since project quite big)
Now we can import generated portlet project into workspace also

Configure Tomcat server under Eclipse

Now, to be able to run and debug portal (and our portlet) under Eclipse we need configure Liferay’s tomcat server under Eclipse:

1. Define Tomcat 6.0 Runtime (Window -> Preferences -> Server -> Runtime Environment -> Add -> Apache Tomcat 6.0) and point it to tomcat in Liferay (<path_to_liferay>/tomcat-6.0.18)
2. Create Liferay server instance (Services Tab -> New -> Server)
3. Configure it (double click on created server):
   1. Increase Timeouts to something big enough;
   2. Server Locations -> Switch to “Use Tomcat Installation”;
   3. Set standard Liferay Java options: Open Launch Configuration -> Arguments Tab -> VM Arguments -> Add -Xms128m -Xmx1024m -XX:MaxPermSize=128m -Dfile.encoding=UTF8 -Duser.timezone=GMT
   4. Add sources of projects (to make it possible to debug): Open Launch Configuration -> Source Tab -> Add -> Java Project -> Select both – portal & portlet projects

Now, you should be able to start Liferay in Eclipse and see it’s log file in Console view.
latest step to setup ant-target. Open Ant View (Window -> Show View -> Ant) and drag&drop build.xml from portlet project into this view. Now, you will able to call required target (like deploy) for our portlet by double-click on it in this view

What Technologies will be used in Portlet Development

OK, now we are ready to start for real development, but before lets shortly list of technologies Liferay used or we will use.
For working with Database Liferay used Hibernate. In our cae we will not have care about hibernate mappings and configuration, since everything is done by Liferay core, or will be done for us by ServiceBuilder.
Spring Framework widelly used in Liferay to link different components, but again – we do not need care about it too much – since all required bean configuration will be done for us by ServiceBuilder
There are different frameworks available to use for Portlets UI development: Struts, Spring MVC, JSF (including IceFaces or RichFaces) and many more, but, in our case we will use JSP. Yes, yes, it is 2009 year – but in some cases it is still make sense to use plain, old, good JSP in some project. In our case reasons are:

1. Each portlet (including our own) implemented not a big system, bug small part of functionality. And it is responsibility of Portal (Liferay) to combine them into bigger system;
2. We do not need templating (like Tiles in Struts or Facelets in JSF) – since templates usually used to define “general” page look: header, footer, borders, but in our case it is responsibility of Liferay – we only need care about our small part of screen;
3. With using JSP we can use some very useful tag (like to implement table with paginator);

So, be ready to remember your development childhood

Working with ServiceBuilder

ServiceBuilder is a special tool provided by Liferay to build database entities, and services working with them. Speaking in EJB terms it help us to build @Entity and @Stateless beans.
In our example I will use “simplified” version of catalog – same as used in this JSF 2.0 and EJB 3.0 sample – supported only 1 entity object to edit/display list of pets.
So, to define our entity lets create file docroot/WEB-INF/service.xml with content:

<?xml version='1.0' encoding='UTF-8' ?>
<!DOCTYPE service-builder PUBLIC "-//Liferay//DTD Service Builder 5.1.0//EN" "http://www.liferay.com/dtd/liferay-service-builder_5_1_0.dtd">
<service-builder package-path='petcatalog'>
    <namespace>PetCatalog</namespace>

    <!-- Project -->
    <entity name='Item' table='PETS_ITEM' local-service='true' remote-service='false'>
        <!-- PK fields -->
        <column name='itemId' type='long' primary='true'/>
        
        <column name="productId" type="String" />        
        <column name="name" type="String" />        
        <column name="description" type="String" />        
        <column name="imageUrl" type="String" />        
        <column name="imageThumbUrl" type="String" />        
        <column name="price" type="double" />
    </entity>
</service-builder>

This file described entities (and not only entities – but we will speak about it later) operating by our portlet. In our case we simple defined same fields as used in JSF2/EJB3.1 PetCatalog sample.
Not, we can generate services classes and files from this description – simple run target build-service in our portlet ant-file. As result of this target followed classes will be generated:

• Model & Service Implementation classes;
• Model & Service Interface & Util classes;
• Hibernate mapping, Model Hints, Spring Configuration files.

Lets look more details into them

Model and Service Implementation classes

You can find them in docroot/WEB-INF/src/petcatalog folder (petcatalog package as it was defined in our service.xml). Model – is a DB-Model class (same as @Entity in EJB3), Service – is a service class – same as @Statelles in EJB 3.
For both, Model and Service we may see 3 different kind of classes:

• Base Classes (petcatalog.model.impl.ItemModelImpl & petcatalog.service.base.ItemLocalServiceBaseImpl) – this classes always generated by ServiceBuilder and implemented basic functionality – like required accessors for attributes, basic CRUD operations and so on. Since this classes always regenerated by ServiceBuilder – we should not change them;
• Implementation Classes (petcatalog.model.impl.ItemImpl & petcatalog.service.impl.ItemLocalServiceImpl) – they are inherited from base-classes and used for adding additional logic (methods, attributes not covered by service.xml file) by user. So, if we will like to add some new method into your service – we will add it into petcatalog.service.impl.ItemLocalServiceImpl)
• Interfaces – will be discussed in next topic, but – important thing is: interfaces are always generated from implementation. So, after you will add some extra method into your service implementation class – you will need to call ServiceBuilder again to regenerate interfaces

Model and Service Interface and Util classes

Will classes placed in docroot/WEB-INF/service folder and compiled into docroot/WEB-INF/lib/petclinic-service.jar. Improtant thing – these classes always regenerated by service build, so, it does not make sense to do any changes there – instead you should change Implementation clases discussed before.
Util-class (petcatalog.service.ItemLocalServiceUtil) implemented singleton pattern – it is used to access Service Implementation instance by using static methods.
In rest portlet code we should use this Util class to access Service functionality, and use Model Interface to operate with models (then real implementation is not required).

Hibernate mapping, Model Hints, Spring Configuration files

Additionally ServiceBuilder generated:

• Hibernate mapping file for our portlet (at docroot/WEB-INF/src/META-INF/portlet-hbm.xml);
• Model Hints file (at docroot/WEB-INF/src/META-INF/portlet-model-hints.xml) – this file contains additional information about model, helped Liferay to build UI – like length of fileds, format and many more (read Liferay wiki for details: http://www.liferay.com/web/guest/community/wiki/-/wiki/Main/Customize+DB+Column+Sizes);
• Same META-INF folder also has several spring-configuration files, most of them as “default”, provided hibernate sessionFactory, transactionManager and other “default” beans. But it also has portlet-spring.xml which has definitions of our Service and related beans.

OK, nice, now, we may implement our UI used this generated service

Developing UI with using JSPPortlet

Again, based on simple JSF2.0/EJB3.1 PetCatalog sample we are going to display list of pets and allow user to see details of pet by clicking the link in the table row.

Define Portlet

First of all we need to define our portlet. Create target executed in the beginning already created dummy portlet for us. You can check next files:

• docroot/WEB-INF/portlet.xml – contains definition of our petcatalog portlet. it said what portlet implemented in com.sample.jsp.portlet.JSPPortlet and /view.jsp is used to display portlet content. These settings is ok for us (at least for now), so, keep it like it is;
• docroot/WEB-INF/liferay-portlet.xml – contains some additional (liferay specific) configuration for our portlet. Keep it like it is for now;
• docroot/WEB-INF/src/com/sample/jsp/portlet/JSPPortlet.java – source of our portlet – currently it did not do anything – just said to display view.jsp;
• docroot/view.jsp – this jsp will display some default text on portlet display;

So, by default SDK generated simple portlet – we will use it as start-point. So, lets test is it working: run liferay, and run deploy target in portlet ant. Checking liferay logs (if you are using Eclipse like I’m you will see them in Eclipse console view) we can see:
10:42:01,509 INFO  [PortletAutoDeployListener:87] Portlets for /home/akakunin/apps/liferay-portal-5.2.3/deploy/petcatalog-portlet-5.2.3.1.war copied successfully. Deployment will start in a few seconds.

Oct 15, 2009 10:42:08 AM org.apache.catalina.core.ApplicationContext log
INFO: Initializing Spring root WebApplicationContext
Loading file:/var/tmp/1-petcatalog-portlet/WEB-INF/classes/service.properties
10:42:08,644 INFO  [DialectDetector:64] Determining dialect for HSQL Database Engine 1
10:42:08,647 WARN  [DialectDetector:79] Liferay is configured to use Hypersonic as its database. Do NOT use Hypersonic in production. Hypersonic is an embedded database useful for development and demo'ing purposes. The database settings can be changed in portal.properties.
10:42:08,649 INFO  [DialectDetector:97] Using dialect org.hibernate.dialect.HSQLDialect
Loading file:/var/tmp/1-petcatalog-portlet/WEB-INF/classes/service.properties
Loading file:/var/tmp/1-petcatalog-portlet/WEB-INF/classes/service.properties
10:42:11,280 INFO  [ServiceComponentLocalServiceImpl:270] Running PetCatalog SQL scripts for the first time
10:42:11,880 INFO  [PortletHotDeployListener:227] Registering portlets for petcatalog-portlet
10:42:12,396 INFO  [PortletHotDeployListener:346] 1 portlet for petcatalog-portlet is available for use

Looks like portlet correctly deployed. Now lets check how it is working:

• Open liferay UI in browser (http://localhost:8080),
• Login as admin (if you have 7Coz portlet installed, you can simple click on “Login as Bruno Admin”, if not, login by default admin: test@liferay.com/test)
• Create new page (“test” for example) to place our portlet;
• “Add Application” on this page – in popups with list of available applications/portlets we will able to find our “Pet Catalog” portlet in “Sample” category;
• Great! We can see default text “This is the Sample JSP Portlet. Use this as a quick way to include JSPs” – everything works fine.

Fill data into DB

In our simplest sample we will not have UI to add new Pets, only to display, so, we need to place them there manually:

• Stop Liferay;
• Open any SQL Client you like (and depending from which DB your Liferay configured to use). By default Liferay configured to use HSQL. HSQL client (which also may be used as client-app) we can find in <path_to_liferay>/tomcat-6.0.18/lib/ext/hsql.jar and DB itself stored in <path_to_liferay>/data/hsql/lportal files.
• So, open hsql client by run # java -cp <path_to_liferay>/tomcat-6.0.18/lib/ext/hsql.jar org.hsqldb.util.DatabaseManagerSwing
• In opened configuration window use options to connect to file in file-system and use jdbc:hsqldb:file:<path_to_liferay>/hsql/lportal as URL
• In opened window we will already see PETS_ITEM in the list of table – it is because Liferay already created it during first portlet deployment we only need to insert require data;
• Execute sample.sql there (you can find this file in docroot/WEB-INF/sql/sample.sql in project archive);
• Close client;

Display Table with pets

To display table with pets we need to change our view.jsp to by follow way:

<%@ taglib uri="http://java.sun.com/portlet_2_0" prefix="portlet" %>
<%@ taglib uri="http://liferay.com/tld/ui" prefix="liferay-ui" %>

<%@ page import="java.util.ArrayList" %>
<%@ page import="java.util.List" %>

<%@ page import="javax.portlet.PortletURL" %>
<%@ page import="javax.portlet.PortletPreferences" %>
<%@ page import="javax.portlet.WindowState" %>

<%@ page import="com.liferay.portal.kernel.dao.search.ResultRow" %>
<%@ page import="com.liferay.portal.kernel.dao.search.SearchContainer" %>
<%@ page import="com.liferay.portal.kernel.dao.search.SearchEntry" %>

<%@ page import="petcatalog.model.Item" %>

<%@page import="petcatalog.service.ItemLocalServiceUtil"%><portlet:defineObjects />

<%
    PortletURL portletURL = renderResponse.createRenderURL();
    
    // define list of headers we will use in the table
    List<String> headerNames = new ArrayList<String>();
    headerNames.add("name");
    headerNames.add("photo");
    headerNames.add("price");

    // create search container, used to display table
    SearchContainer searchContainer = new SearchContainer(renderRequest,
                                                        null, null,
                                                        SearchContainer.DEFAULT_CUR_PARAM,
                                                        SearchContainer.DEFAULT_DELTA,
                                                        portletURL,
                                                        headerNames,
                                                        "There No Pets To Display");
    portletURL.setParameter(searchContainer.getCurParam(), String.valueOf(searchContainer.getCurValue()));
    
    // get count of pets and list of pets to display on current page
    int petsCount = ItemLocalServiceUtil.getItemsCount();
    List<Item> pets = ItemLocalServiceUtil.getItems(searchContainer.getStart(),
                                                    searchContainer.getEnd());
    
    // set count into search container
    searchContainer.setTotal(petsCount);
    
    // fill table
    List<ResultRow> resultRows = searchContainer.getResultRows();
    for (int i=0; i < pets.size(); i++) {
        Item pet = pets.get(i);
        ResultRow row = new ResultRow(pet, pet.getItemId(), i);

        row.addText(pet.getName(), "");
        row.addJSP("/pet_image.jsp", application, request, response);
        row.addText(String.valueOf(pet.getPrice()));

        resultRows.add(row);
    }    
    
    // and finally display it
%>
<liferay-ui:search-iterator searchContainer="<%= searchContainer %>" />

This code doing following:

• Initialized SearchContainer – special Liferay-sepcific class used to display tables;
• Get data (count of pets and specific subset of pets) from our ItemLocalServiceUtil service, generated by ServiceBuilder. As you can see – some basic functions were generated there automatically;
• Fill SearchContainer with data to display;
• Display table with using liferay-ui:search-iterator tag

As result, default Liferay table should be used to dispplay pets with many functionality like applying styles from theme, pagination and so on.
But – before we will able to see it we need to do some additional changes:

Display Pet Images

Do display pets images in the table we did:

row.addJSP("/pet_image.jsp", application, request, response);
So, we need to create required JSP file:

<%@ page import="com.liferay.portal.kernel.dao.search.ResultRow" %>
<%@ page import="com.liferay.portal.kernel.util.WebKeys" %>
<%@ page import="petcatalog.model.Item" %>

<%
ResultRow row = (ResultRow)request.getAttribute(WebKeys.SEARCH_CONTAINER_RESULT_ROW);

Item pet = (Item)row.getObject();
%>
<img src="<%= request.getContextPath() %>/images/<%=pet.getImageThumbUrl() %>"/>

            <portlet-mode>VIEW</portlet-mode>
        </supports>
 <resource-bundle>petcatalog.messages</resource-bundle>
        <portlet-info>
            <title>Projects</title>

photo=Photo

name & price is already present in Liferay’s resources, so, we do not need to translate them. Later you can easily add localization for your portlet
What is all – try to redeploy portlet and refresh the page

Display Pet Details

To display pet details we we need to change (improve) a little bit our portlet class.
So, lets change portlet.xml to point into new class:

        <portlet-name>petcatalog</portlet-name>
        <display-name>Pet Catalog</display-name>
        <portlet-class>petcatalog.portlet.PetCatalogPortlet</portlet-class>
        <init-param>

and create this class extending from  from com.liferay.util.bridges.jsp.JSPPortlet:

package petcatalog.portlet;
import com.liferay.util.bridges.jsp.JSPPortlet;
public class PetCatalogPortlet extends JSPPortlet {
}

Now we can remove old portlet package in com.sample and redeploy -everything should continue to work.
Then we need to change table to correctly generate link to pet details.
On view.jsp, in for loop change how data for first column was added:

        ResultRow row = new ResultRow(pet, pet.getItemId(), i);

        PortletURL petURL = renderResponse.createRenderURL();
        petURL.setWindowState(WindowState.MAXIMIZED);
        petURL.setParameter("pet_id", String.valueOf(pet.getItemId()));
        petURL.setParameter("redirect", com.liferay.portal.util.PortalUtil.getCurrentURL(request));
        row.addText(pet.getName(), petURL.toString());
        
        
        row.addJSP("/pet_image.jsp", application, request, response);

Here we created URL, added petId and currentURL as arguments and added it as link for first column.
Now, lets change our portlet to handle pet_id parameter:

public class PetCatalogPortlet extends JSPPortlet {
    @Override
    public void doView(RenderRequest renderRequest, RenderResponse renderResponse) throws IOException, PortletException {
        // check - do we have pet_id parameter
        Long petId = ParamUtil.getLong(renderRequest, "pet_id");
        if (petId != null && petId != 0l) {
            // try to get Pet
            try {
                Item pet = ItemLocalServiceUtil.getItem(petId);
                renderRequest.setAttribute("pet", pet);
            } catch (Exception ex) {
                throw new PortletException("Cannot get pet", ex);
            }
            include("/view_pet.jsp", renderRequest, renderResponse);
        } else {
            super.doView(renderRequest, renderResponse);
        }
    }
}

doView method called then portlet is rendered. We just check pet_id parameter, get Catalog Item by id, put it into request attributes and navigate into view_pet.jsp
Last thing – implement view_pet.jsp:

<%@ taglib uri="http://java.sun.com/portlet_2_0" prefix="portlet" %>
<%@ taglib uri="http://liferay.com/tld/ui" prefix="liferay-ui" %>

<%@ page import="javax.portlet.PortletURL" %>
<%@ page import="javax.portlet.PortletPreferences" %>
<%@ page import="javax.portlet.WindowState" %>
<%@ page import="com.liferay.portal.kernel.util.UnicodeFormatter"%>

<%@ page import="petcatalog.model.Item" %>

<portlet:defineObjects />

<%
// get pet
Item pet = (Item)request.getAttribute("pet");
String redirect = request.getParameter("redirect");
%>

<table>
    <tr>
        <td><liferay-ui:message key="name" />:</td>
        <td><%= pet.getName() %></td>
    </tr>
    <tr>
        <td><liferay-ui:message key="description" />:</td>
        <td><%= pet.getDescription() %></td>
    </tr>
    <tr>
        <td><liferay-ui:message key="photo" />:</td>
        <td><img src="<%= request.getContextPath() %>/images/<%=pet.getImageUrl() %>"/></td>
    </tr>
    <tr>
        <td><liferay-ui:message key="price" />:</td>
        <td><%= pet.getPrice() %></td>
    </tr>
</table>
<input id="cancelButton" type="button" value="<liferay-ui:message key='cancel' />"
       onclick="location.href = '<%= UnicodeFormatter.toString(redirect) %>'"/>

This JSP will display Pet Details and image, Cancel button will navigate us back into list.

What’s next?

Ok, we completed very simple portlet for Liferay. Even it is simple, it covered all parts of web-application – starting from UI and finishing DB, explained how to create new DB tables and Services in Liferay, how easily write UI sometimes with sometimes not so simple functionality (like paginator).
In next tutorials I hope to cover followed questions:

• Add new Pet – process actions in portlets;
• Permissions and Authorization for Items;
• Better UI: use bookmarkable links;
• Dependency management in Portlets;
• and many many more.

Source: http://www.emforge.net/web/liferay-petstore-portlet/wiki/-/wiki/Main/Step1%3A+From+DB+to+simple+UI

The service builder framework in Liferay represents the database layer and all the interactions with database are done through service builder infrastructure. So in this blog, I will explain how you can use service builder framework inside your custom portlet using NetBeans 6.5 & Portal Pack 3.0. To use service builder framework, you first need to create a service xml and then generate the required code. The Portal Pack here helps you by providing a nice GUI editor for service.xml file where you can define the entities or database structures and from the same GUI you can generate the services code which can be used inside your portlet.

I have taken an example of Simple Form Submission Portlet here. Using this portlet you can submit customer details which will be stored inside liferay’s database and the same portlet will also show the no of customer records present in the database.

First create a Webapplication with “Portlet Support” framework and add a new Portlet to it. Now you need to create the service.xml file. Let’s create the portlet application as “CustomerApp” and a portlet “CustomerPortlet” inside it.

Creating the service.xml File

After creating a portlet application, you need to create a service.xml file inside the portlet application.

To Create a service.xml File

1. From the CustomerApp application, right click on Web Pages and select New > Others > Web Space/Liferay Plugins > Service Builder XML
2. Enter the file name as service. Make sure the “Folder” is selected as web. Then click Finish.
3. The service.xml file is created inside the web directory and the IDE opens the service.xml inside the editor area.

You can see two tabs “Design” and “XML” in the editor. The “Design” tab helps the user to add/modify entities through GUI and using “XML”, user can directly modify the xml.

Now we are ready to add entities to our service xml.

To Create Entity

1. Click on “Add” button.

   The Service Definition window appears. 

2. Specify the Entity Name as “CustomerDtls” and table name as “CustomerDtls”. The Entity name and table name doesn’t need to be same.
3. Now Click “Add”. So a new entity called “CustomerDtls” is now created.
4. Change the default Package Path name to com.sample.customer and namespace to “customer”. The namespace should be unique for every portlet application. No two portlet applications should have the same namespace.

Add Columns

After creating an entity, you need to add columns for that entity. So to create columns for an entity

• Select an entity.
• Click “Add” under the Columns tab as shown in the Fig : 3.

 

Fig : 3

Generating Services

• From the service.xml GUI editor, click the “Generate Services” button.
• You can see the creation of classes, services, and data models that are required for the database interaction. The service api classes are generated under $project/services directory and added to the project classpath. You should not do any modification in those classes as those will be overwritten next time when you run “Generate Service”. But the implementation classes which can be modified by the user, are added to the project source path and you can modify them as you want. But after modifying anything in the service implementation classes, you need to run “Generate Service” again.
• By default the generated service api jar will be bundled inside the portlet war file. But if you want other applications to access your services then the service api jar file needs to be there in the server classpath. You can do that by changing the preference which can be accessed by clicking on “Preferences” button. (Fig: 6)

Fig: 6

• Now in the GUI editor, click the Local Methods tab. This tab lists local method defined in the local service implementation. Now you can select “Go to Source”  to go the local service implementation. In our example this is “CustomerDtlsLocalServiceImpl.java” file. But we don’t need to add any local method for our current example.

Creating the View Page for Customer Portlet

• From the Projects pane, click the CustomerPortlet_view.jsp file.
• Add code to the CustomerPortlet_view.jsp file to create a HTML form to specify the id,name and age of a customer. This jsp also shows the no of customers in the database. Replace the CustomerPortlet_view.jsp code with following code snippets.

• From the Projects pane, click the CustomerPortlet.java file under the com.test package. Add the following code to processAction method. This method gets the data from the browser and add customer details to the database.

Deploy And Test

So we are now ready to deploy the portlet application. Right click on the portlet project and select “Deploy” to deploy the portlet on Liferay Portal Server. I am assuming you have selected “Liferay Portal Server”  as runtime for the portlet application. The required table is created automatically during the deployment time, so ideally you don’t need to create the table manually. But incase you get “Table not Found Exception” while accessing the portlet, you can run the generated table.sql manually to create the required tables. The table.sql can be found under “WEB-INF/sql” directory.

Now access your liferay portal from the browser and add the new “CustomerPortlet” to a page. You can see a simple form for customer data and below that no of customers in database which is initially “0″. Now try to add a customer and after successful addition of data to the database, the “No of Customers in Database” will be changed to 1.

Web service is nothing but exposes your software as service for other application over the network. Applications can be written in any programming language and if they support the statandard they can be integrated.It removes the concern of writing custom interfaces and REST/HTTP Post based calls for each integration point.

How they can be used , examples

As of now we have not used this feature in our platform. but there are several ways this can be used.

1. Data Migration.

2. External third party software integration – Applications like Salesforge

Exposing an entity as a SOAP Webservice in Liferay

In this example we will create a table in Database and expose a method to update this table via web service

Create a table

CREATE TABLE [dbo].[MyBook](
  [bookid] [bigint] NOT NULL,
  [bookname] [varchar](500) NULL,
CONSTRAINT [PK_MyBook] PRIMARY KEY CLUSTERED
(
   [bookid] ASC
)

Generate Service Layer code for table

1) Create service.xml place it in ext-impl\src\com\ext\portlet\mybook\service.xml

<?xml version="1.0"?>
<!DOCTYPE service-builder PUBLIC "-//Liferay//DTD Service Builder 5.2.0//EN" "http://www.liferay.com/dtd/liferay-service-builder_5_2_0.dtd">

<service-builder package-path="com.ext.portlet.mybook">
 <namespace>MyBook</namespace>
 <entity name="MyBook" local-service="true" remote-service="true">
  <column name="bookid" type="long" primary="true" />
  <column name="bookname" type="String" />
 </entity>
 <exceptions>
  <exception>BookEntryName</exception>
 </exceptions>
</service-builder>

<target name="build-service-portlet-mybook">
  <antcall target="build-service">
     <param name="service.file" value="src/com/ext/portlet/mybook/service.xml" />
  </antcall>
</target>

Now we will write a method to which will add a new book entry to the table.Open the generated file MyBookServiceImpl.java. if your entity name is ‘MyEntity’ in service.xml the generated class name will MyEntityServiceImpl.java

public MyBook addBook(String bookName) throws PortalException, SystemException {
  MyBook  mybook = null;
  long bookId = CounterLocalServiceUtil.increment(MyBook.class.getName());
  mybook = MyBookUtil.create(bookId);
  mybook.setBookname(bookName);
  return MyBookUtil.update(mybook, false);
}

Once this is done run the newly created ant task ‘build-service-portlet-mybook’ again. It will propogate this method rest of the interfaces and classes.Generate web service code for this method

Go to ext-impl\build-parent.xml and add a new ant task to generate the web service.

<target name="build-wssd-portlet-mybook">
  <antcall target="build-wsdd">
    <param name="service.file" value="src/com/ext/portlet/mybook/service.xml" />
  </antcall>
</target>

run the newly created ant task ‘build-wssd-portlet-mybook’. It will generate web service layer code for you.

Later on for easier convenience , you can add following task in ext-impl\build-parent.xml to build service and wsdd at same time.

<target name="build-mybook-service-wssd">
   <antcall target="build-service-portlet-mybook" />
   <antcall target="build-wssd-portlet-mybook" />
</target>

Consuming  Liferay Web services

• Enabling web services

The portal uses Apache Axis to generate web services. The default Axis configuration is specified in the server-config.wsdd file under the /portal/tunnel-web/ docroot/WEB-INF folder. type http://127.0.0.1:8080/ tunnel-web/axis in your browser, you will see a list of SOAP services.

To access a service remotely, the host must be allowed via the portal-ext. properties properties file. After that, the user must have permission to access the portal resources. The default settings to access a service remotely are specified in the portal.properties file as follows:

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

The code above shows the IPs to access the Axis servlet. You can input a blank list to allow any IP to access this servlet. SERVER_IP will be replaced with the IP of the host server. By default, 127.0.0.1 is the IP for local host. This is the reason that you can access web services only by the IP 127.0.0.1

• Example to access services

1. Service can be browsed at http://127.0.0.1:8080/tunnel-web/axis
2. To access the wsdl , click on the wsdl for any of the service.This is the example for User Service wsdl http://127.0.0.1:8080/tunnel-web/axis/Portal_UserService?wsdl
3. From WSDL you can generate stub and other classes using eclipse or netbeans.
4. Following is the sample client code to call a  user service service

public class LiferayUserServiceClient {
    public static void main(String[] args) {
         try {
             UserServiceSoapServiceLocator locatorUser = new UserServiceSoapServiceLocator();
             UserServiceSoap soapUser = locatorUser.getPortal_UserService("http://abc:abc@127.0.0.1:8080/tunnel-web/secure/axis/Portal_UserService");
             UserSoap soapUserModel =  soapUser.getUserById(10806);
             System.out.println(" getEmailAddress:" + soapUserModel.getEmailAddress());
        } catch (Exception e) {
           e.printStackTrace();
        }
    }
}

Source: http://arvindm.com/2010/03/23/web-services-in-liferay

Its really easy in D7. Coding is not at all required.

Taxonomy is a field in D7. I will explain how to create a Related Content block using Views.

1. Create an argument by adding the taxonomy field on which you want to find the related nodes.
2. Select “Provide default argument”.
3. Argument type = “Taxonomy Term ID from URL”
4. Remove tick from “Load default argument from term page”
5. Tick the “Load default argument from node page, thats good for related taxonomy blocks.”

To remove duplicates you have to follow the following points.

1. Open “Query settings” in the “Advanced Settings”.
2. Tick “Distinct”.

This gives you a perfect “Related Articles” or “Related Nodes” using Views.

Overview

Passing an argument from the URL into a block is a common thing. The idea is that the content of a block will change according to what is viewed. For example, we would like a block to show us all the taxonomy terms of a certain node. For this reason we need to pass to the block the argument of the node id (nid). In the following url http://xxx/node/123 argument number 1, which we will call %1, and is equal to 123.

When creating a mini panel, you get the functionality of Panel pages, but the outcome is a block that can be either configured through the blocks admin (http://xxx/admin/build/block), or added to a panel page.

Modules

• Panels
• Panel pages
• Mini panels
• Views

Requirements

• Create a mini panel that shows the comments the currently signed-in user has written in the currently viewed page.
• Enable the block on nodes.

Operation

1. Create a view according to the requirement- user_comments_per_node. (Example attached at bottom of page.)
2. We need to prepare the integration of our view ‘user_comments_per_node’ with panels.
   1. Go to Admin, Panels, Views, or http://xxx/admin/panels/views.
   2. Select the view from the dropdown list and click create panel view
3. In the view Select our View – user_comments_per_node.
1. Set the Panel view title to: User comments per node
2. Keep the view type as block, since we defined there this should appear as ‘List’.
3. Set the required context to: Node
4. Set the amount of items to display to five (5).
5. Click ‘Save’.
4. Just to understand what’s going in this page:
1. ‘Basic information’ concerns the Visual representation of the Views in the panel admin.
2. ‘Arguments’ defines which argument the view can and is allowed to get. Since panel can have several context it’s important to make sure the views gets the correct arguments.
3. ‘Paging information’ defines whether the output of the views should be paged (i.e. those | 1 | 2 | next>> | Last | links ). Even if paging wasn’t defined in the views, it can be defined here. Also the number of posts or offset (i.e. output the view starting from the 2nd result).
4. ‘Pane decorations’ are Merlin’s way of letting us, grateful people, decide if the panel will allow us to override few settings from the panel itself. This can become handy if you have several pages showing the same views, but need a slightly different behavior.
5. Add a mini-panel by going to Panels -> Mini Panels, or http://xxx/admin/ panels/panel-mini/add.
6. Set the layout as ‘Single column’.
7. Enter the mini panel title and name. Set the title to ‘My comments’ and the name to ‘user_comments’. Click ‘Next’.
   
8. We’ve been redirected to the ‘Content’ tab – here we will add the View created previously.
9. Click on the ‘Add content’ Icon and select under ‘Views’ our view. Click ‘Add pane’.
   
10. Our view was added. Don’t forget to save the panel; just adding it is not enough.
11. The mini panel is ready, which means that in the blocks admin (http://xxx/admin/build/block) we have a new mini-panel called Mini panel: “My comments”. Set it to appear on the ‘Right sidebar’.
12. How to show the block only on certain content types, and in another place? Use the panel pages node override of course. Here’s a tutorial for getting started with node overrides.

If you want to import a starting point, download the code and import it by clicking the import tab at the top of the Panel pages module.

As an example View, you can start with this export. (This may not exactly meet the initial specifications, but it does pick up comments for a particular node only.) Import the view using the Import tab under the Views UI.

That should be a simple thing to do but I’m looking for that solution for the past three weeks and the module contemplate didn’t help.

Nguồn: http://drupal.org/node/1015696

KORTRIJK, BELGIUM & CHICAGO, IL — Ngày 5 tháng 1 năm 2011 – Cộng đồng Drupal trên toàn thế giới cùng với Hiệp hội Drupal đón chào việc công bố chính thức ra mắt Drupal 7, nền tảng web được đánh giá là mạnh nhất hiện nay. Drupal là một nền tảng mã nguồn mở để quản lý nội dung website, hiện đang được ứng dụng trên hàng triệu website và các ứng dụng web. Những ứng dụng tiêu biểu là trang web của Nhà Trắng của tổng thống Mỹ WhiteHouse.gov và nhiều trang web của các nghệ sĩ âm nhạc của hãng Warner Media Group. Drupal phiên bản 7 [D7] mang đến công nghệ web mới nhất và các cải tiến đáng kể đối với người sử dụng. Drupal 7 cũng đang được chính thức trong các site có khả năng chịu tải rất cao, như trang Examiner.com, đứng trong top 100 website của Mỹ và tăng lưu lượng 19% từ tháng 10 tới tháng 11, với hơn 22.4 triệu lượt người sử dụng hàng tháng.

“Nền tảng Drupal 7 mới này cung cấp các trường API, lưu trữ và cache thay đổi, cho phép sử dụng Mongo như là giải pháp ‘Không SQL’ cho các ứng dụng chịu tải cao và có khả năng mở rộng. Bộ khung kiểm thử đơn vị mới đảm bảo phần lõi ổn định, đã được chứng minh qua những lần hợp nhất lõi hệ thống khi phát triển dự án của chúng tôi. Trang Examiner.com, với lưu lượng sử dụng cực lớn và khả năng xuất bản tức thì, sẽ rất khó khăn thậm chí không thể phát triển được trên các phiên bản trước đây của Drupal” ông Jim Davidson, chủ tịch của Examiner.com nói.

Dự án phát triển Drupal 7 kết hợp giữa các chỉ dẫn của các chuyên gia công nghệ, cùng với phản hồi của cộng đồng, để làm cho việc sử dụng được dễ dàng hơn. Việc cải tiến cách thức sử dụng bao gồm quản lý dễ dàng hơn, quản lý các cập nhật, truy xuất và tạo nội dung.

Angie Byron (hay Webchick), người bảo trì phát triển lõi của Drupal 7 khẳng định “Drupal 7 cải tiến giao diện người dùng, nâng cao truy xuất, quản lý hình ảnh tốt hơn, hỗ trợ các dữ liệu meta đa nội dung, an toàn bảo mật, khả năng mở rộng và nâng cao trao đổi cơ sở dữ liệu. Drupal 7 vượt qua 30 nghìn lượt kiểm tra để đảm bảo tính ổn đinh. Tóm lại, đây là một bước tiến to lớn cho Drupal và cho tất cả các nhà phát triển website, và chúng tôi rất hạnh phúc vì có thể chính thức giới thiệu Drupal 7 cho thế giới.”

Drupal là phần mềm mã nguồn mở được sử dụng bởi hơn nửa tỉ người trên 200 quốc gia và 189 ngôn ngữ. Gần 1000 thành viên của cộng đồng Drupal đã và đang đóng góp trực tiếp phát triển lõi Drupal 7 và các module kèm theo.

“Drupal đã tăng trưởng như một hiện tượng từ phiên bản 6. Phiên bản 7 này tạo ra bước cải tiến lớn cho việc sử dụng, tốc độ và chức năng”, Dries Buytaert, nhà sáng lập và trưởng nhóm phát triển Drupal cho biết. “Chúng tôi mở ra một chương mới trong việc phát triển web, và cùng với mọi người trên thế giới đóng chào sự kiện ra mắt Drupal 7 vào ngày 7 tháng 1 năm 2011″

Những chức năng quan trọng mới của Drupal 7

• Cải tiến giao diện sử dụng đáp ứng nhu cầu của đa số 80% người sử dụng, cho phép thực hiện các công việc thường gặp dễ dáng hơn, các thiết lập mặc định thông minh, phân quyền cho người tạo nội dung và đơn giản hóa việc quản lý chung.
• Hỗ trợ trong lõi các chức năng hình ảnh như thay đổi kích cỡ, cắt ảnh.
• Chức năng kiểm thử được xây dựng sẵn và tự động hóa cho mỗi bản vá giúp cho hệ thống ổn định lâu dài.
• Quản lý nâng cấp các phiên bản và chuyển đổi từ Drupal 6 sang Drupal 7.
• Tốc độ và khả năng mở rộng tốt hơn bằng công nghệ cache tiên tiến, mạng truyền dữ liệu (CDN) và sao chép dữ liệu master-slave.
• Các trường tùy chỉnh trong lõi, các trường dữ liệu cho mọi loại nội dung và cho cả người dùng, phân loại cùng với hỗ trợ và đa ngôn ngữ.
• Lớp cơ sở dữ liệu tóm tắt cho phép sử dụng nhiều loại CSDL như Maria, DB, Microsoft SQL, MongoDB, Oracle, MySQL, PostgresSQL hoặc SQLite.

“Tại SubHub, chúng tôi giúp mọi người đạt lợi nhuận từ nội dung trực tuyến của họ. Một năm trước, chúng tôi quyết định bắt đầu với Drupal 7 để phát triển nền tảng quản lý nội dung thế hệ mới của chúng tôi”, Jamie Wiseman, trưởng nhóm phát triển của SubHubLite tại Cardiff, Wales, Vương quốc Anh nói. “Khả năng linh hoạt của Drupal giúp chúng tôi xây dựng được hệ thống chúng tôi hằng mơ ước”.

Drupal nổi tiếng trên thế giới vì mở rộng hỗ trợ đa ngôn ngữ và hỗ trợ người tàn tật, như đã được chứng nhận tại Hà Lan là thích ứng 100% với Yêu cầu tiếp cận nội dung web (WCAG 2.0) của tổ chức World Wide Consortium (W3C)

Hỗ trợ công nghệ web ngữ nghĩa đa nội dung (RDFa) trong lõi của Drupal 7

Drupal 7 đang tiên phong trong việc đẩy mạnh chấp nhận RDFa (chuẩn về Khung miêu tả đa nội dung trong thuộc tính của W3C). Như chúng ta đã biết, Google và Bing phụ thuộc vào các dữ liệu tự động lấy từ các trang web khác.Thiết kế của Drupal 7 nhúng dữ liệu meta ngữ nghĩa vào lõi, giúp cho nội dung của các trang web ứng dụng Drupal 7 dễ dàng được các công cụ tìm kiếm lọc và phân tích. RDFa cung cấp thêm thông tin cho các công cụ tìm kiếm, những thông tin không hiển thị cho người dùng như là kinh độ và vĩ độ của một điểm trên bản đồ, hay cung cấp chuẩn thời gian chuẩn ISO cho từng địa phương và hiển thị kết quả tìm kiếm cho từng quốc gia.

Theo Dries, nhà sáng lập Drupal, “giới thiệu công nghệ ngữ nghĩa vào lõi của Drupal sẽ là đóng góp lớn cho tương lai của web.”

Về Hiệp hội Drupal

Hiệp hội Drupal là tổ chức phi lợi nhuận hỗ trợ cộng đồng Drupal bằng tài trợ, hạ tầng, tổ chức sự kiện, quảng cáo và phân phối. Được hỗ trợ bởi các thành viên cá nhân và tổ chức, Hiệp hội sử dụng các nguồn lực để giúp đẩy mạnh phát triển Drupal.

Hiệp hội Drupal có trụ sở đặt tại Bỉ. Xin tham khảo hoặc tải Drupal tại Drupal.org.

Trước tiên, chúng ta cần tạo thư mục dành cho java:

mkdir /usr/java

tại hệ thống thử nghiệm này, chúng tôi đang sử dụng hệ điều hành Ubuntu phiên bản 64bit (với hệ thống Ubuntu 32bit các bạn cần tải gói i586 tương ứng). Truy cập địa chỉ này và tải file jdk-6u21-linux-x64.bin, lưu vào thư mục java vừa tạo ra.

Tiếp theo, chúng ta cần gán thuộc tính thực thi cho file đó và kích hoạt:

cd /usr/java
chmod +x jdk-6u21-linux-x64.bin
./jdk-6u21-linux-x64.bin

Hãy thêm dòng mã /etc/profile đối với JDK6 và Liferay Portal. Mở file /etc/profile:

nano /etc/profile

và thêm những dòng sau vào phía cuối của file:

export JAVA_HOME=/usr/java/jdk1.6.0_21
export LIFERAY_HOME=/usr/liferay/liferay-portal-6.0.5/tomcat-6.0.26
export PATH=$JAVA_HOME/bin:$LIFERAY_HOME/bin:$PATH

Hãy chắc chắn rằng tham số JAVA_HOME và LIFERAY_HOME đã được thiết lập chuẩn xác. Để làm việc này, mở Terminal và gõ lệnh:

echo $JAVA_HOME
echo $LIFERAY_HOME

Tạo cơ sở dữ liệu

Đăng nhập vào MySQL bằng tài khoản root:

mysql -u root –p

và bước đầu tạo cơ sở dữ liệu như sau:

CREATE DATABASE lportal DEFAULT CHARACTER SET utf8;
quit;

Tạo thư mục cho Liferay

mkdir /usr/liferay

Cài đặt Liferay

Tải và giải nén gói Liferay cùng với Tomcat vào thư mục /usr/liferay. Tiếp đến, tạo file Portal-Ext.Properties:

cd $LIFERAY_HOME/webapps/ROOT/WEB-INF/classes
nano portal-ext.properties

Và chèn thêm dòng mã sau:

#
# MySQL
#
jdbc.default.driverClassName=com.mysql.jdbc.Driver
jdbc.default.url=jdbc:mysql://localhost/lportal?useUnicode=true&characterEn
coding=UTF-8&useFastDateParsing=false
jdbc.default.username=root
jdbc.default.password=password
schema.run.enabled=true
schema.run.minimal=true

Thay đổi lại giá trị username và password mong muốn.

Sử dụng tiếp lệnh sau:

cd $LIFERAY_HOME/bin
chmod +x *.sh

để gán thuộc tính thực thi cho các file đó.

Khởi động Liferay

Lần khởi động đầu tiên này thông thường sẽ mất từ 10 – 15 phút (phụ thuộc vào cấu hình và tình trạng phần cứng):

$LIFERAY_HOME/bin/startup.sh

và để truy cập vào Liferay, các bạn áp dụng mẫu sau:

http://<địa chỉ IP của server Liferay>:8080

ví dụ ở đây là:

http://192.168.0.1:8080

Trên đây là 1 số thao tác cơ bản để cài đặt và sử dụng Liferay 6.0.5 Community cùng với Tomcat trên nền tảng Ubuntu 10.04. Chúc các bạn thành công!

http://www.quantrimang.com.vn/hedieuhanh/linux/70690_Huong-dan-cai-dat-Liferay-6-0-5-Community-voi-Tomcat-tren-Ubuntu-10-04.aspx