Distributed Caching

Liferay uses Ehcache, which has robust distributed caching support. This means that the cache can be distributed across multiple Liferay nodes running concurrently. Enabling this cache can increase performance dramatically. For example, say that two users are browsing the message boards. The first user clicks a thread in order to read it. Liferay must look up that thread from the database and format it for display in the browser. With a distributed Ehcache running, this thread is stored in a cache for quick retrieval, and that cache is then replicated to the other nodes in the cluster. Say then that the second user who is being served by another node in the cluster wants to read the same forum thread and clicks on it. This time, the data is retrieved more quickly. Because the thread is in the cache, no trip to the database is necessary.

This is much more powerful than having a cache running separately on each node. The power of distributed caching allows for more functionality. The first user can post a message to the thread he or she was reading, and the cache is updated across all the nodes, making the new post available immediately from the local cache. Without that, the second user would need to wait until the cache was invalidated on the node he or she connected to before he or she could see the updated forum post.

There are two ways to enable distributed caching. If you use the default settings, it's very easy. If you need to tweak the cache for your site, there are a few more steps, but it's still pretty easy.

Enabling distributed caching

The super-easy way of enabling distributed caching is simply to enable Cluster Link. If you've already done this to enable distributed search engine indexes, then your job is already done. What this does is enable some RMI (Remote Method Invocation) cache listeners that are designed to replicate the cache across a cluster.

Once you enable distributed caching, of course, you should do some due diligence and test your system under a load that best simulates the kind of traffic that your system needs to handle. If you'll be serving up a lot of message board messages, your script should reflect that. If web content is the core of your site, your script should reflect that too.

As a result of a load test, you may find that the default distributed cache settings aren't optimized for your site. In this case, you'll need to tweak the settings yourself. You can modify the Liferay installation directly or you can use a plugin to do it. Either way, the settings you change are the same. Let's see how to do this with a plugin first.

Modifying the cache settings with a plugin

A benefit of working with plugins is that you can quickly install a plugin on each node of your cluster without taking down the cluster. We'll cover this first. If you're not a developer, don't worry--even though you'll create a plugin, you won't have to write any code.

Since we're assuming you're an administrator and not a developer, we'll take the easiest route, and use Liferay's graphical development tools, rather than the command line Plugins SDK by itself. If you're a Liferay EE customer, download Liferay Developer Studio from the Customer Portal. Set it up with all the defaults from the first start wizard, and you're good to go (skip the next paragraph).

If you're not a Liferay EE customer, download Eclipse and install Liferay IDE from the Eclipse Marketplace. Download the Plugins SDK for your edition of Liferay from either the Customer Portal (EE) or the Downloads page on liferay.com. Connect Liferay IDE to your Plugins SDK using the instructions found in the Liferay Developer's Guide.

Next, create a hook plugin by selecting File → New → Liferay Project. Select Hook as the project type and give your project a name. Click Finish, and your project is created.

In your project, create a text file called portlet.properties in the docroot/WEB-INF/src folder. This file can override properties in your portal just like portal-ext.properties. Into this file place the following three properties:

net.sf.ehcache.configurationResourceName=
ehcache.single.vm.config.location=
ehcache.multi.vm.config.location=

Liferay's configuration files are, of course, used by default. If you're overriding these properties, it's because you want to customize the configuration for your own site. A good way to start with this is to extract Liferay's configuration files and then customize them. If you're running an application server (such as Tomcat) that allows you to browse to the running instance of Liferay, you can extract Liferay's configuration files from Liferay itself. If you're not, you can extract them from Liferay's .war file or Liferay's source code. In either place, you'll find the files in the portal-impl.jar file, which is in Liferay's WEB-INF/lib folder. The files you want are hibernate-clustered.xml, liferay-single-vm.xml, and liferay-multi-vm-clustered.xml, and they'll be in the /ehcache folder in this .jar. Once you have these, make a subfolder of the docroot folder in your project. Place the files you extracted into this folder, and then specify this folder in the properties above.

For example, if you created a folder called custom_cache in your project's docroot folder, you'd copy the three XML configuration files (hibernate-clustered.xml, liferay-single-vm.xml, and liferay-multi-vm-clustered.xml) there. Then you'd edit your portlet.properties and specify your configuration files in the three properties above:

net.sf.ehcache.configurationResourceName=/custom_cache/hibernate-clustered.xml
ehcache.single.vm.config.location=/custom_cache/liferay-single-vm.xml
ehcache.multi.vm.config.location=/custom_cache/liferay-multi-vm-clustered.xml

