Liferay Custom JSON Web Services on Multiple Tables

Liferay Custom JSON web services on Multiple Tables

Objective:

Create JSON web services for combination of multiple tables means prepare JSON web services so that data should come from multiple tables which are related each other.

Download CustomJsonWebservices portlet from following location

You can find source and war file

https://sourceforge.net/projects/meeralferay/files/CustomJsonWebservicesPortlet/

Note: 

Portlet developed in Liferay 6.1GA2 EE version

If you want deploy in CE version you just do changes in liferay-plugin-package.properties

Liferay 6.1 EE version

name= CustomJsonWebservices module-group-id=liferay-ee module-incremental-version=1 tags= short-description= change-log= page-url=http://www.liferay.com author=Liferay, Inc. licenses=EE liferay-versions=6.1.20

Liferay 6.1 CE version

name = CustomJsonWebservices module-group-id=liferay module-incremental-version=1 tags= short-description= change-log= page-url=http://www.liferay.com author=Liferay, Inc. licenses=LGPL liferay-versions=6.1.1

Procedure for deploy portlet:

You can use war file and directly place in your portal deploy folder and test or you can also use source to deploy portlet.

Once portlet is deployed successfully insert data in the following table as shown in screens

json_employee

json_address

And test web service URLs

Liferay provide JSON web services so that we can use those services in other systems.

Liferay providing two types of web services SOAP based and REST bases web services.

Liferay JSON web services come under REST based web services.

Here we are talking about only rest based web services i.e. liferay JSON web services.

Liferay have built in ability can generate JSON web services by default when we make remote-service true for service builder.

But the services which created by default we can apply on only one table means data can served from only one table or web services related to single entity.

But in real scenario the default web services not enough to full fill real requirement there we have write our custom methods to produce JSON data. This pretty easy in liferay because liferay also provides write custom methods for JSON web services in pluin portlet.

Note:

Liferay have provided to generate service layer using service builder. We will use servce builder to generate service layer classes and methods

Steps to produce Custom JSON web services in Liferay Plugin portlet environment

The Following are the steps write custom methods to produce JSON web services:

Step: 1

Create Plugin portlet in Liferay using liferay IDE and portlet is liferay MVC portlet.

Step: 2

Create service bolder for plugin portlet

Open service.xml file and define data base tables and put remote-service is true. When we put remote service true then it will create default JSON web services.

<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE service-builder PUBLIC "-//Liferay//DTD Service Builder 6.1.0//EN" "http://www.liferay.com/dtd/liferay-service-builder_6_1_0.dtd"> <service-builder package-path="com.meera.jsonwebservices.db">             <author>E5410</author>             <namespace>JSON</namespace>             <entity name="Employee" local-service="true" remote-service="true">                         <column name="emplyeeId" type="long" primary="true" />                         <column name="emplyeeName" type="String" />                         <column name="employeeDesignation" type="String" />                         <order by="asc">                                     <order-column name="emplyeeId" />                         </order>             </entity>             <entity name="Address" local-service="true" remote-service="true">                         <column name="Id" type="long" primary="true" />                         <column name="emplyeeId" type="long" />                         <column name="employeeAddress" type="String" />                         <order by="asc">                                     <order-column name="emplyeeId"/>                         </order>                         <finder name="emplyeeId" return-type="Collection">                                     <finder-column name="emplyeeId" />                         </finder>             </entity> </service-builder>

Step: 3

Now we need add JSON Web service servelet in web.xml of porltet. So that it will get web services exposing ability.

