In the XML, the first thing defined is the portlet itself. Right under the root element <resource-action-mapping>, we have a child element called <portlet-resource>. In this element, we define the portlet name, which is 33 in our case. Next, we list all the actions this portlet supports under the <supports> tag. Keep in mind that this is at the portlet level. To understand what should be listed here, developers should ask themselves what actions belong to the portlet itself or what actions are performed on the portlet that may require a security check. In our case, users need permission to add an entry (ADD_ENTRY), configure blogs portlet settings (CONFIGURATION), and view the blogs itself (VIEW). Each of these supported permissions is within its own <action-key> tag. After we’ve defined all the actions that require a check, we move on to define some of the default permission settings. The community-defaults tag defines what actions are permitted by default for this portlet on the community (group) page the portlet resides. Put it another way, what should a user that has access to the community this portlet resides be able to do minimally? For the blogs portlet, a user with access to the community containing the blogs portlet should be able to view it. Likewise, the guest-defaults tag defines what actions are permitted by default to guests visiting a layout containing this portlet. So if a guest has access to the community page that contains a blogs portlet, the guest should, at the very least, be able to view the portlet according to blogs.xml (not necessarily the content of the portlet). Otherwise, the guest will see an error message within the portlet. Depending on your custom portlet, you may add more actions here that make sense. The guest-unsupported tag contains actions that a visiting guest should never be able to do. For example, the guest visiting the blogs portlet should never be able to add a blog entry since the blog belongs to either a user or a group of users. So even if a user wants to grant guests the ability to add a blog entry to her blog, there is no way for her to grant that permission because the blogs.xml doesn’t permit such an action for guests.

After defining the portlet as a resource, we move on to define models within the portlet that also require access check. The model resource is surrounded by the <model-resource> tag. Within this tag, we first define the model name. This must be the fully qualified Java class name of the model. Next we define the portlet name that this model belongs to under the portlet-ref tag. Though unlikely, a model can belong to multiple portlets, which you may use multiple <portlet-name> tags to define. Similar to the portlet resource element, the model resource element also allows you to define a supported list of actions that require permission to perform. You must list out all the performable actions that require a permission check. As you can see for a blog entry, a user must have permission in order to add comments to an entry, delete an entry, change the permission setting of an entry, update an entry, or simply to view an entry. The <community-defaults> tag, the <guest-defaults> tag, and the <guest-unsupported> tag are all similar in meaning to what’s explained for portlet resource in section 3.1.1.

After defining your permission scheme for your custom portlet, you then need to tell Liferay the location of this file. For Liferay core, the XML file would normally reside in portal/portal-ejb/classes/resource-actions and a reference to the file would appear in the default.xml file. For the extension environment, the recommended setup is to put your XML file in ext/ext-ejb/classes/resource-actions. Create a file called default-ext.xml and model it after the default.xml file. Add all your custom resource-action XML files in the default-ext.xml file. Then copy the property resource.actions.configs found in portal.properties and paste it into portal-ext.properties. Lastly, add a comma to the end of the property value and then add the path to your default-ext.xml file. (i.e. resource.actions.configs=resource-actions/default.xml,resource-actions/default-ext.xml) Below is an example of the default.xml file.

<?xml version="1.0"?>

<resource-action-mapping>
	<resource file="resource-actions/portal.xml" />
	<resource file="resource-actions/blogs.xml" />
	<resource file="resource-actions/bookmarks.xml" />
	<resource file="resource-actions/calendar.xml" />
	<resource file="resource-actions/communities.xml" />
	<resource file="resource-actions/documentlibrary.xml" />
	<resource file="resource-actions/imagegallery.xml" />
	<resource file="resource-actions/journal.xml" />
	<resource file="resource-actions/messageboards.xml" />
	<resource file="resource-actions/polls.xml" />
	<resource file="resource-actions/shopping.xml" />
	<resource file="resource-actions/wiki.xml" />
</resource-action-mapping>

If you would like to provide your user the ability to choose whether to add the default community permission and the guest permission for the resources within your custom portlet, Liferay has a custom JSP tag you may use to quickly add that functionality. Simply insert the <liferay-ui:input-permissions /> tag into the appropriate JSP and the checkboxes will show up on your JSP. Of course, make sure the tag is within the appropriate <form> tags.

To prevent having a lot of dead resources taking up space in the Resource_ database table, you must remember to remove them from the Resource_ table when the resource is no longer applicable. Simply call the deleteResource(…) method in ResourceLocalServiceUtil. Here’s an example of a blogs entry being removed:

ResourceLocalServiceUtil.deleteResource(
	entry.getCompanyId(), BlogsEntry.class.getName(),
	Resource.TYPE_CLASS, Resource.SCOPE_INDIVIDUAL,
	entry.getPrimaryKey().toString());

On the portlet level, no code needs to be written in order to have the permission system work for your custom portlet. Your custom portlet will automatically have all the permission features. If you’ve defined any custom permissions (supported actions) in your portlet-resource tag in section 3.1, those are automatically added to a list of permissions and users can readily choose them. Of course, for your custom permissions to have any value, you’ll need to show or hide certain functionality in your portlet. You can do that by checking the permission first before performing the intended functionality. This will be covered in section 3.4.

In order to allow a user to set permissions on the model resources, you will need to expose the permission interface to the user. This can be done by adding two Liferay UI tag to your JSP. The first one is the <liferay-security:permissionsURL> tag which returns a URL that takes the user to the page to configure the permission settings. The second tag is the <liferay-ui:icon> tag that shows a permission icon to the user. Below is an example found in the file view_entry_content.jsp.

<liferay-security:permissionsURL
	modelResource="<%= BlogsEntry.class.getName() %>"
	modelResourceDescription="<%= entry.getTitle() %>"
	resourcePrimKey="<%= entry.getPrimaryKey().toString() %>"
	var="entryURL"
/>

<liferay-ui:icon image="permissions" url="<%= entryURL %>" />

The attributes you need to provide to the first tag are modelResource, modelResourceDescription, resourcePrimKey, and var. The modelResource attribute is the fully qualified Java object class name. It then gets translated in Language.properties to a more readable name (underlined in red in figure 3.3.2.1).

model.resource.com.liferay.portlet.blogs.model.BlogsEntry=Entry

As for the modelResourceDescription attribute, you can pass in anything that best describes this model instance. In the example, the blogs title was passed in, which is reflected in figure 3.3.2.1 with the blue underline. The resourcePrimKey attribute is simply the primary key of your model instance. The var attribute is the variable name this URL String will get assigned to. This variable is then passed to the <liferay-ui:icon> tag so the permission icon will have the proper URL link. There’s also an optional attribute redirect that’s available if you want to override the default behavior of the upper right arrow link shown in figure 3.3.2.1. That is all you need to do to enable users to configure the permission settings for model resources!!

Similar to the other steps, the default permissions for the portlet resources are automatically checked for you. You do not need to implement anything for your portlet to discriminate whether a user is allowed to view or to configure the portlet itself. However, you do need to implement any custom permission you have defined in your resource-actions XML file. In the blogs portlet example, one custom supported action is ADD_ENTRY. There are two places in the source code that check for this permission. The first one is in the file view_entries.jsp. The presence of the add entry button is contingent on whether the user has permission to add entry (and also whether the user is in tab one).

<%
boolean showAddEntryButton = tabs1.equals("entries") && PortletPermission.contains(permissionChecker, plid, PortletKeys.BLOGS, ActionKeys.ADD_ENTRY);
%>

The second place that checks for the add entry permission is in the file BlogsEntryServiceImpl. (Notice the difference between this file and the BlogsEntryLocalServiceImpl.) In the addEntry(…) method, a call is made to check whether the incoming request has permission to add entry.

PortletPermission.check(
	getPermissionChecker(), plid, PortletKeys.BLOGS,
	ActionKeys.ADD_ENTRY);

If the check fails, it throws a PrincipalException and the add entry request aborts. You’re probably wondering what the PortletPermission class and the PermissionChecker class do. Let’s take a look at these two classes.

public BlogsEntry addEntry(
		String plid, String categoryId, String[] tags, String title,
		String content, int displayDateMonth, int displayDateDay,
		int displayDateYear, int displayDateHour, int displayDateMinute,
		boolean addCommunityPermissions, boolean addGuestPermissions)
throws PortalException, SystemException {
	
	PortletPermission.check(
		getPermissionChecker(), plid, PortletKeys.BLOGS,
		ActionKeys.ADD_ENTRY);

	return BlogsEntryLocalServiceUtil.addEntry(
		getUserId(), plid, categoryId, tags, title, content,
		displayDateMonth, displayDateDay, displayDateYear, displayDateHour,
		displayDateMinute, addCommunityPermissions, addGuestPermissions);
}

Checking model resource permission is very similar to checking portlet resource permission. The only major difference is that instead of calling methods found in the PortletPermission class mention previously, you need to create your own helper class to assist you in checking permission. The next section will detail how this is done.

public class BlogsEntryPermission {

	public static void check(
			PermissionChecker permissionChecker, String entryId,
			String actionId)
		throws PortalException, SystemException {

		if (!contains(permissionChecker, entryId, actionId)) {
			throw new PrincipalException();
		}
	}

	public static void check(
			PermissionChecker permissionChecker, BlogsEntry entry,
			String actionId)
		throws PortalException, SystemException {

		if (!contains(permissionChecker, entry, actionId)) {
			throw new PrincipalException();
		}
	}

	public static boolean contains(
			PermissionChecker permissionChecker, String entryId,
			String actionId)
		throws PortalException, SystemException {

		BlogsEntry entry = BlogsEntryLocalServiceUtil.getEntry(entryId);

		return contains(permissionChecker, entry, actionId);
	}

	public static boolean contains(
			PermissionChecker permissionChecker, BlogsEntry entry,
			String actionId)
		throws PortalException, SystemException {

		return permissionChecker.hasPermission(
			entry.getGroupId(), BlogsEntry.class.getName(),
			entry.getPrimaryKey().toString(), actionId);
	}
}

public BlogsEntry getEntry(String entryId) throws PortalException, SystemException {

	BlogsEntryPermission.check(
		getPermissionChecker(), entryId, ActionKeys.VIEW);

	return BlogsEntryLocalServiceUtil.getEntry(entryId);
}

<c:if test="<%= BlogsEntryPermission.contains(permissionChecker, entry, ActionKeys.UPDATE) %>">
	<portlet:renderURL windowState="<%= WindowState.MAXIMIZED.toString() %>" var="entryURL">
		<portlet:param name="struts_action" value="/blogs/edit_entry" />
		<portlet:param name="redirect" value="<%= currentURL %>" />
		<portlet:param name="entryId" value="<%= entry.getEntryId() %>" />
	</portlet:renderURL>

	<liferay-ui:icon image="edit" url="<%= entryURL %>" />
</c:if>