Generating Staged Models Using Service Builder

This document has been updated and ported to Liferay Learn and is no longer maintained here.

A Staged model is an essential building block to implementing the Staging and Export/Import frameworks in your application. Instead of having to create staged models for your app manually, you can leverage Service Builder to generate the necessary staged model logic for you. Before diving into this tutorial, make sure you’ve read the Understanding Staged Models tutorial for information on how staged models work. Also, if your app doesn’t use Liferay’s Service Builder, you must configure it in your project. If you need help doing this, follow the Defining an Object-Relational Map with Service Builder tutorial.

This tutorial assumes you have a Service Builder project with *api and *service modules. If you want to follow along with this tutorial, download the staged-model-example Service Builder project. This is a bare-bones project that you can test to observe the Staging-related changes generated by running Service Builder. This tutorial assumes your project is built with Gradle. The example project’s service.xml file contains the following configuration:

<service-builder package-path="com.liferay.docs">
    <namespace>FOO</namespace>
    <entity local-service="true" name="Foo" remote-service="true" uuid="true">

        <!-- PK fields -->

        <column name="fooId" primary="true" type="long" />

        <!-- Group instance -->

        <column name="groupId" type="long" />

        <!-- Audit fields -->

        <column name="companyId" type="long" />
        <column name="createDate" type="Date" />
        <column name="modifiedDate" type="Date" />

        ...
        ...

    </entity>
</service-builder>

For simplicity, you’ll track the Service Builder-generated changes applied to an entity model file to observe how staged models are assigned to your entity. Keep in mind the specific staged attributes necessary for each staged model. Depending on the attributes defined in your service.xml file, Service Builder assigns your entity model to a specific staged model type.

1. Navigate to your project’s *service module at the command line. Run Service Builder (e.g., gradlew buildService) to generate your project’s models based on the current service.xml configuration.

2. Open your project’s [Entity]Model.java interface and observe the inherited interfaces.

   public interface FooModel extends BaseModel<Foo>, ShardedModel, StagedModel {
   

   Your model was generated as a staged model! This is because the UUID is set to true and the companyId, createDate, and modifiedDate columns are defined. There is much more logic generated for your app behind the scenes, but this shows that Service Builder deemed your entity eligible for the Staging and Export/Import frameworks.

3. Add the userId and userName columns to your service.xml file:

       <column name="userId" type="long" />
       <column name="userName" type="String" />
   

4. Rerun Service Builder and observe your [Entity]Model.java interface again:

   public interface FooModel extends BaseModel<Foo>, GroupedModel, ShardedModel,
       StagedAuditedModel {
   

   Your model is now a staged audited model!

5. Add the lastPublishDate column to your service.xml file:

   <column name="lastPublishDate" type="Date" />
   

6. Rerun Service Builder and observe your [Entity]Model.java interface again:

   public interface FooModel extends BaseModel<Foo>, ShardedModel,
       StagedGroupedModel {
   

   Your model is now a staged grouped model! The groupId column is also required to extend the StagedGroupedModel interface, but it was already defined in the original service.xml file.

Fantastic! You’ve witnessed firsthand how easy it is to generate staged models using Service Builder.