Configuring Coherence
Coherence uses several
configuration files. In
this section, we will cover one of the core configuration files, the operational descriptor.
Operational configuration
The operational descriptor is
used to configure Coherence runtime parameters such as clustering,
communication, services, logging, security, license information, and so
on.
Coherence ships with a default operational descriptor, tangosol-coherence.xml, packaged within coherence.jar.
If you look more carefully at the console printout of a Coherence node,
you will see that the very first line printed is similar to the
following:
2009-08-12 13:46:01.983/0.259 Oracle Coherence 3.5.1/461 <Info> (thread=main, member=n/a):
Loaded operational configuration from resource "jar:file:/opt/coherence-3.5/lib/coherence.jar!/tangosol-coherence.xml"
While you are encouraged to
review this file to see what the default configuration looks like, you
will typically not modify it directly. Instead, you will use one or more override files to modify only those elements of the operational descriptor that need to be changed for your environment.
All you need to do is create an override file and place it in the Coherence node's classpath before coherence.jar.
There are several override files that you can use:
If you want to change the settings globally, regardless of the mode Coherence is running in, you can create a file called tangosol-coherence-override.xml
and use it to override any of the elements from a default deployment
descriptor. The structure of the files is exactly the same, with the
exception that all elements in the override file are optional.
If you want your changes to apply only to the development environment, you can create an override file called tangosol-coherence-override-dev.xml. Any settings specified in this file will apply only when the Coherence is running in a development mode, which is the default.
If you want your changes to apply only to the production environment, you can create a file called tangosol-coherence-override-prod.xml. In order to have settings from this file applied on your production servers, you should set the system property tangosol.coherence.mode to prod in the script that is used to start Coherence nodes.
You can also create all of
these files, and they will be applied in order, from most specific to
the default one. For example, if you define both tangosol-coherence-override-dev.xml and tangosol-coherence-override.xml,
settings from the former will be used to override default settings, and
settings from the latter will override both the default settings and
the settings specified in the tangosol-coherence-override-dev.xml.
Configuring logging
By default, Coherence prints out log statements to stderr
using its own logging subsystem. More likely than not, this is not the
desired behavior-you will probably want to use the same logging
framework for Coherence that you use for the rest of the application.
Fortunately, Coherence supports both the JDK logging framework and
Log4J.
In order to configure Coherence to use Log4J, you need to create an operational override file and define a logging-config section with a destination element set to log4j:
<coherence>
<logging-config>
<destination>log4j</destination>
</logging-config>
</coherence>
You will likely want to use the
same logging framework both in development and production, so you
should place the code above into tangosol-coherence-override.xml file, and make sure that the file is in the classpath.
You will also need to configure Log4J by creating a log4j.properties file similar to the following, and placing it in the classpath as well:
log4j.logger.Coherence=DEBUG, CONSOLE, FILE
log4j.appender.CONSOLE=org.apache.log4j.ConsoleAppender
log4j.appender.CONSOLE.threshold=INFO
log4j.appender.CONSOLE.layout=org.apache.log4j.PatternLayout
log4j.appender.CONSOLE.layout.ConversionPattern=%m%n
log4j.appender.FILE=org.apache.log4j.RollingFileAppender
log4j.appender.FILE.File=logs/coherence.log
log4j.appender.FILE.MaxFileSize=10MB
log4j.appender.FILE.layout=org.apache.log4j.PatternLayout
log4j.appender.FILE.layout.ConversionPattern=%m%n
Obviously, you can
set logging thresholds as you like, but my personal preference is to log
errors, warnings, and informational messages to the console, and to
write all messages into the log file. This allows me to immediately see
on the console if anything is out of the ordinary, and to dig into the
log file for details.
Writing log messages from all
the nodes into a single log file also has tremendous benefits, as it
allows you to see the events across the cluster in one place. This is
very helpful when debugging Coherence applications.
In any case, while the exact logger configuration is up to you, there are two important things to notice in the previous sample:
You need to configure a logger named Coherence, as that's the name that the internal logging subsystem looks for when delegating to Log4J.
Also,
because Coherence already formats log messages internally to include
all necessary information, you should simply print out the message using
the %m%n layout pattern in Log4J.
Of course, you could modify
the standard Coherence message pattern and use Log4J for formatting, but
using the default one will make the process much easier if you need to
submit the log file to Coherence support team.
Configuring a private cluster
Now that you know how to use
operational descriptors to configure Coherence, let's see how we can use
configuration elements to ensure that each developer's cluster is
private.
First off, because we want clusters to be private only in the development environment, you will need to create a tangosol-coherence-override-dev.xml
file, and ensure that it is in the classpath at runtime. The next step
will depend on whether you are using multicast or WKA for cluster join
protocol.
In the former case, you will need to use the following configuration:
<coherence xml-override="/tangosol-coherence-override.xml">
<cluster-config>
<multicast-listener>
<join-timeout-milliseconds>1000</join-timeout-milliseconds>
</multicast-listener>
</cluster-config>
</coherence>
While you only need to specify the time-to-live element to ensure that cluster is private, it is recommended that you specify join-timeout-milliseconds
as well, and to set it to a relatively small value (one to three
seconds should be more than enough for a private cluster). This will
override the default production setting of thirty seconds and ensure
that your cluster nodes start quickly.
If you are using WKA, configuration will be slightly different:
<coherence xml-override="/tangosol-coherence-override.xml">
<cluster-config>
<unicast-listener>
</unicast-listener>
<multicast-listener>
<join-timeout-milliseconds>1000</join-timeout-milliseconds>
</multicast-listener>
</cluster-config>
</coherence>
Notice that we still had to specify the join-timeout-milliseconds
parameter. Even though multicast is not used, this setting still
controls how long the member will wait for evidence of an existing
cluster before starting a new cluster and electing itself as a senior
member, so you need to specify it in order to avoid a 30-second delay
when starting the first member.
Finally, you should notice xml-override attribute within the root configuration element and its value-this is what ensures that the tangosol-coherence-override.xml
file we created in the previous section is loaded and used to override
the settings in this file and the base operational descriptor, so make
sure that you include it if you want the logging configuration we
defined earlier to be used.
Now that we have both the development environment and Coherence configured properly, we are ready to write some code.
