forked from liferay/liferay-portal
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathportal-service-overview.html
180 lines (145 loc) · 9.46 KB
/
portal-service-overview.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
<!DOCTYPE html>
<!--
Copyright (c) 2000-present Liferay, Inc. All rights reserved.
This library is free software; you can redistribute it and/or modify it under
the terms of the GNU Lesser General Public License as published by the Free
Software Foundation; either version 2.1 of the License, or (at your option)
any later version.
This library is distributed in the hope that it will be useful, but WITHOUT
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more
details.
-->
<html>
<body>
<p>
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 <strong>Description</strong> link below to continue reading this overview.
</p>
<h2>The Liferay Public API Documentation</h2>
<p>
This documentation includes only those classes that should be used by portlet and plugin developers. These include:
</p>
<ul>
<li>Portal models and services</li>
<li>Built-in portlet models and services</li>
<li>The portal kernel and utilities</li>
</ul>
<p>
Let's condsider each of these and look at examples of each.
</p>
<h3>Portal Models and Services</h3>
<p>
The portal models (e.g. User, UserGroup, Role, ResourcePermission, ... etc.) are used throughout Liferay portal and are leveraged by portlets and plugins via services.
</p>
<p>
Example - Get a user model object from the local service:
</p>
<pre><code>import com.liferay.portal.service.UserLocalServiceUtil;
import com.liferay.portal.model.User;
...
User test_user = UserLocalServiceUtil.getUserByEmailAddress("test@liferay.com");</code></pre>
<h3>Built-in Portlet Models and Services</h3>
<p>
A host of powerful portlets are provided with Liferay. They consume portal services and have their own models and services.
</p>
<p>
Example - Subscribe to a Wiki page:
</p>
<pre><code>import com.liferay.portlet.wiki.service.WikiPageServiceUtil;
...
long nodeId = ParamUtil.getLong(actionRequest, "nodeId");
String title = ParamUtil.getString(actionRequest, "title");
WikiPageServiceUtil.subscribePage(nodeId, title);</code></pre>
<h3>The Portal Kernel and Utilities</h3>
<p>
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.
</p>
<p>
Example - Retrieve the list of available locales from a localizations XML fragment:
</p>
<pre><code>import com.liferay.portal.kernel.util.LocalizationUtil;
...
String xml;
String[] locales = LocalizationUtil.getAvailableLocales(xml);</code></pre>
<h3>Find out more ...</h3>
<p>
Continue reading for further description of ...
</p>
<ul>
<li>
<strong>Best Practices</strong> - Includes explanation of key software paradigms used in Liferay and best practices for using the API.</li>
<li>
<strong>Liferay Javadoc Initiative</strong> - Describes the Javadoc process underway at Liferay and provides links to packages containing documented classes that may be significant to your portlet and plugin development.</li>
</ul>
<h4>Best Practices Interfacing with the Liferay Kernel and Built-in Portlets</h4>
<p>
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.
</p>
<p>
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").
</p>
<p>
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.
</p>
<p>
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.
</p>
<p>
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.
</p>
<p>
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.
</p>
<h4>Liferay Javadoc Initiative</h4>
<p>
Liferay has started the process of writing high quality Javadoc that follows the <a href="http://www.liferay.com/community/wiki/-/wiki/Main/Javadoc+Guidelines" title="Liferay Javadoc Guidelines">Liferay Javadoc Guidelines</a> to ensure that documentation is clear, comprehensive, and helpful to you.
</p>
<p>
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:
</p>
<ul>
<li>
<a href="com/liferay/portal/kernel/bean/package-summary.html" title="com.liferay.portal.kernel.bean">com.liferay.portal.kernel.bean</a>
</li>
<li>
<a href="com/liferay/portal/kernel/exception/package-summary.html" title="com.liferay.portal.kernel.exception">com.liferay.portal.kernel.exception</a>
</li>
<li>
<a href="com/liferay/portal/kernel/portlet/package-summary.html" title="com.liferay.portal.kernel.portlet">com.liferay.portal.kernel.portlet</a>
</li>
<li>
<a href="com/liferay/portal/kernel/util/package-summary.html" title="com.liferay.portal.kernel.util">com.liferay.portal.kernel.util</a>
</li>
<li>
<a href="com/liferay/portal/model/package-summary.html" title="com.liferay.portal.model">com.liferay.portal.model</a>
</li>
<li>
<a href="com/liferay/portal/security/permission/package-summary.html" title="com.liferay.portal.security.permission">com.liferay.portal.security.permission</a>
</li>
<li>
<a href="com/liferay/portal/service/persistence/package-summary.html" title="com.liferay.portal.service.persistence">com.liferay.portal.service.persistence</a>
</li>
<li>
<a href="com/liferay/portal/service/package-summary.html" title="com.liferay.portal.service">com.liferay.portal.service</a>
</li>
<li>
<a href="com/liferay/portlet/asset/service/package-summary.html" title="com.liferay.portlet.asset.service">com.liferay.portlet.asset.service</a>
</li>
<li>
<a href="com/liferay/portlet/documentlibrary/service/package-summary.html" title="com.liferay.portlet.documentlibrary.service">com.liferay.portlet.documentlibrary.service</a>
</li>
<li>
<a href="com/liferay/portlet/documentlibrary/store/package-summary.html" title="com.liferay.portlet.documentlibrary.store">com.liferay.portlet.documentlibrary.store</a>
</li>
<li>
<a href="com/liferay/portlet/documentlibrary/util/package-summary.html" title="com.liferay.portlet.documentlibrary.util">com.liferay.portlet.documentlibrary.util</a>
</li>
<li>
<a href="com/liferay/portlet/social/service/package-summary.html" title="com.liferay.portlet.social.service">com.liferay.portlet.social.service</a>
</li>
</ul>
<p>
For more information for using, administering, and developing using Liferay, please consult the resources found at <a href="http://www.liferay.com/documentation/liferay-portal/6.2/community-resources" title="Liferay Community Resources">Liferay Community Resources</a>.
</p>
</body>
</html>