Coherence is a in-memory distributed cache system, usually sitting in between your application servers and your databases.
Coherence is designed to be extremely scalable and has no single point of failure.
It was originally developed by TangoSol and acquired by Oracle in March 2007.

Although usually used by large scale Internet web site and transactional system, Coherence happens to be very lightweight and easy to use for evaluation / development.

Coherence is fully developed in Java and runs on any Java-enabled platform, including Solaris, Linux, Windows and Mac OS X.  Coherence provides clients libraries for Java, .Net and C++ applications.

In this serie of articles, I will show how to test and evaluate Coherence on a Mac OS X system.

1. Get the package

You can freely download Coherence from Oracle Technology Network (free membership required)

2. Unzip the package

marsu:~ sst$ unzip coherence-java-3.6.0.0b17229.zip

3. Inspect the package and be sure the scripts are executable

marsu:~ sst$ ls coherence
bin		doc		lib		product.xml

Without surprises :

• bin – will contains the executable
• doc – contains the javadoc
• lib – contains the JAR to be included with your application

marsu:~ sst$ chmod u+x bin/*.sh

4. Start a first cluster node

marsu:coherence sst$ ./bin/cache-server.sh

Many lines will be output on the console.  Be sure to read

Group{Address=224.3.6.0, Port=36000, TTL=4}
MasterMemberSet
(
ThisMember=Member(Id=1, Timestamp=2010-12-10 13:02:01.121, Address=192.168.0.2:8088, MachineId=26626, Location=machine:marsu,process:42007, Role=CoherenceServer)
OldestMember=Member(Id=1, Timestamp=2010-12-10 13:02:01.121, Address=192.168.0.2:8088, MachineId=26626, Location=machine:marsu,process:42007, Role=CoherenceServer)
ActualMemberSet=MemberSet(Size=1, BitSetCount=2
Member(Id=1, Timestamp=2010-12-10 13:02:01.121, Address=192.168.0.2:8088, MachineId=26626, Location=machine:marsu,process:42007, Role=CoherenceServer)
)
RecycleMillis=1200000
RecycleSet=MemberSet(Size=0, BitSetCount=0
)
)
Group{Address=224.3.6.0, Port=36000, TTL=4}
MasterMemberSet  (  ThisMember=Member(Id=1, Timestamp=2010-12-10 13:02:01.121, Address=192.168.0.2:8088, MachineId=26626, Location=machine:marsu,process:42007, Role=CoherenceServer)  OldestMember=Member(Id=1, Timestamp=2010-12-10 13:02:01.121, Address=192.168.0.2:8088, MachineId=26626, Location=machine:marsu,process:42007, Role=CoherenceServer)  ActualMemberSet=MemberSet(Size=1, BitSetCount=2    Member(Id=1, Timestamp=2010-12-10 13:02:01.121, Address=192.168.0.2:8088, MachineId=26626, Location=machine:marsu,process:42007, Role=CoherenceServer)    )  RecycleMillis=1200000  RecycleSet=MemberSet(Size=0, BitSetCount=0    )  )

And … that’s it.  The first cluster node is started.

5. Start a second cluster node

In another terminal, type  :

marsu:~ sst$ cd coherence
marsu:coherence sst$ ./bin/cache-server.sh

In the output, be sure to read

MasterMemberSet
  (
  ThisMember=Member(Id=2, Timestamp=2010-12-10 13:05:16.693, Address=192.168.0.2:8090, MachineId=26626, Location=machine:marsu,process:42023, Role=CoherenceServer)
  OldestMember=Member(Id=1, Timestamp=2010-12-10 13:02:01.121, Address=192.168.0.2:8088, MachineId=26626, Location=machine:marsu,process:42007, Role=CoherenceServer)
	ActualMemberSet=MemberSet(Size=2, BitSetCount=2
	Member(Id=1, Timestamp=2010-12-10 13:02:01.121, Address=192.168.0.2:8088, MachineId=26626, Location=machine:marsu,process:42007, Role=CoherenceServer)
	Member(Id=2, Timestamp=2010-12-10 13:05:16.693, Address=192.168.0.2:8090, MachineId=26626, Location=machine:marsu,process:42023, Role=CoherenceServer)
   )
RecycleMillis=1200000
RecycleSet=MemberSet(Size=0, BitSetCount=0
)
)

6. Troubleshooting startup issues

By default, Coherence uses multicast to communicate between servers.  In some rare cases, Multicast might fail, preventing the second node to join the cluster.

Be sure to check the documentation and these troubleshooting notes if you run into a problem.

7. Using the cache interractively

Coherence has a command line interface to manipulate objects in the cache,

marsu:coherence sst$ ./bin/coherence.sh ** Starting storage enabled console **
(many lines suppressed)
2010-12-10 13:26:02.066/1.264 Oracle Coherence GE 3.6.0.0 <D5> (thread=Invocation:Management, member=3): Service Management joined the cluster with senior service member 1
Map (?):

Let’s first create a cache :

Map (?): cache currencies
2010-12-10 13:31:30.019/329.217 Oracle Coherence GE 3.6.0.0 <Info> (thread=main, member=3): Loaded cache configuration from "jar:file:/Users/sst/coherence/lib/coherence.jar!/coherence-cache-config.xml"
2010-12-10 13:31:30.151/329.350 Oracle Coherence GE 3.6.0.0 <D5> (thread=DistributedCache, member=3): Service DistributedCache joined the cluster with senior service member 1
<distributed-scheme>
<scheme-name>example-distributed</scheme-name>
<service-name>DistributedCache</service-name>
<backing-map-scheme>
<local-scheme>
<scheme-ref>example-binary-backing-map</scheme-ref>
</local-scheme>
</backing-map-scheme>
<autostart>true</autostart>
</distributed-scheme>
Map (currencies):
Map (?): cache currencies2010-12-10 13:31:30.019/329.217 Oracle Coherence GE 3.6.0.0 <Info> (thread=main, member=3): Loaded cache configuration from "jar:file:/Users/sst/coherence/lib/coherence.jar!/coherence-cache-config.xml"2010-12-10 13:31:30.151/329.350 Oracle Coherence GE 3.6.0.0 <D5> (thread=DistributedCache, member=3): Service DistributedCache joined the cluster with senior service member 1<distributed-scheme>  <scheme-name>example-distributed</scheme-name>  <service-name>DistributedCache</service-name>  <backing-map-scheme>    <local-scheme>      <scheme-ref>example-binary-backing-map</scheme-ref>    </local-scheme>  </backing-map-scheme>  <autostart>true</autostart></distributed-scheme>
Map (currencies):

Populate the cache :

Map (currencies): put USD "US Dollar"
null

Map (currencies): put EUR "Euro"
null

Map (currencies): put CHF "Swiss Franc"
null

Map (currencies): put GPB "British Pound"
null

Play with the cache :

Map (currencies): size
4

Map (currencies): get CHF
Swiss Franc

Map (currencies): remove CHF
Swiss Franc

Map (currencies): size
3

Map (currencies): list
GPB = British Pound
USD = US Dollar
EUR = Euro

8. Next Step

In the next article, I will show you how to programmatically interact with Coherence from a Java application.