Configuring the development environment
Before we can write our
first Coherence application, we need to configure the development
environment. This involves several steps, such as adding the necessary
JAR files to the classpath, configuring the IDE to start Coherence
nodes, and specifying configuration parameters that will ensure that
each developer has a private Coherence cluster for development and
testing.
Most of the examples in this
section are specific to IntelliJ IDEA, which is the IDE that I am most
familiar with. However, adapting them to Eclipse or any other IDE should
be trivial-the principles are the same, even if the mechanics are
slightly different.
Referencing necessary JAR files
In a day and age when
every library seems to come with so many dependencies that we need build
tools like Maven and Ivy to help us put everything together, you might
be surprised to find out that Coherence has no external dependencies.
For the most part, all you need is a reference to a single JAR file, coherence.jar, which can be found in the COHERENCE_HOME/lib directory.
You should also configure the API documentation by pointing your IDE to the COHERENCE_HOME/doc/api directory. This will allow you to access documentation for Coherence classes within your IDE.
For example, a
fully configured project-level library referencing Coherence should look
similar to the following in IntelliJ IDEA:
For example, Coherence
provides a distributed implementation of CommonJ Work Manager
specification. In order to use it you need to include both commonj.jar and coherence-work.jar into the classpath.
Similarly, if you want to use Hibernate, Oracle TopLink, or JPA integration for persistence, you will need to include coherence-hibernate.jar, coherence-toplink.jar, or coherence-jpa.jar respectively, as well as any JAR files required by the persistence provider of your choice.
Enabling IntelliSense for configuration files
Another thing you will likely want to configure in your IDE is the IntelliSense for Coherence configuration files.
Coherence uses a set of
XML-based files for configuration. We will cover these files in more
detail a bit later, but at the moment it should suffice to say that all
of them have a corresponding DTD file within the coherence.jar file.
Most IDEs can take the
advantage of that fact and provide assistance when editing XML
documents, based on information in a DTD file. However, more likely than
not, you will need to tell your IDE where to find the DTD files.
With IDEA, you need to create external resource definitions that point to the files within the coherence.jar file:
With other IDEs the process might be somewhat different, and you might need to extract these three DTD files from coherence.jar and place them in a location that will be accessible to everyone on the team.
Starting Coherence nodes within the IDE
So far we have used the cache-server shell script to start Coherence nodes, but that is not the most convenient way to do so during development.
For one, you will
likely start and restart your development cluster many times a day, and
switching between your IDE and a number of terminal windows all the time
is not the most productive way to work.
Second, you will need to
add your application's classes and any third-party libraries they depend
on to the classpath of each Coherence node. While you could copy and
edit the cache-server shell
script to include necessary classes and JAR files into the classpath
(and you will need to do so before deploying to production), this tends
to be quite cumbersome during development.
Fortunately, as I mentioned
earlier, Coherence is a regular Java application, which makes it quite
simple to start within the IDE. If you look at the cache-server shell script, you will see that it really doesn't do much-it sets heap size and classpath, and launches com.tangosol.net.DefaultCacheServer using server JVM.
Doing the same within any IDE should be trivial. The following screenshot shows a sample configuration in IntelliJ IDEA:
As you can see, I have
configured the cache server to use server JVM and 64 MB of heap. This is
significantly lower than the 512 MB allocated by the cache-server
script, but it should be more than enough for development, as you will
likely not use the complete data set. In any case, you can adjust heap
size to fit your needs.
Now that we have DefaultCacheServer
configured, we can launch as many nodes as we need within the IDE by
simply clicking on a toolbar button. The following screenshot shows two
Coherence nodes running within IntelliJ IDEA:
Creating a private cluster
One thing you will
definitely want to do while working with Coherence is to ensure that
each developer uses a private cluster on their own machine. The very
fact that Coherence clusters so seamlessly can lead to some head
scratching during development if this is not done.
Just recently a colleague of
mine and I were working on two independent tasks, but we both had a few
Coherence nodes running on our laptops. The initial implementation of
the code he was working on had a trivial bug that loaded objects of a
wrong type into one of the caches. He quickly fixed the bug, restarted
the nodes on his machine, and was surprised to find out that the invalid
objects were still in the cache, although now in addition to the
objects of the correct type.
Fortunately, I was sitting
right next to him and it didn't take us long to figure out what was
going on and fix the problem. Basically, even though he restarted the
nodes on his machine before rerunning the tests, the cluster as a whole,
and the data within it survived because there were other nodes running
on my laptop.
Even though the impact in this
case was minimal, the situation might have been different if I was
sitting in another office, so it is extremely important to create
developer "sandboxes" when working with Coherence. It is also the reason
why you need to pay close attention to the information within the MasterMemberSet section when starting Coherence nodes, and to investigate if the result does not match your expectations.
If you were wondering what that tangosol.coherence.ttl system property I specified when configuring DefaultCacheServer
within the IDE meant, it is one of the ways to limit cluster reach. By
setting it to zero, you can effectively limit multicast packets to a
single machine and ensure that your cluster remains private.
If you are using Well-Known Addresses instead of multicast, you can achieve the same goal by setting the tangosol.coherence.wka system property to localhost.
That said, using system
properties is only one way to configure Coherence, and in this case
probably not the best. The issue is that you need to remember to specify
the property in every run configuration you create, and to make sure
that each developer does the same for configurations that are not
shared. This creates a lot of opportunities for human error, and chances
are that sooner or latter someone will forget to specify the necessary
system property.
The good news is that you can
achieve the same goal using configuration files, which can be committed
into the source control repository and shared by the whole team. In
addition, settings specified within the configuration files will apply
automatically to all run/debug configurations that you create in your
IDE.
