mirrormap
Class MirrorMap<K extends Serializable,V extends Serializable>

java.lang.Object
  mirrormap.collections.NotifyingMap<K,V>
      mirrormap.MirrorMap<K,V>

Type Parameters:

K - The key type for the map

V - The value type for the map

All Implemented Interfaces:

Map<K,V>

public class MirrorMap<K extends Serializable,V extends Serializable>
extends NotifyingMap<K,V>

MirrorMap is a replicating Java map implementation. Its key features are:

• Replicates changes to remote instances
• Can detect when the map contents change
• Can detect when a local map is connected and disconnected from remote instances
• Can detect when peers of a map are connected and disconnected

A MirrorMap wraps any standard Java map implementation and decorates it with the ability to replicate changes with other remote MirrorMap instances. A MirrorMap is given a name, replication occurs with remote instances of the same name. Both the map key and value need to implement the Serializable interface.

MirrorMap is built on top of a NotifyingMap; this is a Map implementation that has the ability to notify observer objects when map entries are added, updated or removed. The operations to the map are further categorised into a 'before' and 'after' events e.g. when adding an entry to a NotifyingMap, observers receive a 'will add' notification, the entry is added, then the observers receive a 'did add' notification. A similar for pattern follows for update and remove operations.

Logically, replication is peer-to-peer. Physically, all peer communication is done using a server component. The server holds the master copy of the named MirrorMap. New peers register with the server for replication and will receive the full map image upon registration. The connection with the server is point-to-point using TCP; the server performs the fan out of changes to all peers.

MirrorMap is written using the Java NIO library. A mirror map has a single I/O thread dealing with network communication. The mirror map server ( server(String, int)) creates 2 threads; one to handle reading and one to handle writing.

Author:

Ramon Servadei

Nested Class Summary

Nested classes/interfaces inherited from interface java.util.Map

Map.Entry<K,V>

Method Summary

static boolean	connect(MirrorMap<? extends Serializable,? extends Serializable> map, String host, int port) Connects the passed in MirrorMap to the mirror map server identified by the host and port.
static <Key extends Serializable,Value extends Serializable> MirrorMap<Key,Value>	create(String name, Map<Key,Value> data) Create a MirrorMap identified by a unique name that wraps the passed in Map.
static boolean	disconnect(MirrorMap<? extends Serializable,? extends Serializable> map) Disconnects the passed in MirrorMap from the mirror map server.
static <Key extends Serializable,Value extends Serializable> MirrorMap<Key,Value>	get(String name) Get the MirrorMap identified by the name.
IMirrorMapConnectionListener	getConnectionListener() Get the connection listener attached to this mirror map
String	getName() The name of this instance
static TcpServer	server(String address, int port) Create a TcpServer with the corresponding server socket details.
void	setConnectionListener(IMirrorMapConnectionListener listener) Set the IMirrorMapConnectionListener on this mirror map
String	toString()

Methods inherited from class mirrormap.collections.NotifyingMap

addListener, clear, containsKey, containsValue, entrySet, equals, get, hashCode, isEmpty, keySet, put, putAll, remove, removeListener, size, values

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Method Detail

create

public static <Key extends Serializable,Value extends Serializable> MirrorMap<Key,Value> create(String name,
                                                                                                Map<Key,Value> data)

Create a MirrorMap identified by a unique name that wraps the passed in Map. If the mirror map already exists, the current instance is returned and nothing is done with the Map argument.

Type Parameters:

Key -

Value -

Parameters:

name - the name identifying the MirrorMap

data - the underlying Map for the MirrorMap

Returns:

a MirrorMap or null if there is none for this name

get

public static <Key extends Serializable,Value extends Serializable> MirrorMap<Key,Value> get(String name)

Get the MirrorMap identified by the name.

Type Parameters:

Key -

Value -

Parameters:

name - the name identifying the MirrorMap

Returns:

a MirrorMap or null if there is none for this name

connect

public static boolean connect(MirrorMap<? extends Serializable,? extends Serializable> map,
                              String host,
                              int port)

Connects the passed in MirrorMap to the mirror map server identified by the host and port. After this method completes, the instance will receive changes from remote instances and local updates will be sent to the server for distribution to other instances.

Parameters:

map - the map to connect

host - the host or IP of the mirror map server to connect to

port - the port of the mirror map server to connect to

Returns:

true if the map was connected, false otherwise

disconnect

public static boolean disconnect(MirrorMap<? extends Serializable,? extends Serializable> map)

Disconnects the passed in MirrorMap from the mirror map server. After this method completes, the instance will no longer receive changes from remote instances and local updates will no longer be sent to the server for distribution to other instances.

Parameters:

map - the instance to disconnect

Returns:

true if the map was disconnected, false otherwise

server

public static TcpServer server(String address,
                               int port)

Create a TcpServer with the corresponding server socket details. The returned server will be started.

Parameters:

address - the IP address or host name for the server socket

port - the TCP port for the server socket

Returns:

a TcpServer

getName

public String getName()

The name of this instance

Returns:

the name of this MirrorMap

toString

public String toString()

Overrides:

toString in class NotifyingMap<K extends Serializable,V extends Serializable>

setConnectionListener

public void setConnectionListener(IMirrorMapConnectionListener listener)

Set the IMirrorMapConnectionListener on this mirror map

Parameters:

listener - the listener to set

getConnectionListener

public IMirrorMapConnectionListener getConnectionListener()

Get the connection listener attached to this mirror map

Returns:

the IMirrorMapConnectionListener attached to this instance