Toturial of Creating JSON Web Service using Service Builder

This article talks about how to create json web service based on Service Builder Service.
 
Knowledge: Service Builder
JSON Web Service
 
When we intent to make a service to be a web provider to serve json web service, we can utilize Service Builder to build our json web service.
We have an article to talk about how to use Service Builder to build.
 
Requirement:
I need to build a trading track system to record monthly trading.
I need to build a web service to pass data as JSON of my bank's monthly trading.
(Eventhough in real world the monthly data normally from a query rather than being save as a record, but let's make it like this)
 
Step 1, Define Your Entity and Service.
 
So first I need to build an entity and services from Service Builder. Please check Creating Service Builder MVC Portlet in Liferay 7 with Liferay IDE 3 blog as a guidance.
 
I call my project "monthly-trading".
Define our entity as following service.xml. Note that I set my remote-service to be "true".
<?xml version="1.0"?>
<!DOCTYPE service-builder PUBLIC "-//Liferay//DTD Service Builder 7.0.0//EN" "http://www.liferay.com/dtd/liferay-service-builder_7_0_0.dtd">

<service-builder package-path="monthly.trading">
    <namespace>Banking</namespace>
    <entity local-service="true" name="MonthlyTrading" remote-service="true" uuid="true">
        
        <!-- PK fields -->
        <column name="monthlyTradingId" primary="true" type="long" />

        <!-- Group instance -->
        <column name="groupId" type="long" />

       <!-- Audit fields -->
        <column name="companyId" type="long" />
        <column name="userId" type="long" />
        <column name="userName" type="String" />
        <column name="createDate" type="Date" />
        <column name="modifiedDate" type="Date" />

        <!-- Other fields -->
        <column name="year" type="int" />
        <column name="month" type="int" />
        <column name="volume" type="int" />

        <!-- Order -->
        <order by="asc">
            <order-column name="month" />
        </order>

        <!-- Finder methods -->

        <finder name="Year" return-type="Collection">
           <finder-column name="year" />
        </finder>

   </entity>
</service-builder>
 
Step 2 Build Your Service
 
Once you have finished, you can run buildService to build your service.
 
After all interfaces and impl has been generated, you can modify your LocalServiceImpl to add your own local service implementation.
In my example I simply added an add method in MonthlyTradingLocalServiceImpl ignoring all validation.
 
public MonthlyTrading addMonthlyTrading(int year, int month, int volume) {

    long pk = counterLocalService.increment();
    MonthlyTrading monthlyTrading = monthlyTradingPersistence.create(pk);
    monthlyTrading.setYear(year);
    monthlyTrading.setMonth(month);
    monthlyTrading.setVolume(volume);

    return monthlyTradingPersistence.update(monthlyTrading);

 }

 public List<MonthlyTrading> getMonthlyTradingByYear(int year) {
    return monthlyTradingPersistence.findByYear(year);
 }
 
Run buildService again to regenerate interfaces.
 
Now I can modify my ServiceImpl to call my LocalService.
@JSONWebService
 public MonthlyTrading addMonthlyTrading(int year, int month, int volume) {

    return monthlyTradingLocalService.addMonthlyTrading(year, month, volume);
 }

 @JSONWebService
 public List<MonthlyTrading> getMonthlyTradingByYear(int year) {
    return monthlyTradingLocalService.getMonthlyTradingByYear(year);
 }
 
Run buildService again and deploy.
 
By utilizing @JSONWebService Annotation, you can make you class to be whitelist/blacklist based, you can enable/igore a method in JSON web service.
For more detail please check Liferay Dev KB.
 
Best Practice tips:
It's a good practice to check user permission in Service Impl to make sure all remote service call is secure.
 
Step 3, Use Your Remote Service
 
Now you can navigate to http://localhost:8080/api/jsonws in your browser.
Choose "banking" in Context name.
Now the custom json web service is in the list.
 
 
You can find JavaScript Example, curl Example, URL Example after you invoke the service.
 
 
This is how we add a JSON web service through service builder.
 
Hope you enjoy it.
 
 
Workable jars for test: API, Service
 
Blogs
[...] Previously we have talked about how to create a soy portlet, how to use a 3rd party js lib(ChartJS) in SOY portlet, and how to use Liferay Service Builder to create a remote service(web service) in... [...] Read More