EHCache Quick Start |
rate-8257567-13654
| Article Rating? |
|
|
|
Overview
This guide covers getting started with EHCache and Terracotta. It assumes you already have an application written with EHCache.
To get started with Terracotta DSO, review the following guides:
In addition to this quick-start guide, you can also learn more from this example of an application being integrated with Terracotta DSO and EHCache.
Watch the Webcast
If you are already familiar with Terracotta DSO, you are ready to learn how it can help you with an EHCache-enabled application. Visit the Online Training area and select the Distributed Cache Webcast to see:
- How Terracotta supports Distributed Caching
- A demonstration application in action
- How to enable Terracotta for Hashmaps, JBoss TreeCache, and EHCache
You can also browse the source code:
Requirements
Terracotta for EHCache requires the following:
First steps
If you already have an EHCache-enabled application, then follow these steps:
- Install Terracotta.
- Install the EHCache TIM.
- Start your application with Terracotta enabled.
These steps are explained in the following sections.
Installing Terracotta
To install Terracotta, follow these steps:
- Download Terracotta
- If you are on Windows, execute the installer
- For all other platforms, untar/unzip the downloaded file into the directory of your choosing
When you are done, Terracotta will be installed onto your machine. If you are on Windows, it will be installed, by default, into C:\Program Files\Terracotta[Terracotta Version]. From now on, we will refer to the Terracotta installation directory as $TC_HOME.
To aid in starting Terracotta, you may want to set an environment variable that points to the Terracotta installation directory called $TC_HOME.
For a more thorough guide on downloading, installing, and trying out Terracotta sample programs, read the Getting Started Using Terracotta Guide
Installing the EHCache TIM
See the EHCache TIM page for where to download the latest TIMs and how to use them with Terracotta DSO.
Starting the Terracotta server
Every Terracotta application must connect to the Terracotta server. The configuration file above does not specify a server section, but it can. A server section specifies details for the server, such as the location of data and log files. Without one, the defaults will be used. For more details, please consult the Terracotta Configuration Guide for more details.
To start up your server, run the start-tc-server script (it will end in .bat, or .sh, depending on your platform):
$ $TC_HOME/bin/start-tc-server.sh &
You should see output like the following:
2008-02-02 11:52:14,719 INFO - Terracotta 2.5.1, as of 20080128-160143
(Revision 6850 by cruise@rh4mo0 from 2.5)
...
2008-02-02 11:52:17,491 INFO - Terracotta Server has started up as ACTIVE node
on 0.0.0.0:9510 successfully, and is now ready for work.
 |
