JRedisFuture

package org.jredis;

import java.io.Serializable;
import java.util.List;
import java.util.Map;
import java.util.concurrent.ExecutionException;
import java.util.concurrent.Future;
import org.jredis.protocol.ResponseStatus;


/**
 * The asynchronous interface to Redis.
 * <p>
 * This is effectively a one to one mapping to Redis commands.  Depending on the implementation
 * either the redis response and/or redis write are asynchronous.  Regardless, each method returns
 * an extension of {@link Future} and the returned results conforms to the contract of that interface (which
 * you should review).
 * <p>
 * If your request results in a {@link RedisException}, the call to {@link Future#get()} (of whatever flavor)
 * will raise a {@link ExecutionException} with {@link ExecutionException#getCause()} returning the underlying
 * {@link RedisException}.
 * <p>
 * Similarly, if the request results in either {@link ClientRuntimeException} or {@link ProviderException}, the
 * {@link Future}'s {@link ExecutionException} will wrap these as the cause.
 * <p>
 * Beyond that , just be aware that an implementation may throw {@link ClientRuntimeException}
 * or an extension to report problems (typically connectivity) or {@link ProviderException}
 * (to highlight implementation features/bugs).  
 * These are {@link RuntimeException} that have been encountered while trying to queue your request.
 * <p>
 * <b>Note</b> that this interface provides no guarantees whatsoever regarding the execution of your requests beyond
 * the (relative) ordering of the requests per your invocations.  Specifically, in the event of connection issues, this
 * interface's contract does not place any requirements on the implementation beyond to notify the user of such issues
 * either during a call to this interface, or, on the attempt to get the result of a pending response on {@link Future#get()}.
 * Refer to the documentation of the implementation of {@link JRedisFuture} for the specifics of behavior in context of
 * errors. 
 * 
 * @author  Joubin ([email protected])
 * @version alpha.0, 04/02/09
 * @since   alpha.0
 * 
 */
public interface JRedisFuture {
	
	// ------------------------------------------------------------------------
	// "Connection Handling"
	// ------------------------------------------------------------------------

	public Future<ResponseStatus> ping ();

	public Future<ResponseStatus> quit ();
	
	// ------------------------------------------------------------------------
	// "Commands operating on string values"
	// ------------------------------------------------------------------------

	public Future<ResponseStatus> set (String key, byte[] value);
	public Future<ResponseStatus> set (String key, String stringValue);
	public Future<ResponseStatus> set (String key, Number numberValue);
	public <T extends Serializable> 
		   Future<ResponseStatus> set (String key, T object);

	public Future<Boolean> setnx (String key, byte[] value);
	public Future<Boolean> setnx (String key, String stringValue);
	public Future<Boolean> setnx (String key, Number numberValue);
	public <T extends Serializable> 
		   Future<Boolean> setnx (String key, T object);

	public Future<byte[]> get (String key) ;

	public Future<byte[]> getset (String key, byte[] value);
	public Future<byte[]> getset (String key, String stringValue);
	public Future<byte[]> getset (String key, Number numberValue);
	public <T extends Serializable> 
		Future<byte[]> getset (String key, T object);

	public Future<List<byte[]>> mget(String key, String...moreKeys);

	public Future<Long> incr (String key);

	public Future<Long> incrby (String key, int delta);

	public Future<Long> decr (String key);

	public Future<Long> decrby (String key, int delta);

	public Future<Boolean> exists(String key);

	public Future<Boolean> del (String key);

	public Future<RedisType> type (String key);
	
	// ------------------------------------------------------------------------
	// "Commands operating on the key space"
	// ------------------------------------------------------------------------
	
	public Future<List<String>> keys (String pattern);
	public Future<List<String>> keys ();

	public Future<String> randomkey();

	public Future<ResponseStatus> rename (String oldkey, String newkey);

	public Future<Boolean> renamenx (String oldkey, String brandnewkey);
	
	public Future<Long> dbsize ();

	public Future<Boolean> expire (String key, int ttlseconds); 

	public Future<Long> ttl (String key);
	
	// ------------------------------------------------------------------------
	// Commands operating on lists
	// ------------------------------------------------------------------------

	public Future<ResponseStatus> rpush (String listkey, byte[] value);
	public Future<ResponseStatus> rpush (String listkey, String stringValue);
	public Future<ResponseStatus> rpush (String listkey, Number numberValue);
	public <T extends Serializable> 
		Future<ResponseStatus> rpush (String listkey, T object);

	public Future<ResponseStatus> lpush (String listkey, byte[] value);
	public Future<ResponseStatus> lpush (String listkey, String stringValue);
	public Future<ResponseStatus> lpush (String listkey, Number numberValue);
	public <T extends Serializable> 
		Future<ResponseStatus> lpush (String listkey, T object);

	public Future<ResponseStatus> lset (String key, long index, byte[] value);
	public Future<ResponseStatus> lset (String key, long index, String stringValue);
	public Future<ResponseStatus> lset (String key, long index, Number numberValue);
	public <T extends Serializable> 
		Future<ResponseStatus> lset (String key, long index, T object);

	public Future<Long> lrem (String listKey, byte[] value,       int count);
	public Future<Long> lrem (String listKey, String stringValue, int count);
	public Future<Long> lrem (String listKey, Number numberValue, int count);
	public <T extends Serializable> 
		Future<Long> lrem (String listKey, T object, int count);

	public Future<Long> llen (String listkey);

	public Future<List<byte[]>> lrange (String listkey, long from, long to); 

	public Future<ResponseStatus> ltrim (String listkey, long keepFrom, long keepTo);

	public Future<byte[]> lindex (String listkey, long index);

	public Future<byte[]> lpop (String listKey);

	public Future<byte[]> rpop (String listKey);

	// ------------------------------------------------------------------------
	// Commands operating on sets
	// ------------------------------------------------------------------------

	public Future<Boolean> sadd (String setkey, byte[] member);
	public Future<Boolean> sadd (String setkey, String stringValue);
	public Future<Boolean> sadd (String setkey, Number numberValue);
	public <T extends Serializable> 
		Future<Boolean> sadd (String setkey, T object);

	public Future<Boolean> srem (String setKey, byte[] member);
	public Future<Boolean> srem (String setKey, String stringValue);
	public Future<Boolean> srem (String setKey, Number numberValue);
	public <T extends Serializable> 
		Future<Boolean> srem (String setKey, T object);

	public Future<Boolean> sismember (String setKey, byte[] member);
	public Future<Boolean> sismember (String setKey, String stringValue);
	public Future<Boolean> sismember (String setKey, Number numberValue);
	public <T extends Serializable> 
		Future<Boolean> sismember (String setKey, T object);

	public Future<Boolean> smove (String srcKey, String destKey, byte[] member);
	public Future<Boolean> smove (String srcKey, String destKey, String stringValue);
	public Future<Boolean> smove (String srcKey, String destKey, Number numberValue);
	public <T extends Serializable> 
		Future<Boolean> smove (String srcKey, String destKey, T object);

	public Future<Long> scard (String setKey);	
	
	public Future<List<byte[]>> sinter (String set1, String...sets);

	public Future<ResponseStatus> sinterstore (String destSetKey, String...sets);

	public Future<List<byte[]>> sunion (String set1, String...sets);

	public Future<ResponseStatus> sunionstore (String destSetKey, String...sets);

	public Future<List<byte[]>> sdiff (String set1, String...sets);

	public Future<ResponseStatus> sdiffstore (String destSetKey, String...sets);

	public Future<List<byte[]>> smembers (String setkey);
	
	// ------------------------------------------------------------------------
	// Multiple databases handling commands
	// ------------------------------------------------------------------------
	
	public Future<ResponseStatus> flushdb ();

	public Future<ResponseStatus> flushall ();

	public Future<Boolean> move (String key, int dbIndex);
	
	// ------------------------------------------------------------------------
	// Sorting
	// ------------------------------------------------------------------------
	
	/**
	 * <p>For Usage details regarding sort semantics, see {@link JRedis#sort}.  The
	 * only difference in usage is that you must use the {@link Sort#execAsynch()} method
	 * which returns a {@link Future} instances.
	 * <p>Usage:
	 * <p><code><pre>
	 * Future<List<byte[]>>  futureResults = redis.sort("my-list-or-set-key").BY("weight*").LIMIT(1, 11).GET("object*").DESC().ALPHA().execAsynch();
	 * List<byte[]> results = futureResult.get();  // wait for the asynchronous response to be processed
	 * for(byte[] item : results) {
	 *     // do something with item ..
	 *  }
	 * </pre></code>
	 * 
	 * @Redis SORT
	 * @see Redis
	 * @see Future
	 * 
	 */
	public Sort sort(String key);
	
	// ------------------------------------------------------------------------
	// Persistence control commands
	// ------------------------------------------------------------------------

	public Future<ResponseStatus> save();

	public Future<ResponseStatus> bgsave ();
	
	public Future<Long> lastsave ();

	// ------------------------------------------------------------------------
	// Remote server control commands
	// ------------------------------------------------------------------------

	public Future<Map<String, String>>	info () ;
	
}