<?xml version="1.0" encoding="UTF-8"?> <web-app id="WebApp_ID" version="2.4" xmlns="http://java.sun.com/xml/ns/j2ee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd">             <display-name>CustomJsonWebservices-portlet</display-name>             <filter>          <filter-name>Secure JSON Web Service Servlet Filter</filter-name>          <filter-class>com.liferay.portal.kernel.servlet.PortalClassLoaderFilter</filter-class>          <init-param>           <param-name>filter-class</param-name>           <param-value>com.liferay.portal.servlet.filters.secure.SecureFilter</param-value>          </init-param>          <init-param>           <param-name>basic_auth</param-name>           <param-value>true</param-value>          </init-param>          <init-param>           <param-name>portal_property_prefix</param-name>           <param-value>jsonws.servlet.</param-value>          </init-param>        </filter>        <filter-mapping>          <filter-name>Secure JSON Web Service Servlet Filter</filter-name>          <url-pattern>/api/jsonws/*</url-pattern>        </filter-mapping>        <servlet>          <servlet-name>JSON Web Service Servlet</servlet-name>          <servlet-class>com.liferay.portal.kernel.servlet.PortalClassLoaderServlet</servlet-class>          <init-param>           <param-name>servlet-class</param-name>           <param-value>com.liferay.portal.jsonwebservice.JSONWebServiceServlet</param-value>          </init-param>          <load-on-startup>0</load-on-startup>        </servlet>        <servlet-mapping>          <servlet-name>JSON Web Service Servlet</servlet-name>          <url-pattern>/api/jsonws/*</url-pattern>        </servlet-mapping>             <jsp-config>                         <taglib>                                     <taglib-uri>http://java.sun.com/portlet_2_0</taglib-uri>                                     <taglib-location>                                                 /WEB-INF/tld/liferay-portlet.tld                                     </taglib-location>                         </taglib>                         <taglib>                                     <taglib-uri>http://liferay.com/tld/aui</taglib-uri>                                     <taglib-location>/WEB-INF/tld/aui.tld</taglib-location>                         </taglib>             </jsp-config>             </web-app>

Step: 4

Run service builder using ant build-service or in eclipse you can run this from ant view.

Step: 5

Writing Custom methods for produce JSON data

We need to decide for which entity we have to provide custom JSON services .find appropriate entity and write method XXXServiceImpl.java this is under package of

 you-base-package.service.impl package of your source.

Here XXX is entity name which is specified in service.xml

In our example I have implemented in EmployeeServiceImpl.java here I am getting employee object by employeeId. This method return employee object. In liferay any object automatically sterilizes and produces as JSON data.

The following is example for code

public class EmployeeServiceImpl extends EmployeeServiceBaseImpl {                public  com.meera.jsonwebservices.db.model.Employee getEmployee(                                     long emplyeeId)                                     throws com.liferay.portal.kernel.exception.PortalException,                                                 com.liferay.portal.kernel.exception.SystemException {                                     return EmployeeLocalServiceUtil.getEmployee(emplyeeId);                         } }

Once we completed writing custom method in XXXServiceImpl.java

Then we need to run service builder using ant build-service command or from eclipse ant view you can run same command

Step: 6

Now finally deploy the portlet into server by using ant deploy command or from ant view you can use same command

Now we are ready with custom JSON web services

Note:

For each modification in XXXServiceImpl.java or in service layed we have run ant build-service command  later we have to deploy the portlet using ant deploy then only change will be applied to the services.

  

Accessing JSON web services

To access the services we need to use following URL pattern

http://[server]:[port]/[plugin-context]/api/jsonws/[service-class-name]/[service-method-name]

Server:

 It’s your domain name or host name if you are in local the its “localhost”

Port:

It’s your application server port number.

plugin-context:

 it’s our plug-in portlet context name its simple as portlet name

api/jsonws:

This is path for call JSON Web Service servlet this is configured in web.xml

service-class-name:

 service-class-name is generated from the service’s class name by removing the Service or ServiceImpl suffix and making it lower case.This is our service class name where we implemented custom method or its simple a entity name which is in service.xml. In our example we implemented our method in EmployeeServiceImpl.java

Finally we have to use in URL as employee when we observe it’s just entity name in service.xml

service-method-name:

Service-method-name is generated from the service’s method name by converting its camel case to lower case and using dashes (-) to separate words

Finally our Complete URL like this for our Example:

http://localhost:8080/CustomJsonWebservices-portlet/api/jsonws/employee/get-employee

Plugin context path	CustomJsonWebservices-portlet
Web service servelet path	/api/jsonws
Service Class Name	EmployeeServiceImpl.java converted as employee
Service Method Name	getEmplyee(--) converted as get-employee

Passing parameters and its values:

We can pass parameters in two ways

Query String

URL pattern and separated param name and value by slash(/)

Complete URL example with query string

http://[server]:[port]/[plugin-context]/api/jsonws/[service-class-name]/[service-method-name]?param1=value1&param2=value2

Complete URL by URL pattern:

http://[server]:[port]/[plugin-context]/api/jsonws/[service-class-name]/[service-method-name]/param1/value1/param2/value2

For Our Example Complete URL to access employee data by passing employee id is following like this

http://localhost:8080/CustomJsonWebservices-portlet/api/jsonws/employee/get-employee/emplyeeId/1 OR http://localhost:8080/CustomJsonWebservices-portlet/api/jsonws/employee/get-employee?emplyeeId=1 result: {"employeeDesignation":"SoftwareEngineer", "emplyeeId":1,"emplyeeName":"meera"}

Note:

 Some time its ask Authentication so we should pass admin credentials as URL headers

With authentication The URL like follow

http://test@liferay.com:test@localhost:8080/CustomJsonWebservices-portlet/api/jsonws/employee/get-employee?emplyeeId=1 OR http://test@liferay.com:test@localhost:8080/CustomJsonWebservices-portlet/api/jsonws/employee/get-employee/emplyeeId/1 result: {"employeeDesignation":"SoftwareEngineer", "emplyeeId":1,"emplyeeName":"meera"}

Note:

 All these URLs you can use from any browser and see the JSON data. Here sometimes browsers not allows @ or # symbols in URL then we have to make this as URL encoding type characters

For encode URL and test in browse use following link and encode

http://www.url-encode-decode.com/

Encoded URL:

http%3A%2F%2Ftest%40liferay.com%3Atest%40 localhost%3A8080%2F CustomJsonWebservices-portlet%2Fapi%2Fjsonws%2F employee%2F get-employee%3FemplyeeId%3D1 OR http%3A%2F%2F+test%40liferay.com%3Atest%40 localhost%3A8080%2F CustomJsonWebservices-portlet%2Fapi%2Fjsonws%2F employee%2Fget-employee%2FemplyeeId%2F1

Well as of now we just done created Custom service and its calling

Now we will see another way to call same web service method in JSON Web Services Invoker

JSON web service Invoker:

JSON Web Services Invoker is one of the mechanism to call some complex web services very easy way.

Here we can call JSON web service Invoker by following URL pattern

http://[address]:[port]/[plugin-context]//api/jsonws/invoke

URL explanation is same like i explained previous section here we need to remember is to call invoker we have to use path /api/jsonws/invoke

This call take only one parameter i.e. cmd the value of this parameter is JSON Map.

Here we need to pass parameter as query string only like follow

http://[address]:[port]/[plugin-context]//api/jsonws/invoke?cmd=json-map

Our complete URL for example is

http://localhost:8080/CustomJsonWebservices-portlet/api/jsonws/invoke?cmd=json-map

What is JSON Map?

JSON Map is simple JSON object it contains key and value here value is another JSON object which contains key and value

In JSON map key will be used as service call path and value is parameters which passing to service calls.

The same example we discussed above we can do like this

Take the example get employee data by passing id.

Our Normal URL call is as follows

http://test@liferay.com:test@localhost:8080/CustomJsonWebservices-portlet/api/jsonws/employee/get-employee/emplyeeId/1

In above URL service call is    employee/get-employee/  and parameter is employeeId and its value is 1

Now the following is JSON map for above

{ "/employee/get-employee": { "emplyeeId": 1, } }

Here key is used as Service call and value is another json object contains parameters and its value.

Now call our complete web service call using JSON web service Invoker as follows

http://localhost:8080/CustomJsonWebservices-portlet/api/jsonws/invoke?cmd={"/employee/get-employee": {"emplyeeId": 1,}} result: {"employeeDesignation":"Software Engineer", "emplyeeId":1,"emplyeeName":"meera"}

This is way we have to pass JSON map to JSON web service invoker.

We can assign data as some reference object like following .here we have to specify $ before variable

{ "$emp=/employee/get-employee": { "emplyeeId": 1, } }

$emp is reference variable

http://localhost:8080/CustomJsonWebservices-portlet/api/jsonws/invoke?cmd={"$emp=/employee/get-employee": {"emplyeeId": 1,}}

In above call we will get JSON data have all columns of Employee Table

Fetching required columns from JSON Web service invoker means filtering columns

{ "$emp[emplyeeName,emplyeeId]=/employee/get-employee": { "emplyeeId": 1, } }

The following is complete web service call to filter columns using JSON web service invoker

http://localhost:8080/CustomJsonWebservices-portlet/api/jsonws/invoke?cmd={"$emp[emplyeeName,emplyeeId]=/employee/get-employee": {"emplyeeId": 1,}} result: {"emplyeeId":1,"emplyeeName":"meera"}

As of now we just call custom web service which is related to one entity or one table

Now we will see how to fetch JSON data so that data comes from multiple Tables

Some times in real requirement the data should fetch from multiple tables.

To make use of custom method we can produce JSON web services so that data come from multiple tables.

Understanding Real Scenario:

I have one employee each employee have multiple addresses.

Here I have two tables Employee and Address tables.

If we generate JSON web services from liferay it will serve only one table data for service. But here data stored in two tables.

So now we have to produce JSON services so that data should come from Employee Tables and Address table

Employee Table:

employeeId	employeeName	employeeDesignation
1	meera	Software Engineer
2	prince	Architect
3	savvy	Developer

Address Table:

Id	emplyeeId	Address
1	1	Hyderabad
2	1	Hong Kong
2	1	Landon

When you observe above data employee meera have 3 addresses

This is where we need to apply custom JSON web services.

Assume my data should be like as followed structure

{         name:”meera”,        addresess:[                           “Hyderabad”,”Landon”,”Hong Kong”                         ] }

We have two options

Complete manual preparation of JSON data

Use JSON Web service Invoker Nested calls

Complete manual preparation of JSON data:

In the manual preparation we will prepare JSON structure and will produce data.

In general List and any java object type can be serialize and will be produces as JSON data in liferay web services.Some scenarios some complex object will not be sterilize.If some thing complex structure then we have to prepare JSON data and we will produce as web services.

Default sterilization for list type and any object type:

In this scenario when we return some java object in custom method it will be automatically converted as JSON data. Here we need not do like this

Example for  Java Object to JSON data or JSON Object:

public class EmployeeServiceImpl extends EmployeeServiceBaseImpl {                         public  com.meera.jsonwebservices.db.model.Employee getEmployee(                                     long emplyeeId)                                     throws com.liferay.portal.kernel.exception.PortalException,                                                 com.liferay.portal.kernel.exception.SystemException {                                     return EmployeeLocalServiceUtil.getEmployee(emplyeeId);                         } }

In above custom method getEmplyee return Employee objects type. Here we need not to serialize the data and it will be converted as JSON data by default this is default behavior of liferay web services.

The following is URL to access method

http://localhost:8080/CustomJsonWebservices-portlet/api/jsonws/employee/get-employee?emplyeeId=1 OR http://localhost:8080/CustomJsonWebservices-portlet/api/jsonws/employee/get-employee/emplyeeId/1 result: {"employeeDesignation":"Software Engineer", "emplyeeId":1,"emplyeeName":"meera"}

Note:

In the above custom method return Employee object but finally object convereted as JSON data.

 Example for  List to JSON data

public class AddressServiceImpl extends AddressServiceBaseImpl {                       public  List<com.meera.jsonwebservices.db.model.Address> getAddressList(long emplyeeId)                                     throws com.liferay.portal.kernel.exception.PortalException,                                                 com.liferay.portal.kernel.exception.SystemException {                                     return AddressUtil.findByemplyeeId(emplyeeId);                         } }

In the above custom method return list of Address objects for particular employee id.

Here list will be converted as JSON data by default

The following is URL to call the above service

http://localhost:8080/CustomJsonWebservices-portlet/api/jsonws/address/get-address-list?emplyeeId=1 OR http://localhost:8080/CustomJsonWebservices-portlet/api/jsonws/address/get-address-list/emplyeeId/1 result: [{"employeeAddress":"Hyderabad","emplyeeId":1,"id":1}, {"employeeAddress":"Hong Kong","emplyeeId":1,"id":2}]

Here Address is our service class and getAddressList is custom method to give list of address objects for particular employee.

Here List will be converted as JSON array simple.

Some scenarios which data is complex then default sterilization not work all times when default sterilization not work then we will prepare JSON data manually in custom method. Scenarios like list have map objects and map have list objects.

Example for specialized structure:

Take our previous scenario one employee have many address but my data structure should be like follows

{         name:”meera”,        addresess:[                           “Hyderabad”,”Landon”,”Hong Kong”                         ] }

We can’t produce this same JSON data by default here we have to prepare JSON data manually from java objects.

The following is Example:

public class EmployeeServiceImpl extends EmployeeServiceBaseImpl {             public  JSONObject getEmployeeManualJsonData(                                     long emplyeeId)                                     throws com.liferay.portal.kernel.exception.PortalException,                                                 com.liferay.portal.kernel.exception.SystemException {                                                 JSONObject employeeData=JSONFactoryUtil.createJSONObject();                         JSONArray addressArray=JSONFactoryUtil.createJSONArray();                         Employee      empObject=EmployeeLocalServiceUtil.getEmployee(emplyeeId);                         employeeData.put("name",empObject.getEmplyeeName());                         for(Address empaddress:AddressUtil.findByemplyeeId(emplyeeId)){                                     addressArray.put(empaddress.getEmployeeAddress());                         }                         employeeData.put("addresess", addressArray);                                                             return employeeData;                         } }

Here service class is EmployeeServiceImpl.java it will be converts as employee in URL and method is getEmployeeManualJsonData it will be converted in URL as get-employee-manual-json-data

The following is URL to access above service

http://localhost:8080/CustomJsonWebservices-portlet/api/jsonws/employee/get-employee-manual-json-data?emplyeeId=1 OR http://localhost:8080/CustomJsonWebservices-portlet/api/jsonws/employee/get-employee-manual-json-data/emplyeeId/1 result: {"name":"meera","addresess":["Hyderabad","Hong Kong","Landon"]}

Note:

 liferay providing JSONFactoryUtil class from this we can create JSONArray and JSONObject.

By using above classes we can prepare JSON data manually in custom web service method.

Nested JSON web service Invoker:

We already know JSON Web service Invoker is one of the way to call web services in liferay.

Nested JSON web service invoker has ability serve data from multiple tables.

By using this we can get data from multiple tables which are related to each other.

Same above scenarios I want data fetch all addresses for employee by pass employeeId.

We can call following web service invoker to get employee address. From nested web service invoker we can achieve that.

The following is JSON map for fetch employee addresses

{ "$employee =/employee/get-employee": { "emplyeeId": 1, "$address = /address/get-address-list": { "@emplyeeId" : "$employee.emplyeeId" }  } }

@emplyeeId  at which parameter we pass to service call

$employee.emplyeeId   we will get employeeId from $employee reference object.

emplyeeId is same as column name  of entity which we mention in service.xml.

Observer above JSON Map:

First we need to fetch employee object and referenced by variable called $employee we use this employee object to get employeeId and this id will be passed to /address/get-address-list service call.

In the first service call i.e. /employee/get-employee   we will get employee object and referenced by variable, in the next service call i.e. /address/get-address-list we use this reference variable to get employeeId and that will passed as parameter value.

Here we are calling two service calls within one JSON Map object that is why we call it as Nested JSON Web Service Invoker.

Note:

Here all parameters which we passed in JSON map should be same as parameter names which we used in custom method implementation in XXXServiceImpl class.

The final web service call using Nested JSON web service invoke

http://localhost:8080/CustomJsonWebservices-portlet/api/jsonws/invoke ?cmd={"$employee =/employee/get-employee": {"emplyeeId": 1,"$address = /address/get-address-list": {"@emplyeeId" : "$employee.emplyeeId"} }} result: {"emplyeeId":1,"address":[{"employeeAddress":"Hyderabad","emplyeeId":1,"id":1}, {"employeeAddress":"Hong Kong","emplyeeId":1,"id":2}, {"employeeAddress":"Landon","emplyeeId":1,"id":3}], "emplyeeName":"meera","employeeDesignation":"Software Engineer"}

Filter columns in Nested JSON web service call

http://localhost:8080/CustomJsonWebservices-portlet/api/jsonws/invoke?cmd={"$employee[emplyeeName,emplyeeId]=/employee/get-employee": {"emplyeeId": 1,"$address[employeeAddress]= /address/get-address-list": {"@emplyeeId" : "$employee.emplyeeId"} }} result: {"emplyeeId":1,"address":[{"employeeAddress":"Hyderabad","emplyeeId":1,"id":1}, {"employeeAddress":"Hong Kong","emplyeeId":1,"id":2}, {"employeeAddress":"Landon","emplyeeId":1,"id":3}],"emplyeeName":"meera"}

In the above call we only get employeeId and employeeName from employee object.

Now calling JSON web service with portal context:

As of now we have used plugin portlet context for calling web services. We can also call web services using portal context/

The following is pattern to call from portal context:

.

http://[server]:[port]/[portal-context]/api/jsonws/[plugin-context].[service-class-name]/[service-method-name]

Note:

Conveniently, requests sent this way can leverage the user’s authentication in his current portal session. Liferay’s JavaScript API for services calls plugin services using this method.

The following is call web service from plugin context.

http://[server]:[port]/[plugin-context]/api/jsonws/[service-class-name]/[service-method-name]

Note:

This calls the plugin’s service in a separate web application that is not aware of the user’s current session in the portal. As a result, accessing the service in this manner requires additional authentication. You might use this for batch services or other requests that don’t require context.

The following are dependent properties related to JSON web service in liferay

jsonws.web.service.invalid.http.methods=DELETE,POST,PUT jsonws.web.service.strict.http.method=true json.service.auth.token.enabled=true json.service.auth.token.hosts.allowed=255.255.255.255 json.deserializer.strict.mode=false jsonws.web.service.public.methods=*

Note:

Please consider all above properties in your portal.properties file. If something you  want change you can use portal-ext.properties file to override.

Important points:

• Liferay provides two kinds of web services SOAP and REST.
• JSON web services is part REST bases web services which partially follows rest specifications.
• To implement service layer in liferay we will use service builder to and if we use remote- service is true then we can get data base services and JSON web services.
• Liferay web services serve only one table data by default.
• If we want get data which is related multiple tables or some specialize requirement we have to implement customer web services.
• To implement any custom services we will use XXXServiceImpl.java class.
• We can access JSON web services from simple URL pattern URL include plugin context, service class name, service method name and its parameters used by service method.
• We can pass parameter as query string or normal URL pattern so that each param and values should be separated by slash (/)
• We can access JSON web services using plug-in portlet context and portal context too. But difference is when we call from plug-in context we need implement our own authentication mechanism for services. If we use portal context then it will use authentication mechanism which provided by liferay portal.
• JSON web service invoker is way to call web services which will fetch data from multiple tables.
• To fetch data from multiple tables we have to implement custom method so that custom method prepares JSON data manually or we can use Nested JSON web service invoker.
• By default all java objects, list and map can be sterilize automatically and it will be produced as JSON data. Some scenarios if data has complex structure then we have to prepare JSON data manually.
• To prepare JSON data manually we can JSONFcatoryUtil class this can create JSONObject and JSONArray.

Screen 1:

The following screen depicts call JSON web services in browser and result will be JSON data.

Note:

In the URL host name and port number change according to you environment and in the web service URL pass your liferay admin username and password.

Reference Links:

http://www.liferay.com/documentation/liferay-portal/6.1/development/-/ai/json-web-services

http://www.liferay.com/community/wiki/-/wiki/Main/JSON+Web+Services

Author:

Meera Prince