some basic docs

Author: gwhalin

doc/HOWTO.txt

@@ -0,0 +1,117 @@
+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 );
+
+
+
+Other:
+======
+See the java docs.