The "Basic Coherence Features Examples"

Is a collection of examples that show how to use the basic features of Coherence using a simplified contact information tracker and includes:

  • Basic Data Access – "Getting", "putting" and "removing" data from the Coherence Data Grid.
  • Data Loading – Loading example data into the Coherence Data Grid.
  • Parallel Querying – Querying the Coherence Data Grid including the use of indexes.
  • Observable – Listening for changes to data in the Coherence Data Grid.
  • Processing – Co-locating data processing with the data itself in the Coherence Data Grid.

This Example Set

  • Uses example data (i.e. Contact, ContactId, Address and PhoneNumber) represented by the Data Model classes.
  • Ships with a contacts.csv file which is a comma delimited value file containing sample Contacts information.

Running the Example Set

Fist, review the following information:

  1. How to Build the Examples
  2. How to Run the Examples

 

Second, review the information on the Driver implementation found here:

The Driver

Has a static main method that executes all the Contacts examples in the following order:

  • LoaderExample
  • QueryExample
  • ObserverExample
  • BasicExample
  • ProcessorExample

Is implemented in each of the three programming languages supported by Coherence:

Language Implementation Class
Java com.tangosol.examples.contacts.Driver in java/src
.NET Driver in namespace Tangosol.Examples.Contacts in dotnet/src/contacts
CPP Driver in namespace coherence::examples in cpp/contacts
Please refer to this example set's source code for more details on each of the examples outlined below.

Basic Data Access Example

This example shows the most basic data access features of Coherence including getting, putting and removing data.

Java Basic Data Access Example

Implementation Class: com.tangosol.examples.contacts.BasicExample in java/src

Associate a ContactId with a Contact in the cache:

cache.put(contactId, contact);

Retrieve the Contact associated with a ContactId from the cache:

contact = (Contact) cache.get(contactId);

Remove mapping of ContactId to Contact from the cache:

cache.remove(contactId);

.NET Basic Data Access Example

Implementation Class: BasicExample in namespace Tangosol.Examples.Contacts in dotnet/src/contacts

Associate a ContactId with a Contact in the cache:

cache.Add(contactId, contact);

Retrieve the Contact associated with a ContactId from the cache:

contact = (Contact)cache[contactId];

Remove mapping of ContactId to Contact from the cache:

cache.Remove(contactId);

C++ Basic Data Access Example

Implementation Class: BasicExample in namespace coherence::examples in cpp/contacts

Associate a ContactId with a Contact in the cache:

hCache->put(vContactId, vContact);

Retrieve the Contact associated with a ContactId from the cache:

vContact = cast<Managed<Contact>::View>(hCache->get(vContactId));

Remove mapping of ContactId to Contact from the cache:

hCache->remove(vContactId);

Sample Data Access Output

The example Output (due to Observer Example):


entry inserted:
John Nocyefqgqo
Addresses
Home: 1500 Boylston St.
null
Obopnof, NM 88824
US
Work: 8 Yawkey Way
null
Ssedhvmdeq, OR 84217
US
Phone Numbers
work: +11 0 707 3776578
Birth Date: 1971-12-31
entry deleted:
John Nocyefqgqo
Addresses
Home: 1500 Boylston St.
null
Obopnof, NM 88824
US
Work: 8 Yawkey Way
null
Ssedhvmdeq, OR 84217
US
Phone Numbers
work: +11 0 707 3776578
Birth Date: 1971-12-31

Loader Example

This example loads contacts into the cache from a file or stream.

It demonstrates the most effective way of inserting data into a cache using bulk inserts. This will allow for minimizing the number of network roundtrips between the application and the cache.

Java Loader Example

Implementation Class: com.tangosol.examples.contacts.LoaderExample in java/src
cache.putAll(mapBatch);

.NET Loader Example

Implementation Class: LoaderExample in namespace Tangosol.Examples.Contacts in dotnet/src/contacts
cache.InsertAll(dictBatch);

C++ Loader Example

Implementation Class: LoaderExample in namespace coherence::examples in cpp/contacts
hCache->putAll(hMapBatch);