Save the file and deploy the plugin (deploying plugins is covered in the Liferay Developer's Guide), and the settings you've placed in those files will override the default Liferay settings. In this way, you can tweak your cache settings so that your cache performs optimally for the type of traffic generated by your site. The strength of doing it this way is that you don't have restart your server to change the cache settings. This is a great benefit, but beware: since Ehcache doesn't allow for changes to cache settings while the cache is alive, reconfiguring a cache while the server is running will flush the cache.

There is, of course, another way to do this if you don't want to create a plugin. It requires you to restart the server to enable the new cache settings, but you don't have to work with any developer tools to do it.

Modifying the Ehcache settings directly

This method is pretty similar to the plugin method, except that you have to modify the Liferay installation directly. You'll still need to extract Liferay's configuration files as described in the previous section. Next, shut down your server and find the location in the server where Liferay is installed (this may not be possible on all application servers, and if this is the case, you'll need to use the plugin method described above). For example, say you're running Liferay on Tomcat. Tomcat stores the deployed version of Liferay in [Tomcat Home]/webapps/ROOT. Inside this folder is the folder structure WEB-INF/classes. You can create a new folder in here called custom_cache to store the custom versions of the cache configuration files. Copy the files you extracted from Liferay into this folder.

You then need to modify the properties in portal-ext.properties that point to these files. Copy/paste the Hibernate section of portal.properties into your portal-ext.properties file and then modify the net.sf.ehcache.configurationResourceName property to point to the clustered version of the configuration file that is now in your custom folder:

net.sf.ehcache.configurationResourceName=/custom_cache/hibernate-clustered.xml

Now that Liferay is pointing to your custom file, you can modify the settings in this file to change the cache configuration for Hibernate.

Next, copy/paste the Ehcache section from the portal.properties file into your portal-ext.properties file. Modify the properties so that they point to the files that are in your custom folder. For example:

ehcache.multi.vm.config.location=/custom_cache/liferay-multi-vm-clustered.xml

You can now take a look at the settings in these files and tune them to fit your environment and application. Let's examine how to do that next.

Customizing Hibernate cache settings

By default, Hibernate (Liferay's database persistence layer) is configured to use Ehcache as its cache provider. This is the recommended setting. If you're using the default settings using Cluster Link, you already have this enabled. If, however, you need to customize the settings, you'll have to customize it in one of the ways described above: either in a plugin or in the deployed instance of Liferay. The first thing, of course, is to start off with the clustered version of the file. Copy the hibernate-clustered.xml configuration file to your plugin or to a place in Liferay's classpath (as described above) where you can refer to it. Then change the following property to point to the file:

net.sf.ehcache.configurationResourceName=/path/to/hibernate-clustered.xml

Next, open this file in a text editor. You'll notice that the configuration is already set up to perform distributed caching through a multi-cast connection. The configuration, however, might not be set up optimally for your particular application. Notice that by default, the only object cached in the Hibernate cache is the User object (com.liferay.`portal`.model.impl.UserImpl). This means that when a user logs in, his or her User object will go in the cache so that any portal operation that requires access to it (such as permission checking) can retrieve that object very quickly from the cache.

You may wish to add other objects to the cache. For example, a large part of your application may be document management using the Documents and Media portlet. In this case, you may want to cache media objects, such as DLFileEntryImpl in order to improve performance as users access documents. To do that, add another block to the configuration file with the class you want to cache:

<cache
    eternal="false"
    maxElementsInMemory="10000"
    name="com.liferay.portlet.documentlibrary.model.impl.DLFileEntryImpl"
    overflowToDisk="false"
    timeToIdleSeconds="600"
>
    <cacheEventListenerFactory
        class="com.liferay.portal.cache.ehcache.LiferayCacheEventListenerFactory"
        properties="replicatePuts=false,replicateUpdatesViaCopy=false"
        propertySeparator=","
    />
    <bootstrapCacheLoaderFactory class="com.liferay.portal.cache.ehcache.LiferayBootstrapCacheLoaderFactory" />
</cache>

Your site may use the message boards portlet, and those message boards may get a lot of traffic. To cache the threads on the message boards, configure a block with the MBMessageImpl class:

<cache
    eternal="false"
    maxElementsInMemory="10000"
    name="com.liferay.portlet.messageboards.model.impl.MBMessageImpl"
    overflowToDisk="false"
    timeToIdleSeconds="600"
>
    <cacheEventListenerFactory
        class="com.liferay.portal.cache.ehcache.LiferayCacheEventListenerFactory"
        properties="replicatePuts=false,replicateUpdatesViaCopy=false"
        propertySeparator=","
    />
    <bootstrapCacheLoaderFactory class="com.liferay.portal.cache.ehcache.LiferayBootstrapCacheLoaderFactory" />
</cache>

Note that if your developers have overridden any of these classes in an Ext plugin, you'll have to specify the overridden versions rather than the stock ones that come with Liferay Portal. You can customize the other ehcache configuration files in exactly the same way. Refer to Ehcache's documentation for information on how to do this.

As you can see, it's easy to add specific data to be cached. Be careful, however, as too much caching can actually reduce performance if the JVM runs out of memory and starts garbage collecting too frequently. You'll likely need to experiment with the memory settings on your JVM as well as the cache settings above. You can find the specifics about these settings in the documentation for Ehcache.