This wiki does not contain official documentation and is currently deprecated and read only. Please try reading the documentation on the Liferay Developer Network, the new site dedicated to Liferay documentation. DISCOVER Build your web site, collaborate with your colleagues, manage your content, and more. DEVELOP Build applications that run inside Liferay, extend the features provided out of the box with Liferay's APIs. DISTRIBUTE Let the world know about your app by publishing it in Liferay's marketplace. PARTICIPATE Become a part of Liferay's community, meet other Liferay users, and get involved in the open source project. JSON Service API
Introduction #
This article describes the API provided by all Liferay services that allows invoking its methods directly through HTTP using JSON as a data serialization mechanisms. This API is automatically generated by Service Builder, which means that you can also provide it for your custom services developed in the extension environment with no extra effort.
How to generate the JSON API #
The JSON API is generated automatically from the remote service interface (for example, from ReportsEntryService) when "ant build-service" is executed for any given service.
Besides, a JavaScript file which contains a proxy for all the methods in that service is generated. This JavaScript file can be found in:
- (Portal Core) portal-web/docroot/html/js/liferay/service.js
- (Ext) extl-web/docroot/html/js/liferay/ext_service.js
Known limitations #
Not all Java types can be easily converted to and from JSON. Currently ServiceBuilder supports all native types and some object types. If a given method in the remote service does not get registered in service.js that means that some of its method parameter types were not supported.
Look for and open the file bad_json_types.txt within the sources of your specific version of Liferay to find out which types are not supported.
Invoking the JSON API #
From JavaScript #
Using the JSON Service API from a portlet using JavaScript cannot be any easier. As mentioned earlier, Service Builder automatically creates a file that encapsulates the invocation of the API methods through AJAX and makes it easy to process the response.
In order to be able to use the API the generated service.js file has to be included whenever the portlet is used. This can be done through regular HTML:
<script src="/html/js/liferay/service.js" language="JavaScript"> </script>
or for the extension environment:
<script src="/html/js/liferay/ext_service.js" language="JavaScript"> </script>
Or configured in liferay-portlet(-ext).xml so that it's added to the head of the HTML page.
Once the JavaScript file is available the methods of the service can be invoked using the following syntax:
Liferay.Service.NAMESPACE.ENTITY.METHOD(
{
PARAMETER_1: VALUE_1,
PARAMETER_2: VALUE_2
},
function(message) {
var exception = message.exception;
if (!exception) {
// Process Success
}
else {
// Process Exception
}
}NAMESPACE is the namespace of the service as specified within the service.xml file.
ENTITY is the name of the entity as specified in the 'entity' elements of the service.xml file. For exaple, to access the ReportsEntryService the name of the entity is ReportsEntry.
METHOD is the name of the method.
message.exception contains the name of the Java exception that may have been thrown by the service.
Resolving parameter type disambiguations #
Since JavaScript is untyped and Java is typed in some cases it's necessary to specify the type of a given parameter to make sure the proper method is invoked.
The JavaScript API allows specifying the Java types of the parameters through an special parameter called serviceParameterTypes. The value of this parameter should be a comma separated list of Java types (in 5.2 or earlier) or a JSON array of Java types (in 5.3 and later). Here is an example:
var serviceParameterTypes = [
'java.lang.String',
'[Ljava.lang.String;',
'com.liferay.portal.service.ServiceContext'
];
Liferay.Service.Asset.AssetTag.addTag(
{
name: tagName,
properties: [],
serviceContext: jQuery.toJSON(
{
communityPermissions: communityPermission,
guestPermissions: guestPermission,
scopeGroupId: themeDisplay.getScopeGroupId()
}
),
serviceParameterTypes: jQuery.toJSON(serviceParameterTypes)
},
...
);- Note: This example is valid for 5.3 and later. For earlier versions use:
serviceParameterTypes: serviceParameterTypes.join(',')serviceParameterTypes: jQuery.toJSON(serviceParameterTypes)
From any other language #
You can use any HTTP client and JSON serializer to access the service.
Example #
public class ReportsEntryServiceImpl extends ReportsEntryServiceBaseImpl {
public void print(String msg) {
System.out.println("ReportsEntryService: " + msg);
}
....
}This method could be invoked from a JSP using the following method (to make it simpler we are linking to the js file directly):
<script src="/html/js/liferay/ext_service.js" language="JavaScript"> </script>
<script language="JavaScript">
Liferay.Service.Reports.ReportsEntry.print(
{
msg: "Invoking a Liferay service via JavaScript",
},
function(message) {
var exception = message.exception;
if (!exception) {
// Process Success
}
else {
// Process Exception
}
}
);
</script>For a much more complete example, it's recommended to look at the Tags Admin and Categories Admin (from 5.3) portlets included with Liferay Portal.