You can specify a configuration file using -f <file>. This is used if your configuration file contains server specific settings, or if you want to restrict your clients to receiving their configuration from the server.
In the latter case, you must start the server with the full application configuration file. While we are configuring our application for Terracotta, it is easier to load the configuration file from the file system, not the server, as it is easier and more flexible.
In a production environment, it is typically desirable to use the server based configuration methodology. |
Starting your application with Terracotta
Once you have started your Terracotta server, you can start the clients. Terracotta uses normal Java, but requires some specific java options to be added.
The easiest way to start a Terracotta enabled JVM is to use the dso-java script, included with Terracotta.
$ $TC_HOME/dso-java.sh MyMainClass
The dso-java command is only a wrapper around normal Java. It takes all the same arguments that the standard Java command does (e.g. -D, -classpath, etc).
The above command assumes you have a tc-config.xml file in the working directory. If you do not, you will need to use the "-f" parameter.
|
If you cannot use the dso-java script in your environment, please consult the Terracotta Product Documentation for details on starting java with Teracotta configured. |
How it works
Terracotta automatically recognizes caches created in EHCache using the singleton CacheManager. For example,
CacheManager cacheManager = CacheManager.getInstance();
Cache cache;
cache = new Cache("My Cache", 5000, false, false, 30, 30);
cacheManager.addCache(cache);
the cache "My Cache" would automatically be clustered with Terracotta with no need to make changes to the application.
What next
You will probably get the following kinds of exceptions running your application:
- Non Portable Exception
- Unlocked Shared Exception
These are normal for the configuration phase of installing Terracotta!
It is easy to resolve these exceptions.
TCNonPortableObjectException
When you receive a non-portable exception, it means that the class you are sharing (putting into the cache) has not been configured to be portable (shared) in the tc-config.xml. A non-portable exception looks like this:
com.tc.exception.TCNonPortableObjectError:
*******************************************************************************
Attempt to share an instance of a non-portable class referenced by a portable class.
This unshareable class has not been included for sharing in the configuration.
For more information on this issue, please visit our Troubleshooting Guide at:
http:
[...]
And will typically give you instructions on common actions to take to resolve the issue:
Action to take:
1) Reconfigure to include the unshareable classes
* edit your tc-config.xml file
* locate the <dso> element
* add this snippet inside the <dso> element
<instrumented-classes>
<include>
<class-expression>com.mypackage.MyClass</class-expression>
</include>
</instrumented-classes>
* if there is already an <instrumented-classes> element present, simply add
the new includes inside it
It is possible that some or all of the classes above are truly non-portable, the solution
is then to mark the referring field as transient.
You just need to follow these instructions, modifying your tc-config.xml as appropriate.
Unlocked Shared Object Exception
When you receive an Unlocked Shared Object Exception, it means that you have attempted to update the value of a shared object, without the proper locking (synchronization) around it.
An Unlocked Shared Object Exception looks like this:
com.tc.object.tx.UnlockedSharedObjectException:
*******************************************************************************
Attempt to access a shared object outside the scope of a shared lock.
All access to shared objects must be within the scope of one or more shared locks
defined in your Terracotta configuration.
Please alter the locks section of your Terracotta configuration so that this access
is auto-locked or protected by a named lock.
For more information on this issue, please visit our Troubleshooting Guide at:
It is generally very easy to resolve an Unlocked Shared Object Exception. If your object already has synchronization built in (a good idea, if you want your object to be thread safe), then you simply need to add the appropriate Terracotta config to enable locking on the existing synchronization.
This can be done by editing your tc-config.xml to add the appropriate locking. You must have a locks section in your tc-config.xml, which should be inside the <application> and <dso> sections.
Then you must specify the name of the method (wildcards are support) and the lock level (usually write, but read locks, a more advanced topic, are also supported). For example, to configure a write lock on the method void setMyString(String theString) on class com.mypkg.MyBean the following config would be required:
<tc:tc-config>
<application>
<dso>
<locks>
<autolock>
<method-expression>void com.mypkg.MyBean.setMyString(String)</method-expression>
<lock-level>write</lock-level>
</autolock>
</locks>
</dso>
</application>
</tc:tc-config>
If the method does not already have synchronization, you can use the "auto-synchronized" feature:
<tc:tc-config>
<application>
<dso>
<locks>
<autolock auto-synchronized="true">
<method-expression>void com.mypkg.MyBean.setMyString(String)</method-expression>
<lock-level>write</lock-level>
</autolock>
</locks>
</dso>
</application>
</tc:tc-config>
If you don't want to put fine grained synchronization on the setter methods, you can move to a more course-grained approach. Find the point in your application that represents "a transaction" - and put synchronization or locking - as described above - at that point.
For example, suppose you have code that is the following:
public class MyController
{
...
public void update(String key, A a, B b, C c)
{
Foo myFoo = cache.get(key);
myFoo.updateA(a);
myFoo.updateB(b);
myFoo.updateC(c);
cache.put(key, myFoo);
}
}
Instead of locking the methods "updateA", "updateB", and "updateC", you should consider using a more coarse-grained lock on the update method in the MyController class.
More help
The Terracotta Distributed Cache Webcast includes a sample application that you can learn from. If you are having trouble understanding this guide, you should
If you still need assistance, you can:
