merge from head

Author: gwhalin

doc/HOWTO.txt

@@ -0,0 +1,149 @@
+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.

src/com/danga/MemCached/NativeHandler.java

@@ -106,6 +106,7 @@ public class NativeHandler {
     public static final int MARKER_SHORT            = 9;
     public static final int MARKER_DOUBLE           = 10;
     public static final int MARKER_DATE             = 11;
+    public static final int MARKER_STRINGBUILDER    = 12;
 
     public static boolean isHandled( Object value ) {
 
@@ -114,6 +115,7 @@ public static boolean isHandled( Object value ) {
              value instanceof String          ||
              value instanceof Character       ||
              value instanceof StringBuffer    ||
+             value instanceof StringBuilder   ||
              value instanceof Short           ||
              value instanceof Long            ||
              value instanceof Double          ||
@@ -153,6 +155,9 @@ public static byte[] encode( Object value ) throws Exception {
         if ( value instanceof StringBuffer )
             return encode( (StringBuffer)value );
 
+        if ( value instanceof StringBuilder )
+            return encode( (StringBuilder)value );
+
         if ( value instanceof Short )
             return encode( (Short)value );
 
@@ -256,6 +261,15 @@ public static byte[] encode( StringBuffer value ) throws Exception {
 
     }
 
+    public static byte[] encode( StringBuilder value ) throws Exception {
+
+        byte[] b = encode( value.toString() );
+        b[0] = MARKER_STRINGBUILDER;
+        
+        return b;
+        
+    }
+
     public static byte[] encode( Short value ) throws Exception {
 
         byte[] b = encode( (int)value.shortValue() );
@@ -426,6 +440,12 @@ public static StringBuffer decodeStringBuffer( byte[] b ) throws Exception {
 
     }
 
+    public static StringBuilder decodeStringBuilder( byte[] b ) throws Exception {
+
+        return new StringBuilder( decodeString( b ) );
+        
+    }
+
     public static Short decodeShort( byte[] b ) throws Exception {
 
         //FIXME: this generates an extra object we don't need