oo

Service Builder

An application without reliable business logic or persistence isn’t much of an application at all. Unfortunately, writing your own persistence code often takes a great deal of time. Service Builder is an object-relational mapping tool that can generate your model, persistence, and service layers from a single xml file. Once generated, the code is completely customizable: you can write your own persistence code along with custom SQL if necessary. Regardless of how you produce your persistence code, you can then use Service Builder to implement your app’s business logic.

Here, you’ll learn how to use Service Builder to

  • Generate and customize your persistence framework

  • Implement your business logic

When you configure your model and its relationships in your service.xml file and run Service Builder, it generates these layers of code:

  • Model layer: defines objects to represent your project’s entities.

  • Persistence layer: saves entities to and retrieves entities from the database.

  • Service layer: a blank layer ready for you to create your API and business logic.

Here are some key features:

  • Stubbed-out classes for implementing custom business logic

  • Hibernate configurations

  • Configurable caching support

  • Flexibility and support for adding custom SQL queries and dynamic queries

note

You don’t have to use Service Builder for your back-end services on DXP/Portal. It’s entirely possible to use your persistence framework of choice, such as JPA or Hibernate. Note that under the hood, Service Builder uses Hibernate.

Customization via Implementation Classes

Service Builder-generated entities contain these implementation classes:

  • Entity implementation (*Impl.java): Responsible for customizing the entity.

  • Local service implementation (*LocalServiceImpl.java): Responsible for calling the persistence layer to retrieve and store data entities. Local services contain the business logic and access the persistence layer. They can be invoked by client code running in the same Java Virtual Machine.

  • Remote service implementation (*ServiceImpl.java): Generated if the service.xml is configured for remote services. Remote services usually contain permission checking code and are meant to be accessible from outside the JVM. Service Builder automatically generates code that makes the remote services available via JSON or SOAP, and you can also create your own remote APIs through REST Builder or JAX-RS.

These classes are where you implement custom business logic. They’re the only classes generated by Service Builder intended for customization.

Hibernate Configurations

Service Builder uses the Hibernate persistence framework for object-relational mapping. Service Builder hides the complexities of Hibernate, while still giving you access to technology like dynamic queries and custom SQL. You can take advantage of Object-Relational Mapping (ORM) in your projects without having to set up a Hibernate environment manually or make any configurations.

Caching

Service Builder caches objects at three levels: entity, finder, and Hibernate. By default, Liferay uses Ehcache as an underlying cache provider for each of these cache levels. However, this is configurable via portal properties. All you must do to enable entity and finder caching in your project is to set the cache-enabled=true attribute of your entity’s <entity> element in your service.xml file. Liferay Clustering describes Liferay caching in a cluster.

Dynamic Query and Custom SQL Query

Service Builder automates many of the common tasks associated with creating database persistence code, but it doesn’t prevent you from creating custom SQL queries. You can define custom SQL queries in an XML file and implement finder methods to run the queries. If you have some crazy join to do, Service Builder gets out of your way. You can also use dynamic query to access Hibernate’s criteria API.

What’s Next

Service Builder is used exclusively throughout Liferay DXP and its applications, so it’s well-tested and robust. It saves lots of development time, both initial development time and time that would have to be spent maintaining, extending, or customizing a project. To get started, begin with Service Builder Basics.