Liferay Service Builder Tags Detail Part-1

Objective:

Provide detailed information about service builder root level tags and usage.

Liferay service builder is tool to generate service layer to Plugin portlets. With minimal effort developer can develop service layer to portlet.

Liferay service builder generate many java service classes and Util classes from these classes we can do most of the curd operations.

How we will use service builder in Liferay Portlets?

• To use service builder tool in portlet we need to define service.xml file in portlet WEB-INF directory.
• Service builder will use certain predefined tags so that we have to define those tags in service.xml file
• All tags information will be available in liferay-service-builde_X_x.dtd file. Liferay have different versions of DTD files.
• Once we define everything in service.xml we need run ant build-service target form eclipse or command prompt
• Once we run ant target then all required service classes will be generated so that we can use these classes in portlet.

Assumption:

Assume we want create service builder to Student Entity so that we will generate many service classes and Util classes which will use to interact with data Student tables in data base

Example for define Entity in service.xml

<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE service-builder PUBLIC "-//Liferay//DTD Service Builder 6.1.0//EN" "http://www.liferay.com/dtd/liferay-service-builder_6_1_0.dtd"> <service-builder package-path="com.meera.sb"> <author>E5410</author> <namespace>SB</namespace> <entity name="Student" local-service="true" remote-service="true" > <!—Define columns tags --> <!—Define finder tags --> <!—Definde order tags --> </service-builder>

Note:

Whenever we use service builder we need to specify the service builder DTD file in DOCTYPE tag so that it will use the tags those defined in dtd file. This is very important when we use service builder tool.

The following are service builder tags and its attribute details

Service builder have following important root level tags

service-builder author namespace entity service-builder-import

service-builder

The parent tag in service.xml file is service-builder all tags which are related to service builder should enclosed by parent tag.

Attributes for service-builder tag:

packeage-path:  

This is specifying that where all service builder generated classes will be placed in given package path

Example:

<service-builder package-path="com.meera.sb"> <!—Define Enities tags --> </service-builder>

In above all service builder generated classes will be places in com.meera.sb base package.

author

This specify the author who is developing this service builder

namespace

Name space tag will used to avoid the name collegians between data base tables.

Assume some time we may have scenario tow portlet have same table name but columns are different.

If we don’t want use name space then existed tables override by another portlet table columns.

To avoid this we will use name space so that we can use same table in many portlets so that table name will be appended with name space

Example:

<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE service-builder PUBLIC "-//Liferay//DTD Service Builder 6.1.0//EN" "http://www.liferay.com/dtd/liferay-service-builder_6_1_0.dtd"> <service-builder package-path="com.meera.sb"> <author>E5410</author> <namespace>SB</namespace> <entity name="Student" local-service="true" remote-service="true" > <!—Define columns tags --> <!—Define finder tags --> <!—Definde order tags --> </service-builder>

Database Table Name= Name Space Tag Value + Entity Name

For above definition the Table Name will be SB_Student

Note:

To avoid Name space append to entity name we need to use table attribute in

enitity

Entity tag used to define the service layer entity class.  For each physical table we need entity definition in service.xml so that we can do data base operation on that table.

All entities are enclosed by <service-builder/> parent tag

Example:

<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE service-builder PUBLIC "-//Liferay//DTD Service Builder 6.1.0//EN" "http://www.liferay.com/dtd/liferay-service-builder_6_1_0.dtd"> <service-builder package-path="com.meera.sb"> <author>E5410</author> <namespace>SB</namespace> <entity> ----- ----- </entity> <entity> ----- ----- </entity> <entity> ----- ----- </entity> </service-builder>

Important Attributes for entity tag:

name              table local-service remote-service data-source session-factory tx-manager cache-enabled json-enabled

Name:

This specifies the name of the entity so that all service classes and model classes’ names will start with entity name.

Possible attribute values:

 Any String Value we can use as value better don’t use some special characters

Note:

This is mandatory attribute

Example:

<entity name="Student"> ---- ----- </entity>

table:

This specifies the name of the table in data base. Means the service layer service will do data base operations for given table.

Possible attribute values:

This is name of table in data base nothing but string value

Note:

This is optional attribute

Example:

<entity table="Student"> ---- ----- </entity>

Assume already table is existed in data bases for this we want use the service builder service then we have to table attribute in entity tag.

local-service:

This is Boolean value and this will generate the all service classes those we can use in local or within same application environment and the default value is false.

