JGroups (3)

3 Building Blocks
    Building blocks位于org.jgroups.blocks包中，在逻辑上可以视为channels之上的一层，它提供了更复杂的接口。Building blocks并不必依赖于channels，部分building blocks只需要实现了Transport接口的类即可工作。以下简要介绍部分building blocks。

3．1 MessageDispatcher
    Channels 通常用于异步地发送和接收消息。然后有些情况下需要同步通信，例如发送者希望向集群发送消息并等待所有成员的应答，或者等待部分成员的应答。MessageDispatcher支持以同步或者异步的方式发送消息，它在构造时需要一个Channel型的参数。
    MessageDispatcher提供了Object handle(Message msg)方法，用于以push 方式的接收消息并返回应答（必须可以被序列化），该方法抛出的异常也会被传播到消息发送者。MessageDispatcher在内部使用了PullPushAdapter，PullPushAdapter也是org.jgroups.blocks包中的类，但是已经被标记为deprecated。这种方式被称为MessageDispatcher的server模式。
    MessageDispatcher的client模式是指通过调用castMessage或者sendMessage向集群发送消息并同步或者异步的等待应答。castMessage()方法向dests指定的地址发送消息，如果dest为null，那么向集群中所有成员发送消息。castMessage()方法的返回值是RspList，RspList 实现了Map<Address,Rsp> 接口。msg参数中的目的地址会被覆盖。mode参数（由org.jgroups.blocks.GroupRequest类定义）指定了消息是同步还是异步发送，其可选值如下：

• GET_FIRST 返回收到的第一个应答。
• GET_ALL 等待所有成员的应答（被怀疑崩溃的成员除外）。
• GET_MAJORITY 等待绝大多数成员（相对与成员的个数）的应答。
• GET_ABS_MAJORITY等待绝大多数成员（一个绝对的数值，只计算一次）的应答。
• GET_N 等待n个应答，如果n大于成员的个数，可能会一直阻塞下去。
• GET_NONE 不等待应答，直接返回，即异步方式。

    castMessage()方法的定义如下：

public RspList castMessage(Vector dests, Message msg, int mode, long timeout);

    sendMessage()方法允许向一个成员发送消息，msg参数的目的地址不能为null。如果mode参数是GET_NONE，那么消息的发送变成异步方式；否则mode参数会被忽略（缺省采用GET_FIRST）。sendMessage()方法的定义如下：

public Object sendMessage(Message msg, int mode, long timeout) throws TimeoutException;

    以下是个使用MessageDispatcher的例子：

import java.io.BufferedReader;
import java.io.InputStreamReader;

import org.jgroups.Channel;
import org.jgroups.JChannel;
import org.jgroups.Message;
import org.jgroups.blocks.GroupRequest;
import org.jgroups.blocks.MessageDispatcher;
import org.jgroups.blocks.RequestHandler;
import org.jgroups.util.RspList;

public class MessageDispatcherTest {
	//
	private Channel channel;
	private MessageDispatcher dispatcher;
	private boolean propagateException = false;

	public void start() throws Exception {
		//
		channel = new JChannel();
		dispatcher = new MessageDispatcher(channel, null, null, new RequestHandler() {

			public Object handle(Message msg) {
				System.out.println("got a message: " + msg);
				if(propagateException) {
					throw new RuntimeException("failed to handle message: " + msg.getObject());
				} else {
					return new String("success");
				}
			}
			
		});
		channel.connect("MessageDispatcherTest");
		
		//
		sendMessage();
		
		//
		channel.close();
		dispatcher.stop();
	}
	
	private void sendMessage() throws Exception {
		boolean succeed = false;
		BufferedReader br = null;
		try {
			br = new BufferedReader(new InputStreamReader(System.in));
			while(true) {
				System.out.print("> ");
				System.out.flush();
				String line = br.readLine();
				if(line != null && line.equals("exit")) {
					break;
				} else {
					Message msg = new Message(null, null, line);
					RspList rl = dispatcher.castMessage(null, msg, GroupRequest.GET_ALL, 0);
					System.out.println("Responses:\n" + rl);
				}
			}
			succeed = true;
		} finally {
			if(br != null) {
				try {
					br.close();
				} catch (Exception e) {
					if(succeed) {
						throw e;
					}
				}
			}
		}
	}

	public static void main(String[] args) {
		try {
			new MessageDispatcherTest().start();
		} catch (Exception e) {
			e.printStackTrace();
		}
	}
}

