Today I tried to create a service in a plugin portlet of liferay. Since this is not very straight forward, it took me the whole day to get my simple service running. As a matter of fact, I decided to publish this on the web.

I used Liferay6.0.5 source and plugin sdk, along with eclipse 3.6, with WTP and Liferay IDE 1.0.1. The base platform was Java1.6.0_21 and MySQL5.1.46, both running on openSuse11.3. The deployment server was tomcat6.0.26.

Step 1: Setup liferay source project and tomcat

1. Unzip the liferay source in your eclipse workspace. In eclipse, create a new project with the name liferay-portal-src-6.0.5. Eclipse will automatically detect the project type and configure it accordingly.

2. Open the app.server.properties and edit the app.server.parent.dir to point to the folder containing the tomcat installation. Note that this is the parent folder of CATALINA_HOME. For me it was: app.server.parent.dir=/home/swoosh/installations

3. Un-comment: app.server.type=tomcat

4. Scroll down and change the app.server.tomcat.dir, so that it points to the CATALINA_HOME. For me it was: app.server.tomcat.dir=${app.server.parent.dir}/liferay-tomcat-6.0.26

5. Save and close the app.server.properties

6. Create a DB schema and user using any tool (I used MySQL Administrator)
   

7. Open the portal.properties and comment out the HSQL (Hypersonic) DB settings.

8. Un-comment the MySQL DB settings and change the host, schema name, username and password. For me the settings were:
   jdbc.default.driverClassName=com.mysql.jdbc.Driver
   jdbc.default.url=jdbc:mysql://localhost/lportal?useUnicode=true&characterEncoding=UTF-8&useFastDateParsing=false
   jdbc.default.username=liferay
   jdbc.default.password=test

9. Save and close the portal.properties file.

10. Now open the ant view in eclipse and drag liferay-portal-src-6.0.5/portal-web/build.xml and liferay-portal-src-6.0.5/build.xml file to the ant view. Wait for some time as ant loads the set of build files.

11. Run the build-themes task under portal-web (from liferay-portal-src-6.0.5/portal-web/build.xml). Make sure that you get Build Successful message everytime you fire an ant task. (There is a bug in liferay's builder due to which it doesn't create the themes when you compile the source. If you directly deploy the source, you wont be able to access the home page).

12. Now run the compile task under portal (from liferay-portal-src-6.0.5/build.xml).

13. Then run the deploy task under the same file. Watch the log to verify that ant is copying the files to the right folder. If not, then double check the settings specified in the app.server.properties file.

14. Now you have tomcat bundled up with the liferay portal. To start it you need to set up the runtime in eclipse. Go to Window->Preferences->Server->Runtime Environments. Click Add. Select the srever type as Liferay v6.0 (Tomcat 6). Click next. Give a name to your runtime - Liferay v6 (Tomcat 6). Browse and select the tomcat folder that you specified in app.server.properties' app.server.tomcat.dir property. Select runtime as java 1.6 and click Finish.

15. If you don't have a server project in your workspace, then create a new one. Right click on the server project and Create a new server. Select the server type as Liferay v6.0 (Tomcat 6) and runtime as Liferay v6 (Tomcat 6). Server's host name should be localhost. Click next and click Finish.

16. Now the server should appear under your server view (Add the view from Window->Show View->Servers)

17. Double click on the server and change the Timeouts to 300 seconds. This will give enough time to the server to create and populate the DB schema for the first time.
    

18. Right click on the server and select start.

19. The liferay server should start. For the first time, it will create all the tables and populate them with the seed data.

20. Once you get the server started message, open the web browser and open the http://localhost:8080. You should get the liferay's default home page. Enter test@liferay.com as email address and test as password.

21. If you are not able to see the liferay's page even though the source was compiled and deployed successfully, then please check your app.server.properties file.

Step 2: Setup plugin SDK.

1. Download and unzip the plugins sdk.

2. Open the liferay-plugins-sdk-6.0.5/build.properties file and change the server settings:
   app.server.type=tomcat app.server.dir=/home/swoosh/installations/liferay-tomcat-6.0.26 app.server.deploy.dir=${app.server.dir}/webapps app.server.lib.global.dir=${app.server.dir}/lib/ext app.server.portal.dir=${app.server.dir}/webapps/ROOT
   

3. Go to Window->Preferences->Liferay->Installed SDKs.

4. Click on Add. In the pop-up window browse to the unzipped sdk folder and click Ok.

Step 3: Create the service project

1. Now create a new Liferay plug-in project. Enter the details as in the screenshot below:
   

   

2. Click Next and select Dynamic Web module version 2.5 and Default configuration for Liferay v6.0 (Tomcat 6).
   

3. Click Finish and Click Yes on the Switch Perspective dialog box.
   

4. A new TestPlugin-Portlet Project will appear in the navigator.

5. Now right click on the plugin project and select New->Liferay Service.

6. Enter the detail as in the screenshot below:
   

   

7. You can enter a different package and Namespace. In that case you will have to follow the next steps accordingly.

8. Click Finish. The service.xml file will be created and will be opened in the service editor.

9. The service.xml is similar to the service definition files in the ext environment of older liferay versions. Here we can define as many entities along with their functions.

10. We will create an Employee entity with id (long) and name (String) attributes. The service definition looks like:
    

    

11. Save the service.xml file.

12. Drag the TestPlugin-portlet/build.xml to the Ant view.

13. In the ant view, expand the TestPlugin-portlet and run the build-service task.

