biz.chitec.quarterback.util
Class TalkingMap

java.lang.Object
  biz.chitec.quarterback.util.TalkingMap

All Implemented Interfaces:

java.util.Map

public class TalkingMap

extends java.lang.Object

implements java.util.Map

Map featuring a property event sending mechanism on changing data. TalkingMap implements the Map interface and backs the complete map handling stuff to another map, either user-given or an internally created HashMap. TalkingMap's access methods are extended, however, by some calling means of an internally provided PropertyChangeSupport element. Any changes done in the internal map by the access methods of TalkingMap result in PropertyChangeEvents sent to all connected listeners. TalkingMap knows two modes for sending events. Either, the event is sent immediately after the change in the map or changes are collected in a "transaction" and a special event is sent at the end of the transaction. This mode is useful especially if many changes have to be done or some changes should be handled only together and not separatly. It is always guaranteed that the event is sent after the change took place. The old value is always sent within the event. For insertions, the old value is null. For deletions, the new value is null. Changes which do not change something do not raise an event, this is handled within the PropertyChangeSupport. The generated events contain the key of the changed property as property name. Therefore, map keys should be either String objects or provide meaningful representations via the toString() method. Events generated internally by the TalkingMap (e.g. start and end of a transaction) always begin with an underscore, "_", therefore the map's keys should not begin with an underscore. The current implementation of TalkingMap is incomplete as it does not provide encapsulations of the map's sets (entrySet, keySet). Changes to the map done through these sets are not recognized by the TalkingMap. Of course, if the map is user-defined and changed directly though its own methods, changed aren't recognized by the TalkingMap, either.

Version:

$Id: 47b3bcb04a51202b34d5146d3a435e8702a98145 $

Author:

cantamen/Dirk Hillbrecht 2003-2004

Nested Class Summary

Nested classes inherited from class java.util.Map

java.util.Map.Entry

Field Summary

private boolean	autocleartransaction
private boolean	intransaction
private java.util.Map	map
private java.beans.PropertyChangeSupport	pcs
private java.util.Set	transactionparts

Constructor Summary

TalkingMap()
Creates a new instance backing the data storage with an internally created, non synchronized HashMap.

TalkingMap(java.util.Map delegate)
Creates a new instance backing the data storage by a user-provided map

Method Summary

void	addPropertyChangeListener(java.beans.PropertyChangeListener listener)
void	addPropertyChangeListener(java.lang.String propertyName, java.beans.PropertyChangeListener listener)
void	clear() Clears the map with informing listeners.
void	commitTransaction() Commits a transaction of several entry changes.
boolean	containsKey(java.lang.Object key)
boolean	containsValue(java.lang.Object value)
java.util.Set	entrySet()
java.lang.Object	get(java.lang.Object key)
java.beans.PropertyChangeListener[]	getPropertyChangeListeners()
java.beans.PropertyChangeListener[]	getPropertyChangeListeners(java.lang.String propertyName)
boolean	hasListeners(java.lang.String propertyName)
boolean	isAutoClearTransaction() Asks whether the clear method will encapsulate itself into a transaction automatically.
boolean	isEmpty()
boolean	isInTransaction() Returns whether a transaction is currently running
java.util.Set	keySet()
java.lang.Object	put(java.lang.Object key, java.lang.Object value)
void	putAll(java.util.Map t)
java.lang.Object	remove(java.lang.Object key)
void	removePropertyChangeListener(java.beans.PropertyChangeListener listener)
void	removePropertyChangeListener(java.lang.String propertyName, java.beans.PropertyChangeListener listener)
void	setAutoClearTransaction(boolean b) Sets whether the clear method should encapsulate itself into a transaction automatically.
int	size()
void	startTransaction() Starts an unnamed transaction.
void	startTransaction(java.lang.String name) Starts a transaction cumulating several changes to the map without sending events.
java.lang.String	toString()
java.util.Collection	values()

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface java.util.Map

equals, hashCode

Field Detail

map

private java.util.Map map

pcs

private java.beans.PropertyChangeSupport pcs

intransaction

private boolean intransaction

autocleartransaction

private boolean autocleartransaction

transactionparts

private java.util.Set transactionparts

Constructor Detail

TalkingMap

public TalkingMap(java.util.Map delegate)

Creates a new instance backing the data storage by a user-provided map

TalkingMap

public TalkingMap()

Creates a new instance backing the data storage with an internally created, non synchronized HashMap.

Method Detail

addPropertyChangeListener

public void addPropertyChangeListener(java.beans.PropertyChangeListener listener)

addPropertyChangeListener

public void addPropertyChangeListener(java.lang.String propertyName,
                                      java.beans.PropertyChangeListener listener)

getPropertyChangeListeners

public java.beans.PropertyChangeListener[] getPropertyChangeListeners()

getPropertyChangeListeners

public java.beans.PropertyChangeListener[] getPropertyChangeListeners(java.lang.String propertyName)

hasListeners

public boolean hasListeners(java.lang.String propertyName)

removePropertyChangeListener

public void removePropertyChangeListener(java.beans.PropertyChangeListener listener)

removePropertyChangeListener

public void removePropertyChangeListener(java.lang.String propertyName,
                                         java.beans.PropertyChangeListener listener)

startTransaction

public void startTransaction(java.lang.String name)

Starts a transaction cumulating several changes to the map without sending events. After this call, a "_TRANSACTIONSTART" event is fired. Then, no further event occur until the transaction is defined to be finished. Instead, the keys of all changed map entries are stored into a set which is sent on finishing the transaction.

Parameters:

name - A transaction name which is sent as new value in the fired event.

startTransaction

public void startTransaction()

Starts an unnamed transaction.

isInTransaction

public boolean isInTransaction()

Returns whether a transaction is currently running

commitTransaction

public void commitTransaction()

Commits a transaction of several entry changes. This method fires a "_TRANSACTIONEND" event. Its new value contains a Set with all entry key which have been changed during the transaction. Receivers can decide upon this information whether they wanna do something or not.

setAutoClearTransaction

public void setAutoClearTransaction(boolean b)

Sets whether the clear method should encapsulate itself into a transaction automatically.

isAutoClearTransaction

public boolean isAutoClearTransaction()

Asks whether the clear method will encapsulate itself into a transaction automatically.

size

public int size()

Specified by:

size in interface java.util.Map

clear

public void clear()

Clears the map with informing listeners. In transaction mode, all keys are collected and the map is simply cleared. In non-transaction mode, a change event is sent on each element and everything is removed on its own. Therefore, this method is much, much faster within a transaction than without.

Specified by:

clear in interface java.util.Map

isEmpty

public boolean isEmpty()

Specified by:

isEmpty in interface java.util.Map

containsKey

public boolean containsKey(java.lang.Object key)

Specified by:

containsKey in interface java.util.Map

containsValue

public boolean containsValue(java.lang.Object value)

Specified by:

containsValue in interface java.util.Map

values

public java.util.Collection values()

Specified by:

values in interface java.util.Map

putAll

public void putAll(java.util.Map t)

Specified by:

putAll in interface java.util.Map

entrySet

public java.util.Set entrySet()

Specified by:

entrySet in interface java.util.Map

keySet

public java.util.Set keySet()

Specified by:

keySet in interface java.util.Map

get

public java.lang.Object get(java.lang.Object key)

Specified by:

get in interface java.util.Map

remove

public java.lang.Object remove(java.lang.Object key)

Specified by:

remove in interface java.util.Map

put

public java.lang.Object put(java.lang.Object key,
                            java.lang.Object value)

Specified by:

put in interface java.util.Map

toString

public java.lang.String toString()