edu.uci.ics.jung.utils
Class UnifiedUserData

java.lang.Object
  extended by edu.uci.ics.jung.utils.UserData
      extended by edu.uci.ics.jung.utils.UnifiedUserData
All Implemented Interfaces:
UserDataContainer, UserDataFactory, Cloneable

public class UnifiedUserData
extends UserData
implements UserDataFactory

Represents custom user- and system-level information to extend the definition of a node. This is the easiest way to extend the class without subclassing. This works as a dictionary in order to help ensure that there are possibilities for extending user information to a variety of different sorts of data. (Each provider of information can register their own enhanced information without interfering with other providers.) Some suggested uses of UserData include

Consider a series of nodes that has, among other things, enhanced information about 3D coordinates. This might be stored in the 3DData data structure, which generates itself with an input from a node. Thus the relevant call might be n.addUserDatum("3DData", new 3DData ( )). Later, to access this information, the call might be 3DData dd = (3DData) n.getUserDatum("3DData").

Shared and Individual Data

Note that the there are no required semantics for the key or the information. However, it is necessary to specify information that is used for SHARED and for INDIVIDUAL data elements. When a new View of a graph is generated, the Node elements inside it are all shallow-copied. The UserData that they use, however, is not copied, by default. This is the correct and logical behavior if the UserData contains source information. But what when the UserData contains transient information, specific to the view, such as graph metrics or coordinates? In that case, the UserData would be quite inappropriate to share that information between copies. The solution to this is to add a third flag, "shared", which tells whether the currect data is shared or not. This flag is assigned when the data is added.


Nested Class Summary
 
Nested classes/interfaces inherited from interface edu.uci.ics.jung.utils.UserDataContainer
UserDataContainer.CopyAction
 
Field Summary
protected static Map key_meta_map
           
 
Fields inherited from class edu.uci.ics.jung.utils.UserData
CLONE, REMOVE, SHARED
 
Constructor Summary
UnifiedUserData()
           
 
Method Summary
 void addUserDatum(Object key, Object value, UserDataContainer.CopyAction shared)
          Adds user-level information to the node.
 Object clone()
           
 boolean containsUserDatumKey(Object key)
          Reports whether key is a key of this user data container.
 UserDataContainer getInstance()
          Returns a single UserDataContainer instance.
protected  Map getKeyMap(Object key)
           
 Object getUserDatum(Object key)
          Returns UserData (if any) for this key, or null if not known.
 UserDataContainer.CopyAction getUserDatumCopyAction(Object key)
          Returns the CopyAction associated with this key.
 Iterator getUserDatumKeyIterator()
          Returns an Iterator which can be used to iterate over all the user data repository keys for this object.
protected  Pair getUserDatumValuePair(Object key)
           
 void importUserData(UserDataContainer udc)
          Uses the CopyAction to determine how each of the user datum elements in udc should be carried over to the this UserDataContiner
 Object removeUserDatum(Object key)
          Removes the Datum (if any) for this key, and returns it.
 void setUserDatum(Object key, Object value, UserDataContainer.CopyAction shared)
          Changes the user-level information to the object.
 
Methods inherited from class edu.uci.ics.jung.utils.UserData
toString
 
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

key_meta_map

protected static final Map key_meta_map
Constructor Detail

UnifiedUserData

public UnifiedUserData()
Method Detail

getKeyMap

protected Map getKeyMap(Object key)

addUserDatum

public void addUserDatum(Object key,
                         Object value,
                         UserDataContainer.CopyAction shared)
Adds user-level information to the node. Throws an exception if the node already has information associated with it.

Specified by:
addUserDatum in interface UserDataContainer
Parameters:
key - A unique (per type, not per node) key into the information
value - The extended information associated with the node
shared - the CopyAction of the datum being added

importUserData

public void importUserData(UserDataContainer udc)
Uses the CopyAction to determine how each of the user datum elements in udc should be carried over to the this UserDataContiner

Specified by:
importUserData in interface UserDataContainer
Parameters:
udc - The UserDataContainer whose user data is being imported

setUserDatum

public void setUserDatum(Object key,
                         Object value,
                         UserDataContainer.CopyAction shared)
Changes the user-level information to the object. Equivalent to calling
   removeUserDatum( key );      
   addUserDatum(key, value) 
 

Specified by:
setUserDatum in interface UserDataContainer
Parameters:
key -
value -
shared - the CopyAction for the new (key, datum) pair

getUserDatum

public Object getUserDatum(Object key)
Returns UserData (if any) for this key, or null if not known.

Specified by:
getUserDatum in interface UserDataContainer
Parameters:
key -
Returns:
Object the datum retrieved

getUserDatumValuePair

protected Pair getUserDatumValuePair(Object key)

removeUserDatum

public Object removeUserDatum(Object key)
Removes the Datum (if any) for this key, and returns it.

Specified by:
removeUserDatum in interface UserDataContainer
Parameters:
key -
Returns:
Object the datum removed

getUserDatumKeyIterator

public Iterator getUserDatumKeyIterator()
Returns an Iterator which can be used to iterate over all the user data repository keys for this object.

Specified by:
getUserDatumKeyIterator in interface UserDataContainer
Returns:
Iterator

containsUserDatumKey

public boolean containsUserDatumKey(Object key)
Description copied from interface: UserDataContainer
Reports whether key is a key of this user data container.

Specified by:
containsUserDatumKey in interface UserDataContainer
Parameters:
key - the key to be queried
Returns:
true if key is present in this user data container
See Also:
UserDataContainer.containsUserDatumKey(Object)

getUserDatumCopyAction

public UserDataContainer.CopyAction getUserDatumCopyAction(Object key)
Returns the CopyAction associated with this key.

Specified by:
getUserDatumCopyAction in interface UserDataContainer
Parameters:
key -
Returns:
CopyAction

getInstance

public UserDataContainer getInstance()
Description copied from interface: UserDataFactory
Returns a single UserDataContainer instance. Depending on the architecture involved, this may be a singleton instance, or a new instance may be generated each time the method is called.

Specified by:
getInstance in interface UserDataFactory

clone

public Object clone()
             throws CloneNotSupportedException
Specified by:
clone in interface UserDataContainer
Overrides:
clone in class UserData
Throws:
CloneNotSupportedException