3．2 RpcDispatcher
    RpcDispatcher 继承自MessageDispatcher，它允许远程调用集群中其它成员上的方法，并可选地等待应答。跟MessageDispatcher相比，不需要为RpcDispatcher指定RequestHandler。RpcDispatcher的构造函数接受一个Object server_obj参数，它是远程调用的目标对象。RpcDispatcher的callRemoteMethods系列方法用于远程调用目标对象上的方法，该方法可以由MethodCall指定，也可以通过方法名、参数类型指定。跟MessageDispatcher的castMessage()方法和sendMessage()方法类似，callRemoteMethods系列方法也接受一个int mode参数，其含义也相同。以下是个简单的例子：

import java.io.BufferedReader;
import java.io.InputStreamReader;

import org.jgroups.Channel;
import org.jgroups.JChannel;
import org.jgroups.blocks.GroupRequest;
import org.jgroups.blocks.RpcDispatcher;
import org.jgroups.util.RspList;

public class RpcDispatcherTest {
	private Channel channel;
	private RpcDispatcher dispatcher;

	public int print(int number) throws Exception {
		return number * 2;
	}

	public void start() throws Exception {
		channel = new JChannel();
		dispatcher = new RpcDispatcher(channel, null, null, this);
		channel.connect("RpcDispatcherTest");
		
		//
		sendMessage();
		
		//
		channel.close();
		dispatcher.stop();
	}
	
	private void sendMessage() throws Exception {
		boolean succeed = false;
		BufferedReader br = null;
		try {
			br = new BufferedReader(new InputStreamReader(System.in));
			while(true) {
				System.out.print("> please input an int value:");
				System.out.flush();
				String line = br.readLine();
				if(line != null && line.equals("exit")) {
					break;
				} else {
					int param = 0;
					try {
						param = Integer.parseInt(line);
					} catch(Exception e) {
						System.out.println("invalid input: " + line);
						continue;
					}
					RspList rl = dispatcher.callRemoteMethods(null, "print", new Object[]{new Integer(param)}, new Class[]{int.class}, GroupRequest.GET_ALL, 0);
					System.out.println("Responses: \n" + rl);
				}
			}
			succeed = true;
		} finally {
			if(br != null) {
				try {
					br.close();
				} catch (Exception e) {
					if(succeed) {
						throw e;
					}
				}
			}
		}
	}

	public static void main(String[] args) {
		try {
			new RpcDispatcherTest().start();
		} catch (Exception e) {
			e.printStackTrace();
		}
	}
}

3．3 ReplicatedHashMap
    ReplicatedHashMap 继承自ConcurrentHashMap，并在内部使用了RpcDispatcher。ReplicatedHashMap构造函数的clustername参数指定了集群的名字，集群中所有的实例会包含相同的状态。新加入的实例在开始工作前会从集群中获得当前的状态。对实例的修改（例如通过put，remove方法）会传播到集群的其它实例中，只读的请求（例如get方法）则是本地调用。需要注意的是，ReplicatedHashMap的以下划线开头的方法是用于RpcDispatcher的远程调用的。在ReplicatedHashMap上可以注册 Notification，以便在实例的状态改变时进行回调，所有的回调也是本地的。以下是个简单的例子：

import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.util.Iterator;
import java.util.Map;
import java.util.Vector;

import org.jgroups.Address;
import org.jgroups.ChannelFactory;
import org.jgroups.JChannelFactory;
import org.jgroups.View;
import org.jgroups.blocks.ReplicatedHashMap;

public class ReplicatedHashMapTest implements ReplicatedHashMap.Notification<String, String> {
	//
	private ReplicatedHashMap<String, String> map;

	public void start() throws Exception {
		ChannelFactory factory = new JChannelFactory();
		map = new ReplicatedHashMap<String, String>("ReplicatedHashMapTest", factory, "udp.xml", false, 10000);
		map.addNotifier(this);

		sendMessage();
		map.stop();
	}

	public void entryRemoved(String key) {
		System.out.println("in entryRemoved(" + key + ")");
	}

	public void entrySet(String key, String value) {
		System.out.println("in entrySet(" + key + "," + value + ")");
	}

	public void contentsSet(Map<String, String> m) {
		System.out.println("in contentsSet(" + printMap(m) + ")");
	}

	public void contentsCleared() {
		System.out.println("in contentsCleared()");
	}

	public void viewChange(View view, Vector<Address> newMembers,
			Vector<Address> oldMembers) {
		System.out.println("in viewChange(" + view + ")");
	}

