JRedis 2.0 API - RFC

/*
 *   Copyright 2009-2010 Joubin Houshyar
 * 
 *   Licensed under the Apache License, Version 2.0 (the "License");
 *   you may not use this file except in compliance with the License.
 *   You may obtain a copy of the License at
 *    
 *   http://www.apache.org/licenses/LICENSE-2.0
 *    
 *   Unless required by applicable law or agreed to in writing, software
 *   distributed under the License is distributed on an "AS IS" BASIS,
 *   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 *   See the License for the specific language governing permissions and
 *   limitations under the License.
 */

package org.jredis;

import java.security.ProviderException;
import java.util.List;
import java.util.Map;
import java.util.concurrent.Future;
import org.jredis.ClientRuntimeException;
import org.jredis.RedisException;
import org.jredis.connector.Connection;
import org.jredis.connector.Connection.Modality;
import org.jredis.protocol.Command;
import org.jredis.ri.alphazero.support.Assert;
import org.jredis2.JRedisNew.Topic.Listener;

/**
 * 
 * @author  Joubin Houshyar ([email protected])
 * @version alpha.0, Jun 26, 2010
 * @since   alpha.0
 * 
 */

public interface JRedis  {
	
	// ------------------------------------------------------------------------
	// JRedis Client Interface
	// ------------------------------------------------------------------------
	
	public JRedisNew pipeline(boolean f);
	public JRedisNew select (int db);
	public JRedisNew.Admin admin();

	// - Transactional semantics

	public JRedisNew.Tx beginTx (Object...metadata);

	// - Monitor (Blocking Semantics)
	public JRedisNew.Monitor monitor(Monitor.Callback callback, Object...metadata);
	
	// the basic (synchronous) API -- cf JRedis 1.0
	public JRedisNew.Sync sync();
	
	// the basic (asynchronous) API -- cf JRedisFuture 1.0
	public JRedisNew.Async async();
	
	// - Topics (Blocking Semantics)
	public JRedisNew.Topic subscribe(byte[] topic, Topic.Listener listener, Object...metadata);	
	public List<JRedisNew.Topic> subscribe(List<byte[]> topiclist, Topic.Listener listener, Object...metadata);
	

	// ========================================================================
	// Administration API
	// ========================================================================
	public interface Admin {
		public JRedisNew.Admin ping () throws RedisException;
		public Map<String, String>	info ()  throws RedisException;
		public JRedisNew.Admin slaveof(String host, int port) throws RedisException;
		public void slaveofnone() throws RedisException;
                // ... etc - all administrative commands		
	}
	// ========================================================================
	// Topic
	// ========================================================================
	public interface Topic {
		
		public byte[] getName();
		public Object getMetadata();
		
		/**
		 * Blocking call to get the next message.  Interruptible.
		 * TODO: this makes things more complex.  do we really need both this and listener?
		 * @return a message from server
		 * @throws InterruptedException
		 */
		public byte[] getMessage() throws InterruptedException;
		
		public interface Message  { 
			/** @return the message */
 			public byte[] getContent();

			/** @return the topic identifier */ 
			public byte[] getSource();
		}
		
		public interface Listener{ 
			/** @param msg the published message*/ 
			public void onMessage(Message msg); 
		}
		public void unsubscribe();
		
	}

	// ========================================================================
	// Monitor
	// ========================================================================
	public interface Monitor {
		public interface Event  { public Object get(String key); }
		public interface Callback { public void onEvent(Event event); }
		public void stop();
	}
	// ========================================================================
	// Sync
	// ========================================================================
	public interface Sync /* extends JRedis */ { 
		// all synchronous blocking request/reply commands
	}
	// ========================================================================
	// Async
	// ========================================================================
	public interface Async /*extends JRedisFuture*/ { 
		// all asynchronous blocking request/reply commands
	}
	// ========================================================================
	// Tx
	// ========================================================================
	public interface Tx /* extends JRedis */ { 
		public Object exec(Command cmd, Object...args);
		public boolean commit() throws RedisException;
		public boolean rollback() throws RedisException;
		// all applicable synchronous blocking request/reply commands
	}
}