14. If the build fails, please check if you have followed the point number 2 in Step 2. On successful build, the ant task creates the files related to Employee entity.

15. Refresh your project (F5) to see the files.

16. Right click on the project go to Properties->Java Build Path->Source tab. Add the TestPlugin-portlet/docroot/WEB-INF/service and TestPlugin-portlet/docroot/WEB-INF/src folders, and click Ok.
    

17. Implement the service by editing com.liferay.test.service.impl.EmployeeLocalServiceImpl. Add the implementations for CRUD and finder methods. They look like the following listing:
    public Employee create(Employee model) throws SystemException{
      long id = CounterLocalServiceUtil.increment(Employee.class.getName());
      model.setId(id);
      Employee newModel = EmployeeUtil.create(model.getId());
    
      newModel.setName(model.getName());
      EmployeeUtil.update(newModel, true);
      return newModel;
    }
    
    public Employee update(Employee model) throws NoSuchEmployeeException, SystemException{
      Employee newModel = EmployeeUtil.findByPrimaryKey(model.getId());
    
      newModel.setName(model.getName());
    
      EmployeeUtil.update(newModel, true);
    
      return newModel;
    }
    
    public List<Employee> findByName(String name) throws SystemException{
      return EmployeeUtil.findByName(name);
    }
    
    public Employee remove(long id) throws NoSuchEmployeeException, SystemException{
      return EmployeeUtil.remove(id);
    }

18. Run the TestPlugin-portlet/build-service task and make sure that build is successful.

19. Similarly edit the com.liferay.test.service.impl.EmployeeServiceImpl Add the CRUD and finder methods as listed below:
    public Employee create(Employee model) throws SystemException{
      return EmployeeLocalServiceUtil.create(model);
    }
    
    public Employee update(Employee model) throws NoSuchEmployeeException, SystemException{
      return EmployeeLocalServiceUtil.update(model);
    }
    
    public List<Employee> findByName(String name) throws SystemException{
      return EmployeeLocalServiceUtil.findByName(name);
    }
    
    public Employee remove(long id) throws NoSuchEmployeeException, SystemException{
      return EmployeeLocalServiceUtil.remove(id);
    }

20. Run the TestPlugin-portlet/build-service task again and make sure that build is successful.

21. There is a bug in liferay's service builder due to which it doesn't generate the ServiceSoap class correctly. It is not able convert the parameters to their corresponding soap type. See http://issues.liferay.com/browse/LPS-12629 for details. To get around this issue open the EmployeeServiceSoap and change the generated create and update methods as:

     
    publicstatic com.liferay.test.model.EmployeeSoap create(
       com.liferay.test.model.EmployeeSoap model) throws RemoteException {
     try {
      com.liferay.test.model.Employee returnValue = EmployeeServiceUtil.create(com.liferay.test.model.impl.EmployeeModelImpl.toModel(model));
     
      return com.liferay.test.model.EmployeeSoap.toSoapModel(returnValue);
      }
      catch (Exception e) {
      _log.error(e, e);
     
      throw new RemoteException(e.getMessage());
      }
    }
     
    publicstatic com.liferay.test.model.EmployeeSoap update(
       com.liferay.test.model.EmployeeSoap model) throws RemoteException {
     try {
      com.liferay.test.model.Employee returnValue = EmployeeServiceUtil.update(com.liferay.test.model.impl.EmployeeModelImpl.toModel(model));
     
      return com.liferay.test.model.EmployeeSoap.toSoapModel(returnValue);
      }
      catch (Exception e) {
      _log.error(e, e);
     
      thrownew RemoteException(e.getMessage());
      }
    }

22.  Now run the TestPlugin-Portlet/build-wsdd task to generate the webservices.

23. Once this is complete, start the server if not already started.
    
24. Then run TestPlugin-Portlet/compile and TestPlugin-Portlet/deploy.
25. Check the logs for "1 portlet for TestPlugin-portlet is available for use" message.
26. If that appears, open the http://localhost:8080 in your browser.
27. Login as test@liferay.com and password test.
28. Go to Add -> More->Samples. Add the TestPlugin to you page. Make sure that the default page for the plugin appears. This confirms that the plugin was deployed properly.
29. Now open http://127.0.0.1:8080/TestPlugin-portlet/axis/Plugin_Test_EmployeeService?wsdl in your browser and confirm that the wsdl opens up.
30. This completes the plugin service creation.

Step 4: Create Web service client

1. Now we need to test our webservice. For that we need to have another tomcat runtime as our Liferay tomcat 6 runtime eclipse plugin doesn't support building webservices. Also we need to make sure that the tomcat runtime and liferay runtime run on different ports. I used the ports 9005, 9080 and 9009 for my tomcat runtime.
   

2. In eclipse go to New->Webservice Client and enter the details as in the screenshot below:
   

   

3. Click Next on this and next screen. Then click on "Start server" to start the tomcat runtime. Then click Finish.
   

4. Select all the methods and click Finish
   

5. Eclipse will then deploy the client and open up a screen to test your webservice.

6. Click on the methods to test them.

7. We will test create method first. We will provide the primaryKey=0, name=Liferay and id=0 and click invoke.

8. In the results section we can see that the employee entity has been created with the id=1.

9. Now invoke findByName and provide name=Liferay. The result will show the reference of the entity object returned by the webservice.

That completes the tutorial. The complete plugin and the webservice client can be downloaded from the attachments of this post. Hope that was helpful. Do write your comments.