The Liferay public API documentation describes the packages and classes used by portlet and plugin developers and provides a general overview of the API, best practices for using the API, and information about Liferay's ongoing Javadoc initiative; select the Description link below to continue reading this overview.
This documentation includes only those classes that should be used by portlet and plugin developers. These include:
Let's condsider each of these and look at examples of each.
The portal models (e.g. User, UserGroup, Role, ResourcePermission, ... etc.) are used throughout Liferay portal and are leveraged by portlets and plugins via services.
Example - Get a user model object from the local service:
import com.liferay.portal.service.UserLocalServiceUtil;
import com.liferay.portal.model.User;
...
User test_user = UserLocalServiceUtil.getUserByEmailAddress("test@liferay.com");A host of powerful portlets are provided with Liferay. They consume portal services and have their own models and services.
Example - Subscribe to a Wiki page:
import com.liferay.portlet.wiki.service.WikiPageServiceUtil;
...
long nodeId = ParamUtil.getLong(actionRequest, "nodeId");
String title = ParamUtil.getString(actionRequest, "title");
WikiPageServiceUtil.subscribePage(nodeId, title);The portal kernel acts as a bridge connecting the models and services of the portal and portlets with the application server. The kernel leverages services supporting EJB, dependency injection (Spring), a persistence framework (Hibernate), and business logic and workflow (JBPM). It provides adapters to popular languages such as PHP, Python, and Ruby. Lastly, the Liferay comes with utilities used by Liferay portal, portlets, and plugins.
Example - Retrieve the list of available locales from a localizations XML fragment:
import com.liferay.portal.kernel.util.LocalizationUtil;
...
String xml;
String[] locales = LocalizationUtil.getAvailableLocales(xml);Continue reading for further description of ...
The hot-pluggable nature of Liferay portlets and plugins imposes certain restrictions on the parts of the Liferay core they can access. These limitations allow for the least disruptive upgrades to both the core and plugins while also allowing the greatest flexibility in modifying core Liferay features without requiring a portal restart.
Most classes in Liferay follow a simple, but extremely important hierarchy. The public methods are defined in an interface, such as "Portal". This interface is then implemented in a class of the same name but with the suffix "Impl" appended ("PortalImpl"). A single instance of this implementation class is then stored inside a static wrapper class with the suffix "Util" ("PortalUtil").
The hierarchy of different types of classes will often diverge significantly from this paradigm (particularly for models and services), the basic structure remains the same. The reasons for this system are explained in more detail later, but the end result is that whenever possible, classes should only be referenced by their interfaces and accessed via their utilities. If you are interested in a more detailed explanation keep reading, otherwise skip to the examples section.
The first cause for this pattern is that servlet containers (such as Apache Tomcat) place the core and plugins within separate class loaders. This means that any classes shared between the two must be placed in the global class loader for the servlet container. Classes within the global class loader cannot be reloaded without restarting the servlet container, whereas classes inside servlets (such as the Liferay kernel and plugins) are monitored for changes on disk and reloaded whenever necessary. Thus, flexibility mandates that as little as possible be placed in the global class loader. However, all the functionality of the core must still be accessible within portlets.
Liferay solves this problem using the class hierarchy. All the core interfaces and utilities are placed in the global class loader, while their implementations are placed inside the portal servlet. This allows the portal to be modified in place, while still maintaining a consistent interface for plugins.
One other reason for the separation between interface, implementation, and utility is that Liferay makes extensive use of the Spring framework to the support dynamic injection and replacement of implementation classes in utilities. This means that it is possible in Liferay to completely replace many built-in classes with your own implementations at runtime. By placing core classes within a static utility wrapper, you can dynamically modify Liferay's behavior without the portal or other plugins needing to do anything.
Liferay has started the process of writing high quality Javadoc that follows the Liferay Javadoc Guidelines to ensure that documentation is clear, comprehensive, and helpful to you.
Not all classes have been documented, but the number of classes is growing. Some of the most significant services and classes documented that you may need are the following packages:
For more information for using, administering, and developing using Liferay, please consult the resources found at Liferay Community Resources.