Understanding the Code Generated by Service Builder

Service Builder generates code to support your entities. The files listed under Local Service and Remote Service below are only generated for an entity that has both local-service and remote-service attributes set to true. Service Builder generates services for these entities in your application’s *-api and *-service modules in the packages you specified in service.xml. For example, here are the package paths for Liferay’s Bookmarks application:

• /guestbook-api/src/main/java/com/liferay/docs/guestbook
• /guestbook-service/src/main/java/com/liferay/docs/guestbook

The guestbook-api module’s interfaces define the Guestbook application API. The *-api module interfaces define the application’s persistence layer, service layer, and model layer. Whenever you compile and deploy the *-api module, all its classes and interfaces are packaged in a .jar file called PROJECT_NAME-api.jar in the module’s build/libs folder. Deploying this JAR to Liferay defines the API as OSGi services.

The guestbook-service module classes implement the guestbook-api module interfaces. The *-service module provides the OSGi service implementations to deploy to Liferay’s OSGi framework.

Next, examine the classes and interfaces generated for the entities you specified. Similar classes are generated for each entity, depending on how each entity is specified in the service.xml. Here are the three types of customizable classes:

• *LocalServiceImpl
• *ServiceImpl
• *Impl

The * represents the entity name in the classes listed above.

Here are the persistence, service, and model classes:

• Persistence

  • [ENTITY_NAME]Persistence: Persistence interface that defines CRUD methods for the entity such as create, remove, countAll, find, findAll, etc.
  • [ENTITY_NAME]PersistenceImpl: Persistence implementation class that implements [ENTITY_NAME]Persistence.
  • [ENTITY_NAME]Util: Persistence utility class that wraps [ENTITY_NAME]PersistenceImpl and provides direct access to the database for CRUD operations. This utility should only be used by the service layer; in your portlet classes, use the [ENTITY_NAME] class by referencing it with the @Reference annotation.

  

  Figure 1: Service Builder generates these persistence classes and interfaces for an example entity called *Event*. You shouldn't (and you won't need to) customize any of these classes or interfaces.

• Local Service (generated for an entity only if the entity’s local-service attribute is set to true in service.xml)

  • [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: it’s where you add your business logic. For any methods added here, Service Builder adds corresponding methods to the [ENTITY_NAME]LocalService interface 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. @abstract
  • [ENTITY_NAME]LocalServiceUtil: Local service utility class which wraps [ENTITY_NAME]LocalServiceImpl. This class is generated for backwards compatibility purposes only. Use the *LocalService class by referencing it with the @Reference annotation.
  • [ENTITY_NAME]LocalServiceWrapper: Local service wrapper which implements [ENTITY_NAME]LocalService. This class is designed to be extended and it lets you customize the entity’s local services.

Figure 2: Service Builder generates these service classes and interfaces. Only the [ENTITY_NAME]LocalServiceImpl (e.g., EventLocalServiceImpl for the Event entity) allows custom methods to be added to the service layer.

• Remote Service (generated for an entity only if an entity’s remote-service attribute is not set to false in service.xml)

  • [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]Service interface the next time you run it.
  • [ENTITY_NAME]ServiceBaseImpl: Remote service base implementation. This is an abstract class. @abstract
  • [ENTITY_NAME]ServiceUtil: Remote service utility class which wraps [ENTITY_NAME]ServiceImpl. This class is generated for backwards compatibility purposes only. Use the *Service class by referencing it with the @Reference annotation.
  • [ENTITY_NAME]ServiceWrapper: Remote service wrapper which implements [ENTITY_NAME]Service. This class is designed to be extended and it lets you customize the entity’s remote services.
  • [ENTITY_NAME]ServiceSoap: SOAP utility which the remote [ENTITY_NAME]ServiceUtil remote service utility can access.
  • [ENTITY_NAME]Soap: SOAP model, similar to [ENTITY_NAME]ModelImpl. [ENTITY_NAME]Soap is serializable; it does not implement [ENTITY_NAME].

• Model

  • [ENTITY_NAME]Model: Base model interface. This interface and its [ENTITY_NAME]ModelImpl implementation serve only as a container for the default property accessors Service Builder generates. Any helper methods and all application logic should be added to [ENTITY_NAME]Impl.
  • [ENTITY_NAME]ModelImpl: Base model implementation.
  • [ENTITY_NAME]: [ENTITY_NAME] model interface which extends [ENTITY_NAME]Model.
  • [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 [ENTITY_NAME]. This class is designed to be extended and it lets you customize the entity.

Figure 3: Service Builder generates these model classes and interfaces. Only `[ENTITY_NAME]Impl` (e.g., `EventImpl` for the Event entity) allows custom methods to be added to the service layer.

Note: *Util classes are generated for backwards compatibility purposes only. Your module applications should avoid calling the util classes. Use the non-util classes instead–you can reference them using the @Reference annotation.

Each file that Service Builder generates is assembled from an associated FreeMarker template. The FreeMarker templates are in the portal-tools-service-builder module’s src/main/resources/com/liferay/portal/tools/service/builder/dependencies/ folder. For example, Service Builder uses the service_impl.ftl template to generate the *ServiceImpl.java classes.

You can modify any *Impl class Service Builder generates. The most common are *LocalServiceImpl, *ServiceImpl and *Impl. If you modify the other classes, Service Builder overwrites the changes the next time you run it. Whenever you add methods to, remove methods from, or change a method signature of a *LocalServiceImpl class, *ServiceImpl class, or *Impl class, you should run Service Builder again to regenerate the affected interfaces and the service JAR.

Note: Service Builder may generate code that requires adding dependencies to your *-service module build file.

Note: When spring is the dependency injector (see Dependency Injector in Defining Global Service Information), the -LocalServiceBaseImpl classes Service Builder generates include -LocalService and -Persistence member fields of all the service.xml’s entities. -LocalServiceImpl classes inherit these fields and are Spring beans. The Spring beans can reference each other. For example, Spring bean A can have a Spring bean B field and vice versa. Liferay’s spring dependency injector accommodates Spring bean circular references. The ds dependency injector does not accommodate circular references.

When using ds as the dependency injector, -LocalServiceImpl classes are OSGi Declarative Services. Such services start only after all the other services they reference have started. If declarative service A has a declarative service B member field and vice versa, neither service can start. For this reason, the -LocalServiceBaseImpl classes Service Builder generates don’t include -LocalService member fields of the service.xml’s other entities. When using the ds dependency injector, you must make sure member fields you add to service classes don’t create circular dependencies.

Congratulations! You’ve generated your application’s initial model, persistence, and service layers and you understand the generated code.

Related Topics

Service Builder

Running Service Builder

Understanding Service Context

Creating Local Services