This tutorial explains how to run Service Builder and provides an overview of
the code that Service Builder generates. If you’d like to use Service Builder in
your application but haven’t yet created a
service.xml file, visit the
Defining an Object-Relational Map with Service Builder
tutorial and then come back to this one.
Running Service Builder
To build a service from a
service.xml file, you can use Liferay Developer Studio or a
terminal window. In this tutorial, you’ll refer to the Event Listing example
project that’s referenced throughout the Liferay Service Builder tutorials.
Now let’s learn how to run Service Builder.
Using Liferay Developer Studio
From the Package Explorer, open the
service.xml file from your
module’s root folder. By default, the file opens up in the Service Builder
Editor. Make sure you are in Overview mode. Then click the Build Services
button () near the
top-right corner of the view.
Make sure to click the Build Services button and not the Build WSDD button () that appears next to it. Building the WSDDs won’t hurt anything, but you’ll generate files for the remote service instead of the local one. For information about WSDDs (web service deployment descriptors), please refer to the SOAP Web Services tutorial.
Another simple way to run Service Builder is to right-click on your project’s name in the Package Explorer and then select Liferay → build-service.
After running Service Builder, your generated files are available. More information about the generated files appears below.
Using the Terminal
Open a terminal window and navigate to your module project’s root folder, which
should be located in your Liferay Workspace’s
modules directory. To learn more
about creating your module project in a
Creating Modules with Blade CLI
tutorial. You can leverage the
Service Builder Template
to create your own predefined Service Builder project.
Liferay Workspace offers a Gradle or Maven build environment; this tutorial shows how to use both. Liferay is tool agnostic, however, and you can use other tools, as well.
For Gradle projects, enter the following command in your module project’s root folder to build your services:
If your module project uses Maven, you can build services running the following command from the module project’s root folder:
mvn service-builder:build command only works if you’re
com.liferay.portal.tools.service.builder plugin version 1.0.145+.
Maven projects using an earlier version of the Service Builder plugin should
update their POM accordingly. See the
Using Service Builder in a Maven Project
tutorial for more information on using Maven to run Service Builder.
When the service has been successfully generated, a
BUILD SUCCESSFUL message
appears in your terminal window. You should also see that a large number of
files have been generated in your project. These files include a model layer,
service layer, and persistence layer. Don’t worry about the number of generated
files–you’ll never have to customize more than three of them. To review the
code that Service Builder generates for your entities, see the next section.
Understanding the Code Generated by Service Builder
Now you’ll examine the files Service Builder generated for your entity. Note
that the files listed under Local Service and Remote Service below are only
generated for an entity that has both
attributes set to
true. Service Builder generates services for these entities
in two locations in your project. These locations use the package path that you
specified in your
service.xml file. For Liferay’s Bookmarks application, for
example, these two locations are the following ones:
bookmarks-api module contains the API for the Bookmarks project. All the
classes and interfaces in the
*-api module are packaged in a
PROJECT_NAME-api.jar in the module’s
build/libs folder. This
file is generated whenever you compile and deploy your module. When deploying
this JAR to Liferay, the necessary interfaces to define the service API are
bookmarks-service module contains the implementation of the interfaces
defined in the
bookmarks-api module. These interfaces provide OSGi services
for the portal instance to which your application is deployed. Service Builder
generates classes and interfaces belonging to the persistence layer, service
layer, and model layer in the
Now you’ll look at the classes and interfaces generated for the entities you
specified. Each entity has similar classes generated for it, depending on what
you specfied for them in the
service.xml. You won’t have to customize more
than three classes for each entity. These customizable classes are
[ENTITY_NAME]Persistence: Persistence interface that defines CRUD methods for the entity such as
[ENTITY_NAME]PersistenceImpl: Persistence implementation class that implements
[ENTITY_NAME]Util: Persistence utility class that wraps
[ENTITY_NAME]PersistenceImpland provides direct access to the database for CRUD operations. This utility should only be used by the service layer; in your portlet classes, use
Local Service (generated for an entity only if an entity’s
local-serviceattribute is set to
[ENTITY_NAME]LocalService: Local service interface.
[ENTITY_NAME]LocalServiceImpl(LOCAL SERVICE IMPLEMENTATION): Local service implementation. This is the only class in the local service that you should modify manually. You can add custom business logic here. For any custom methods added here, Service Builder adds corresponding methods to the
[ENTITY_NAME]LocalServiceinterface the next time you run it.
[ENTITY_NAME]LocalServiceBaseImpl: Local service base implementation. This is an abstract class. Service Builder injects a number of instances of various service and persistence classes into this class.
[ENTITY_NAME]LocalServiceUtil: Local service utility class which wraps
[ENTITY_NAME]LocalServiceImpland serves as the primary local access point to the service layer.
[ENTITY_NAME]LocalServiceWrapper: Local service wrapper which implements
[ENTITY_NAME]LocalService. This class is designed to be extended and it allows developers to customize the entity’s local services.
Remote Service (generated for an entity only if an entity’s
remote-serviceattribute is not set to
[ENTITY_NAME]Service: Remote service interface.
[ENTITY_NAME]ServiceImpl(REMOTE SERVICE IMPLEMENTATION): Remote service implementation. This is the only class in the remote service that you should modify manually. Here, you can write code that adds additional security checks and invokes the local services. For any custom methods added here, Service Builder adds corresponding methods to the
[ENTITY_NAME]Serviceinterface the next time you run it.
[ENTITY_NAME]ServiceBaseImpl: Remote service base implementation. This is an abstract class.
[ENTITY_NAME]ServiceUtil: Remote service utility class which wraps
[ENTITY_NAME]ServiceImpland serves as the primary remote access point to the service layer.
[ENTITY_NAME]ServiceWrapper: Remote service wrapper which implements
[ENTITY_NAME]Service. This class is designed to be extended and it allows developers to customize the remote entity’s services.
[ENTITY_NAME]ServiceSoap: SOAP utility which the remote
[ENTITY_NAME]ServiceUtilremote service utility can access.
[ENTITY_NAME]Soap: SOAP model, similar to
[ENTITY_NAME]Soapis serializable; it does not implement
[ENTITY_NAME]Model: Base model interface. This interface and its
[ENTITY_NAME]ModelImplimplementation serve only as a container for the default property accessors generated by Service Builder. Any helper methods and all application logic should be added to
[ENTITY_NAME]ModelImpl: Base model implementation.
[ENTITY_NAME]: [ENTITY_NAME] model interface which extends
[ENTITY_NAME]Impl: (MODEL IMPLEMENTATION) Model implementation. You can use this class to add helper methods and application logic to your model. If you don’t add any helper methods or application logic, only the auto-generated field getters and setters are available. Whenever you add custom methods to this class, Service Builder adds corresponding methods to the
[ENTITY_NAME]interface the next time you run it.
[ENTITY_NAME]Wrapper: Wrapper, wraps
Each file that Service Builder generates is assembled from an associated
FreeMarker template. You can find Service Builder’s FreeMarker templates in the
module. For example, if you want to find out how a
*ServiceImpl.java file is generated, just look at the
Of all the classes generated by Service Builder, only three should be manually
*Impl. If you manually
modify the other classes, your changes are overwritten the next time you run
Service Builder. Whenever you add methods to, remove methods from, or change a
method signature of a
*ServiceImpl class, or
*Impl class, you should run Service Builder again to regenerate the affected
interfaces and the service JAR.
Congratulations! You’ve generated your application’s initial model, persistence, and service layers and you understand the generated code.
Running Service Builder and Understanding the Generated Code