Note that the managers only need to communicate when an object is removed from a cache. This only happens when an object is updated or deleted. The managers do not co-operate beyond this. This means that the amount of inter-server communications is proportional to the amount of updates/deletes of the application. As the communications is multicast, it is not proportional to the number of caching hosts. Also notice that there is no "server"; all hosts are equal peers and they can come and go from the cache group as they please without affecting other group members. Thus the operation of the distributed cache is very robust.

Basic Usage
SwarmCache is designed to be integrated in to the persistence layer of a database-driven Java application. However, it could be useful for other types of applications. Once built in to the persistence engine, SwarmCache should be transparent to higher layers of the software. SwarmCache does not directly support transaction management. This can be accomplished by wrapping the cached objects and storing some additional transaction data. This will described and possibly implemented at a later date.

Swarmcache requires that swarmcache.jar, jgroups-all.jar, commons-collections.jar, and commons-logging.jar (included in the download) be in your classpath.

For most applications, it is sufficient to make use of the CacheFactory class to configure and use SwarmCache. Here is an example:

import net.sf.swarmcache.*;

...

CacheFactory cacheFactory;

...

// Configure and Initialize the cache manager
CacheConfiguration conf = new CacheConfiguration();
conf.setCacheType(CacheConfiguration.TYPE_LRU);
cacheFactory = new CacheFactory(conf);

...

// Create a new cache, using a name that describes
//  what kind of object we will store
ObjectCache cache = cacheFactory.createCache("People");

...

// Store something in the cache
String key = "0001";
String person = "John Watkinson";
cache.put(key, person);

...

// Retrieve something from the cache
String person = (String)cache.get("0001");
System.out.println(person);

...

// Clear an object from the cache
// (This results in the sending of a 
//  multicast message to other caching hosts)
cache.clear("0001");
String person = (String)cache.get("0001");
// The following will print 'null'
System.out.println(person);

Note that the keys used must be serializable objects-- they must implement java.io.Serializable. The objects themselves that are stored in the cache need not be serializable. And of course, the keys should not be large objects for transmission efficiency purposes.

In order to keep keys distinct, it is usually preferred to have one cache per type of object stored. In that case, it makes sense to follow the convention that the cache be named after the fully-qualified class name of the object type to be stored.

Usage in a Persistence Engine
Here is some skeleton code that demonstrates how SwarmCache could be integrated in to a persistence engine. The following class is responsible for persisting an object of type Person:

public class PersonEntity extends GenericEntity {

	ObjectCache cache;
	
	public PersonEntity(CacheFactory cacheFactory) {
		cache = cacheFactory.createCache("Person");
		// * Other initialization here
	}

	...
	
	public Person get(long key) {
		Long cacheKey = new Long(key);
		Person person = (Person)cache.get(cachekey);
		if (person == null) {
			// * Get the object from the database			
			if (person != null) {
				// Put it in the cache
				cache.put(cacheKey, person);
			}
		}
		return person;
	}
	
	...
	
	public void insert(Person person) {
		// * Do database insert
		// Add new object to cache
		Long cacheKey = new Long(person.getKey());
		cache.put(cacheKey, person);
	}
	
	...
	
	public void update(Person person) {
		// * Do database update
		// Remove object from cache
		// (This causes all caches in the group to be notified)
		Long cacheKey = new Long(person.getKey());
		cache.clear(cacheKey);
		// Re-add the object to the cache
		cache.put(cacheKey, person);
	}
	
	...
	
	public void delete(long key) {
		// * Do database delete
		// Remove object from cache
		// (This causes all caches in the group to be notified)
		Long cacheKey = new Long(key);
		cache.clear(cacheKey);		
	}
	
	...
	
}