HOWTO.txt

Howto
=====

Basic Example:
==============

Lets say you have 3 servers.  Server 1 and server 2 have 3GB of space
and server 3 has 2GB of space for cache.  Here is how I would set up
my client.

import com.danga.MemCached.*;
public class MyClass {

	// create a static client as most installs only need
	// a single instance
	protected static MemCachedClient mcc = new MemCachedClient();

	// set up connection pool once at class load
	static {

		// server list and weights
		String[] servers =
			{
			  "server1.mydomain.com:1624",
			  "server2.mydomain.com:1624",
			  "server3.mydomain.com:1624"
			};

		Integer[] weights = { 3, 3, 2 };

		// grab an instance of our connection pool
		SockIOPool pool = SockIOPool.getInstance();

		// set the servers and the weights
		pool.setServers( servers );
		pool.setWeights( weights );

		// set some basic pool settings
		// 5 initial, 5 min, and 250 max conns
		// and set the max idle time for a conn
		// to 6 hours
		pool.setInitConn( 5 );
		pool.setMinConn( 5 );
		pool.setMaxConn( 250 );
		pool.setMaxIdle( 1000 * 60 * 60 * 6 );

		// set the sleep for the maint thread
		// it will wake up every x seconds and
		// maintain the pool size
		pool.setMaintSleep( 30 );

		// set some TCP settings
		// disable nagle
		// set the read timeout to 3 secs
		// and don't set a connect timeout
		pool.setNagle( false );
		pool.setSocketTO( 3000 );
		pool.setSocketConnectTO( 0 );

		// initialize the connection pool
		pool.initialize();


		// lets set some compression on for the client
		// compress anything larger than 64k
		mcc.setCompressEnable( true );
		mcc.setCompressThreshold( 64 * 1024 );
	}

	// from here on down, you can call any of the client calls
	public static void examples() {
        mcc.set( "foo", "This is a test String" );
		String bar = mcc.get( "foo" );
	}
}

Multi-client Example:
=====================

If you need to support multiple clients (i.e. Java, PHP, Perl, etc.)
you need to make a few changes when you are setting things up:

	// use a compatible hashing algorithm
	pool.setHashingAlg( SockIOPool.NEW_COMPAT_HASH );

	// store primitives as strings
	// the java client serializes primitives
	//
	// note: this will not help you when it comes to
	// storing non primitives
	mcc.setPrimitiveAsString( true );

	// don't url encode keys
	// by default the java client url encodes keys
	// to sanitize them so they will always work on the server
	// however, other clients do not do this
	mcc.setSanitizeKeys( false );


Failover/Failback Notes:
========================

By default the java client will failover to a new server when a server
dies.  It will also failback to the original if it detects that the
server comes back (it checks the server in a falling off pattern).

If you want to disable this (useful if you have flapping servers),
there are two settings to handle this.

	pool.setFailover( false );
	pool.setFailback( false );


Serialization:
==============

For java "native types", which include:

Boolean
Byte
String
Character
StringBuffer
StringBuilder
Short
Long
Double
Float
Date
Integer

The client will by default *NOT* use java serialization, and instead
will serialize using the primitive values to save space.  You can
override this by using the mcc.setPrimitiveAsString( true ), which
will use the toString representation of the object.

For other java objects, you need to make sure the class implements
Serializable in order to be able to be stored in the cache.

I would also reccomend that if possible, classes should instead
implement Externalizable as opposed to Serializable.  This allows the
author of the class to define how objects of that class should
serialize.  In practice at Meetup.com, we saw a 60% reduction in the size
of our serialized objects by doing this.  This means less data to eat up
cache space and less data to transfer over the network.

Other:
======
See the java docs.