Possible attribute values:

It table Boolean values possible values can be true/false

Note:

This is optional attribute

Example:

<entity local-service="true/flase"> ---- ----- </entity>

remote-service:

When we want generate web service to the entity then we will use this attribute. The default value is false. This will generate SOAP and JSON REST web service to entity. When we want expose our data to other platforms as web service then we have to use this attribute.

Possible attribute values:

It table Boolean values possible values can be true/false

Note:

This is optional attribute

Example:

<entity remote-service="true/flase"> ---- ----- </entity>

data-source:

Liferay have given flexibility to define custom data sources for portlet so that we can specify the custom data source through this attribute.

This tells us in which data source our data base table is available. Default it will use liferay data source that is lportal data base to create table or access table.

Possible attribute values:

Name of the data source we configures for portlet.

Note:

This is optional attribute

Example:

<entity data-source="mydatasource"> ---- ----- </entity>

For More information please go through following links:

http://www.liferaysavvy.com/2013/08/liferay-plugin-portlet-connecting-to.html

session-factory:

This also similar to data source we can use custom session factory. When we want define our own session factory so that we can specify using this attribute so that persistence class loaded in specified session factory.

Possible attribute values:

Name of the session factory we configures for portlet.

Note:

This is optional attribute

Example:

<entity session-factory="mysessionfactory"> ---- ----- </entity>

For More information please go through following links:

http://www.liferaysavvy.com/2013/08/liferay-plugin-portlet-connecting-to.html

tx-manager:

This attribute specify that the entity/table whether use the transactions or not.

Possible attribute values:

 Name of transaction manager configured for portlet/none

If we use none value it won’t use transaction manager and by default every entity use the        liferay transaction manager specify in spring configuration files.

Note:

This is option attribute

Example:

<entity tx-manager="none/mytxmaneger"> ---- ----- </entity>

cache-enabled:

When want handle cache mechanism on entity then we have to use this attribute

Possible attribute values:

It will take true/false values.

This is option attribute and by default for all entities cache is implemented by service builder if we don’t want then we need to make it false value. Set the value to false if data in the table will be updated by other programs.

Note:

This is option attribute

Example:

<entity cache-enabled="true/flase"> ---- ----- </entity>

json-enabled :

The json-enabled value specifies whether or not the entity should be annotated

for JSON serialization. By default, if the remote-service value is true, then

The json-enabled value is true.

Example:

<entity json-enabled="true/flase"> ---- ----- </entity>

service-builder-import:

The service-builder-import allows you to split up a large Service Builder file

into smaller files by aggregating the smaller Service Builder into one file.

Note that there can be at most one author element among all the files. There can

Also only be one and only one namespace element among all the files.

Important Attribute for service-builder-import tag

file The attribute file is interpreted as relative to the file that is importing it.

  

Example

<service-builder-import file=”service.1xml”>

Note:

Some of the root tags have its child tags so I will post remaining child tags information on second part of the article

The following is sample example for service.xml

<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE service-builder PUBLIC "-//Liferay//DTD Service Builder 6.1.0//EN" "http://www.liferay.com/dtd/liferay-service-builder_6_1_0.dtd"> <service-builder package-path="com.meera.db"> <author>E5410</author> <namespace>meera</namespace> <entity name="Student" local-service="true" remote-service="true" cache-enabled="true"> <!-- PK fields --> <column name="studentId" type="long" primary="true" /> <!-- Audit fields --> <column name="studentName" type="String" /> <column name="studentPlace" type="String" /> <column name="studentCollege" type="String" /> <!-- Order --> <order by="asc"> <order-column name="studentId" /> </order> <!-- Finder methods --> <finder name="studentPlace" return-type="Collection"> <finder-column name="studentPlace" /> </finder> </entity> <entity name="Course" local-service="true" remote-service="true" cache-enabled="false"> <column name="courseId" type="long" primary="true" /> <!-- Audit fields --> <column name="courseName" type="String" /> <column name="courseGroup" type="String" /> <!-- Order --> <order by="asc"> <order-column name="courseId" /> </order> <!-- Finder methods --> <finder name="courseGroup" return-type="Collection"> <finder-column name="courseGroup" /> </finder> </entity> </service-builder>

Reference Links:

https://github.com/liferay/liferay-portal/blob/master/definitions/liferay-service-builder_6_2_0.dtd

Author

Meera Prince

Liferay Top Contributor Award Winner

http://www.liferaysavvy.com