About service.xml and Service Builder

Service Builder is Liferay's powerful code generation framework. You define your data model in service.xml, and Service Builder automatically generates your entire persistence layer — entity classes, DAO objects, finders, service interfaces, and more. It saves hundreds of lines of boilerplate code.

Why Use Service Builder?

• Automatic Code Generation: Entity classes, DAOs, finders, and service stubs — all generated from service.xml.
• Transaction Management: Built-in transaction boundaries and error handling.
• Finder Methods: Define custom queries once, Service Builder generates the methods.
• ORM Integration: Hibernat integration for database abstraction.
• Portlet Compatibility: Seamless integration with Liferay portlets and themes.
• Consistency: All generated code follows Liferay conventions and best practices.

The service.xml Structure

A service.xml file defines:

• Entity: The main data object (e.g., BlogEntry, Product, Order).
• Columns: The fields/properties of the entity (name, type, constraints).
• Finders: Custom query methods to retrieve entities (e.g., findByUserId, findByStatus).

Column Types

• String — Text up to 75k characters
• long — 64-bit integer (use for IDs)
• int — 32-bit integer
• double, float — Decimal numbers
• boolean — True/false
• Date — Date and time
• BigDecimal — Arbitrary precision numbers
• Blob, Clob — Large binary or text data

Example: Blog Entry Entity

Here's what a typical entity looks like:

How to Use This Generator

1. Name your entity: Use a descriptive singular name (BlogEntry, not BlogEntries).
2. Set the namespace: Your Java package path (e.g., com.liferay.blogs.service).
3. Add columns: Define each field with name, type, and constraints.
4. Add finders (optional): Define custom query methods (e.g., findByUserId).
5. Download service.xml: Copy or download the generated file.

After Generating service.xml

1. Place in your module: Put service.xml in your Liferay module root directory.
2. Run Service Builder: Execute the build service goal:
   gradle buildService
   or
   mvn liferay:build-service
3. Review generated code: Check the src/main/java folder for generated classes.
4. Use in your code: Import entity and service classes in your portlets, modules, and APIs.

System Columns (Auto-Generated)

Service Builder automatically adds these columns to every entity — no need to define them:

• mvccVersion — Multi-version concurrency control
• ctCollectionId — Change tracking collection ID
• uuid — Universally unique identifier
• createDate, modifiedDate — Audit timestamps
• companyId, groupId — Liferay instance and site

Frequently Asked Questions

What is service.xml?

service.xml is the configuration file for Liferay's Service Builder — a tool that generates ORM (object-relational mapping) code. You define your entity structure in service.xml, and Service Builder generates persistence layer code, finder methods, and a local/remote API.

What is Service Builder?

Service Builder is Liferay's code generation tool that turns a service.xml definition into a complete persistence layer with entity classes, finders, and service interfaces. It handles database schema creation, queries, and transaction management.

What should I do after downloading service.xml?

Place it in the root of your Liferay module project (same level as build.gradle, pom.xml, or bnd.bnd). Then run "liferay:build-service" (Maven) or "buildService" (Gradle) to generate the persistence code.

What column types are supported?

String, long, int, double, float, boolean, Date, BigDecimal, Blob, Clob. Use String for text, long for IDs, Date for timestamps, and Blob/Clob for large binary/text data.

What's a finder?

A finder is a generated query method. For example, a finder named "ByUserId" with returnType "Collection" generates a method "findByUserId(long userId)" that queries the database. It makes custom queries easy without writing SQL.

Do I need to define every column manually?

You should define the columns that matter to your business logic. Liferay automatically adds system columns like companyId, groupId, createDate, etc. during code generation. Focus on your entity's core fields.

Official Resources

• Service Builder Reference (Liferay Learn)
• Defining an Object-Oriented Data Model