Example Loader Output:


.........Added 10000 entries to cache

Query Example

QueryExample runs sample queries for contacts.

The purpose of this example is to show how to create Extractors on cache data and how to create a KeyExtractor for the cache keys. It also illustrates how to use the indexes to filter the dataset in order to efficiently create a matching set. Finally, the example demonstrates how to use some of the built-in cache aggregators to do simple computational tasks on the cache data. A subset of the code is shown below.

Java Query Example

Implementation Class: com.tangosol.examples.contacts.QueryExample in java/src

Add an index to make queries more efficient.

cache.addIndex(new ChainedExtractor("getHomeAddress.getState"), /*fOrdered*/ false, /*comparator*/ null);

Find all contacts who live in Massachusetts.

Set setResults = cache.entrySet(new EqualsFilter("getHomeAddress.getState", "MA"));

Count contacts who are older than nAge for the entire cache dataset.

System.out.println("count > " + nAge + ": " + cache.aggregate(new GreaterFilter("getAge", nAge), new Count()));

.NET Query Example

Implementation Class: QueryExample in namespace Tangosol.Examples.Contacts in dotnet/src/contacts

Add an index to make queries more efficient.

cache.AddIndex(new ChainedExtractor("getHomeAddress.getState"),/*fOrdered*/ false, /*comparator*/ null);

Find all contacts who live in Massachusetts.

ICacheEntry[] aCacheEntry = cache.GetEntries(new EqualsFilter("getHomeAddress.getState", "MA"));

Count contacts who are older than nAge for the entire cache dataset.

Console.WriteLine("count > " + nAge + ": "+ cache.Aggregate(new GreaterFilter("getAge", nAge), new Count()));

C++ Query Example

Implementation Class: QueryExample in namespace coherence::examples in cpp/contacts

Add an index to make queries more efficient.

ValueExtractor::View vHomeStateExtractor = ChainedExtractor::create(
   ChainedExtractor::createExtractors("getHomeAddress.getState"));

Find all contacts who live in Massachusetts.

Object::View voStateName = String::create("MA");
Set::View setResults = hCache->entrySet(
      EqualsFilter::create(vHomeStateExtractor, voStateName));

Count contacts who are older than nAge for the entire cache dataset.

Integer32::View nAge = Integer32::valueOf(58);
Object::View vResult = hCache->aggregate(
      (Filter::View) GreaterFilter::create(vAgeExtractor, nAge),
         Count::create());
std::cout << "count > " << nAge->getValue() << ": " << vResult << std::endl;

Sample Query Output

The example output is large due to 10,000 contacts and several queries. A sample of the query for Massachusetts residents:


