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

                                                    Fig : 4

Add Finder Methods

You can also add your custom finder methods to the entity from "Finders" tab. In "Finders" tab, click "Add Finder" to add finder methods. It provides a GUI where you can select different columns required for your finder methods.(Fig. 5)



Fig. 5

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.

 

Fig: 7