Adding Custom Finder Methods in Liferay Service Builder

Liferay’s Service Builder is a powerful tool for creating database-backed services. In many real-world applications, you need to fetch data using custom criteria. This guide walks you through creating custom finder methods using Liferay's Service Builder with full detail.

🧰 Prerequisites

• Liferay Workspace (7.x or DXP)
• Blade CLI or IDE (e.g., IntelliJ or Eclipse)
• Basic knowledge of Service Builder

📦 Step 1: Create a Service Builder Module

blade create -t service-builder -p com.example.custom -c Example example-finder

This will create three modules:

• example-finder-api
• example-finder-service
• example-finder

📝 Step 2: Define the Entity in service.xml

Edit example-finder-service/src/main/resources/META-INF/service.xml:

<entity name="Employee" local-service="true" remote-service="false" table="Employee">
  <column name="employeeId" type="long" primary="true" />
  <column name="name" type="String" />
  <column name="department" type="String" />
</entity>

After updating, run:

./gradlew buildService

🔍 Step 3: Create a Custom Finder Method

➡️ 3.1 Create Method in EmployeeFinder Interface

File: example-finder-api/src/main/java/com/example/custom/service/persistence/EmployeeFinder.java

package com.example.custom.service.persistence;

import java.util.List;
import com.example.custom.model.Employee;

public interface EmployeeFinder {
    List<Employee> findByDepartment(String department);
}

➡️ 3.2 Implement in EmployeeFinderImpl

File: example-finder-service/src/main/java/com/example/custom/service/persistence/impl/EmployeeFinderImpl.java

package com.example.custom.service.persistence.impl;

import com.example.custom.model.Employee;
import com.example.custom.service.persistence.EmployeeFinder;
import com.liferay.portal.kernel.dao.orm.*;
import com.liferay.portal.kernel.service.persistence.impl.BasePersistenceImpl;
import org.osgi.service.component.annotations.Component;

import java.util.List;

@Component(service = EmployeeFinder.class)
public class EmployeeFinderImpl extends BasePersistenceImpl<Employee> implements EmployeeFinder {

    public List<Employee> findByDepartment(String department) {
        Session session = null;

        try {
            session = openSession();

            String sql = "SELECT * FROM Employee WHERE department = ?";
            SQLQuery query = session.createSQLQuery(sql);
            query.setCacheable(false);
            query.addEntity("Employee", getModelClass());
            query.setString(0, department);

            return query.list();

        } catch (Exception e) {
            e.printStackTrace();
            throw new RuntimeException("Failed to execute custom finder", e);
        } finally {
            closeSession(session);
        }
    }
}

🔗 Step 4: Access Custom Finder from LocalServiceImpl

Use the finder in EmployeeLocalServiceImpl.java:

public List<Employee> getEmployeesByDepartment(String department) {
    return employeeFinder.findByDepartment(department);
}

📌 Step 5: Build and Deploy

./gradlew buildService
./gradlew deploy

🧪 Step 6: Test Your Custom Finder

Call your service method using:

• REST endpoint (if exposed)
• JSP/React portlet
• Integration test

📘 Summary

• We created a custom finder in Liferay using Service Builder
• Used raw SQL and the BasePersistenceImpl class
• Injected and called it in the service layer

🔗 Useful Links

• Liferay Developer Documentation
• Liferay Portal Docs