MA Residents
ConverterEntry{Key="John Scqngqda", Value="John Scqngqda
Addresses
Home: 265 Beacon St.

Oaskxm, MA 88259
US
Work: Yoyodyne Propulsion Systems
330 Lectroid Rd.
Grover's Mill, OK 95744
US
Phone Numbers
work: +11 88 903 8991283
home: +11 98 553 5878221
Birth Date: 1960-01-03"}

Observer Example

ObserverExample demonstrates how to use a MapListener to monitor cache events such as when cache data has been inserted, updated, and removed. A subset of the code is shown below.

Java Observer Example

Implementation Class: com.tangosol.examples.contacts.ObserverExample in java/src
cache.addMapListener(new ContactChangeListener());

ContactChangeListener is a class that implements the MapListener interface.

.NET Observer Example

Implementation Class: ObserverExample in namespace Tangosol.Examples.Contacts in dotnet/src/contacts
cache.AddCacheListener(new ContactChangeListener());

ContactChangeListener is a class that implements the ICacheListener interface.

C++ Observer Example

Implementation Class: ObserverExample in namespace coherence::examples in cpp/contacts
ContactChangeListener::Handle hListener = ContactChangeListener::create();
hCache->addFilterListener(hListener);

ContactChangeListener is a class that extends the MapListener type using Coherence extend macro.

class ContactChangeListener
   : public class_spec<ContactChangeListener,
         extends <MapListener> >

Sample Observer Output

There is no immediate output when this example is run. The registered listener outputs the entry when it is inserted, updated, and deleted. For an update, it outputs both the old value and the new value. The changes to entries are caused by running the Basic Data Access Example and the Processor Example, so the output happens when those examples are run.

Processor Example

ProcessorExample demonstrates how to use a processor to modify a set of data in the cache. In the code sample that follows, all Contacts who live in MA will have their work address updated.

Java Processor Example

Implementation Class: com.tangosol.examples.contacts.ProcessorExample in java/src
Helper Class: com.tangosol.examples.contacts.OfficeUpdater in java/src

Apply the OfficeUpdater on all contacts who live in MA. The OfficeUpdater is a class that implements the InvocableMap.EntryProcessor interface by extending AbstractProcessor.

cache.invokeAll(new EqualsFilter("getHomeAddress.getState", "MA"), new OfficeUpdater(addrWork));

.NET Processor Example

Implementation Class: ProcessorExample in namespace Tangosol.Examples.Contacts in dotnet/src/contacts
Helper Class: OfficeUpdater in namespace Tangosol.Examples.Contacts in dotnet/src/contacts

Apply the OfficeUpdater on all contacts who live in MA. The OfficeUpdater is a class that implements the IEntryProcessor interface by extending AbstractProcessor.

cache.InvokeAll(new EqualsFilter("getHomeAddress.getState", "MA"), new OfficeUpdater(addrWork));

C++ Processor Example

Implementation Class: ProcessorExample in namespace coherence::examples in cpp/contacts
Helper Class: OfficeUpdater in namespace coherence::examples in cpp/contacts

The OfficeUpdater is a class that extends the UpdaterProcessor type.

class OfficeUpdater
   : public class_spec<OfficeUpdater,
      extends<UpdaterProcessor>,
      implements<PortableObject> >

Apply the OfficeUpdater on all contacts who live in MA.

InvocableMap::EntryProcessor::Handle hOffice = OfficeUpdater::create(addrWork);
Map::View vMap = hCache->invokeAll(vEqualsFilter, hOffice);

Sample Processor Output

The example Output (due to Observer Example) is large due to the number of contacts. A sample of output:


entry updated
old value:
John Keau
Addresses
Home: 443 Beacon St.

Ophvowvw, MA 06539
US
Work: Yoyodyne Propulsion Systems
330 Lectroid Rd.
Grover's Mill, FL 86812
US
Phone Numbers
work: +11 8 919 9456102
home: +11 25 759 588823
Birth Date: 1968-12-31
new value:
John Keau
Addresses
Home: 443 Beacon St.

Ophvowvw, MA 06539
US
Work: 200 Newbury St.
Yoyodyne, Ltd.
Boston, MA 02116
US
Phone Numbers
work: +11 8 919 9456102
home: +11 25 759 588823
entry updated
old value:
John Lbggblkd
Addresses
Home: 929 Beacon St.

Trwylbmf, MA 50358
US
Work: Yoyodyne Propulsion Systems
330 Lectroid Rd.
Grover's Mill, AZ 19164
US
Phone Numbers
work: +11 60 699 203810
home: +11 34 149 5018157
Birth Date: 1964-01-02
new value:
John Lbggblkd
Addresses
Home: 929 Beacon St.

Trwylbmf, MA 50358
US
Work: 200 Newbury St.
Yoyodyne, Ltd.
Boston, MA 02116
US
Phone Numbers
work: +11 60 699 203810
home: +11 34 149 5018157
Birth Date: 1964-01-02

Birth Date: 1968-12-31

Data Generator

Java Data Generator

Implementation Class: com.tangosol.examples.contacts.DataGenerator in java/src

The DataGenerator has a static main method that generates random Contact information and stores the results in a
comma separated value file. This class was used to generate the contacts.csv that is packaged with the contacts examples and is included in case more sample data is needed.

It is implemented only in Java.