	private void sendMessage() throws Exception {
		boolean succeed = false;
		BufferedReader br = null;
		try {
			br = new BufferedReader(new InputStreamReader(System.in));
			while (true) {
				System.out.print("> ");
				System.out.flush();
				String line = br.readLine();
				if (line != null && line.equals("exit")) {
					break;
				} else {
					if (line.equals("show")) {
						System.out.println(printMap(map));
					} else if (line.equals("clear")) {
						map.clear();
					} else if (line.startsWith("remove ")) {
						String key = line.substring(line.indexOf(" ") + 1, line.length()).trim();
						map.remove(key);
					} else if (line.startsWith("put ")) {
						line = line.replace("put ", "");
						int index = line.indexOf("=");
						if (index <= 0 || index >= (line.length() - 1)) {
							System.out.println("invalid input");
							continue;
						}
						String key = line.substring(0, index).trim();
						String value = line.substring(index + 1, line.length())
								.trim();
						map.put(key, value);
					} else {
						System.out.println("invalid input: " + line);
						continue;
					}
				}
			}
			succeed = true;
		} finally {
			if (br != null) {
				try {
					br.close();
				} catch (Exception e) {
					if (succeed) {
						throw e;
					}
				}
			}
		}
	}

	private String printMap(Map<String, String> m) {
		StringBuffer sb = new StringBuffer();
		sb.append("[");
		for (Iterator<String> iter = map.keySet().iterator(); iter.hasNext();) {
			String key = iter.next();
			String value = map.get(key);
			sb.append(key).append("=").append(value);
			if (iter.hasNext()) {
				sb.append(",");
			}
		}
		sb.append("]");
		return sb.toString();
	}

	public static void main(String args[]) {
		try {
			new ReplicatedHashMapTest().start();
		} catch (Exception e) {
			e.printStackTrace();
		}
	}
}

3．4 NotificationBus
    NotificationBus 提供了向集群发送通知的能力，通知可以是任何可以被序列化的对象。NotificationBus在内部使用Channel，其start()和stop()方法用于启动和停止。NotificationBus的setConsumer()方法用于注册Consumer接口，其定义如下：

public interface Consumer {
    void handleNotification(Serializable n);
    Serializable getCache();
    void memberJoined(Address mbr);
    void memberLeft(Address mbr);
}

    NotificationBus的getCacheFromCoordinator() 和getCacheFromMember()用于请求集群的状态。前者是从coordinator得到状态，后者从指定地址的成员处得到状态。NotificationBus上注册的Consumer需要实现getCache()方法以返回状态。以下是个简单的例子：

import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.io.Serializable;
import java.util.Iterator;
import java.util.LinkedList;

import org.jgroups.Address;
import org.jgroups.blocks.NotificationBus;

public class NotificationBusTest implements NotificationBus.Consumer {
	//
	private NotificationBus bus;
	private LinkedList<Serializable> cache;

	public void handleNotification(Serializable n) {
		System.out.println("in handleNotification(" + n + ")");
		if (cache != null) {
			cache.add(n);
		}
	}

	public Serializable getCache() {
		return cache;
	}

	public void memberJoined(Address mbr) {
		System.out.println("in memberJoined(" + mbr + ")");
	}

	public void memberLeft(Address mbr) {
		System.out.println("in memberLeft(" + mbr + ")");
	}

	@SuppressWarnings("unchecked")
	public void start() throws Exception {
		//
		bus = new NotificationBus("NotificationBusTest", null);
		bus.setConsumer(this);
		bus.start();
		cache = (LinkedList<Serializable>) bus.getCacheFromCoordinator(3000, 1);
		if (cache == null) {
			cache = new LinkedList<Serializable>();
		}
		System.out.println(printCache(cache));

		//
		sendNotification();

		//
		bus.stop();
	}

	private void sendNotification() throws Exception {
		boolean succeed = false;
		BufferedReader br = null;
		try {
			br = new BufferedReader(new InputStreamReader(System.in));
			while (true) {
				System.out.print("> ");
				System.out.flush();
				String line = br.readLine();
				if (line != null && line.equals("exit")) {
					break;
				} else {
					bus.sendNotification(line);
				}
			}
			succeed = true;
		} finally {
			if (br != null) {
				try {
					br.close();
				} catch (Exception e) {
					if (succeed) {
						throw e;
					}
				}
			}
		}
	}

	private String printCache(LinkedList<Serializable> c) {
		StringBuffer sb = new StringBuffer();
		sb.append("[");
		for (Iterator<Serializable> iter = c.iterator(); iter.hasNext();) {
			sb.append(iter.next());
			if (iter.hasNext()) {
				sb.append(",");
			}
		}
		sb.append("]");
		return sb.toString();
	}

	public static void main(String[] args) {
		try {
			new NotificationBusTest().start();
		} catch (Exception e) {
			e.printStackTrace();
		}
	}
}