edu.uci.ics.jung.utils
Class UserData

java.lang.Object
  edu.uci.ics.jung.utils.UserData

All Implemented Interfaces:

java.lang.Cloneable, UserDataContainer

Direct Known Subclasses:

AbstractArchetypeGraph, AbstractSparseEdge, AbstractSparseVertex

public class UserData

extends java.lang.Object

implements UserDataContainer, java.lang.Cloneable

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

• Underlying data references, such as pointers to data sources
• Raw data which can be analyzed or used by the constraint and filter systems
• Temporary enhanced information which can be used for visualization

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.setUserInfo ("3DData", new 3DData ( )). Later, to access this information, the call might be 3DData dd = (3DData) n.getUserInfo("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 UserInfo that they use, however, is not copied, by default. This is the correct and logical behavior if the UserInfo contains source information. But what when the UserInfo contains transient information, specific to the view, such as graph metrics or coordinates? In that case, the UserInfo 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 inherited from class edu.uci.ics.jung.utils.UserDataContainer

UserDataContainer.CopyAction

Field Summary

static UserDataContainer.CopyAction	CLONE A CopyAction that clones UserData--that is, it uses the Java clone()call to clone the object.
static UserDataContainer.CopyAction	REMOVE Causes the userdata not to be copied over, and instead returns null.
static UserDataContainer.CopyAction	SHARED A CopyAction that links UserData--that is, points to the original data.

Constructor Summary

UserData()

Method Summary

void	addUserDatum(java.lang.Object key, java.lang.Object value, UserDataContainer.CopyAction shared) Adds user-level information to the node.
boolean	containsUserDatumKey(java.lang.Object key) Reports whether key is a key of this user data container.
java.lang.Object	getUserDatum(java.lang.Object key) Returns UserInfo (if known) for this key, or null if not known.
UserDataContainer.CopyAction	getUserDatumCopyAction(java.lang.Object key) Returns the CopyAction associated with this key.
java.util.Iterator	getUserDatumKeyIterator() Iterates through the keys to all registered data.
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
java.lang.Object	removeUserDatum(java.lang.Object key) Removes the Datum (if known) for this key, and returns it.
void	setUserDatum(java.lang.Object key, java.lang.Object value, UserDataContainer.CopyAction shared) Changes the user-level information to the object.
java.lang.String	toString()

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

CLONE

public static final UserDataContainer.CopyAction CLONE

A CopyAction that clones UserData--that is, it uses the Java clone()call to clone the object. Throws a CloneNotSupportedException if clone isn't allowed.

SHARED

public static final UserDataContainer.CopyAction SHARED

A CopyAction that links UserData--that is, points to the original data. At that point, both UserDataContainers will contain references to the same UserData, and, if that data is mutable, will both see changes to it. (In the case of immutable user data, such as Strings, they will disconnect if one or the other attempts to change its value: this is the normal behavior with String s = "X"; String t = s; s = "Y"; System.out.pritnln( t ); // will still contain X.

REMOVE

public static final UserDataContainer.CopyAction REMOVE

Causes the userdata not to be copied over, and instead returns null. Useful for temporary userdata that isn't meant to be used.

Constructor Detail

UserData

public UserData()

Method Detail

addUserDatum

public void addUserDatum(java.lang.Object key,
                         java.lang.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(java.lang.Object key,
                         java.lang.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 java.lang.Object getUserDatum(java.lang.Object key)

Returns UserInfo (if known) for this key, or null if not known.

Specified by:

getUserDatum in interface UserDataContainer

Parameters:

key -

Returns:

Object the datum retrieved

removeUserDatum

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

Removes the Datum (if known) for this key, and returns it.

Specified by:

removeUserDatum in interface UserDataContainer

Parameters:

key -

Returns:

Object the datum removed

getUserDatumKeyIterator

public java.util.Iterator getUserDatumKeyIterator()

Iterates through the keys to all registered data. Note: there's no easy way to know, looking at a piece of data, whether it is or is not shared.

Specified by:

getUserDatumKeyIterator in interface UserDataContainer

Returns:

Iterator

containsUserDatumKey

public boolean containsUserDatumKey(java.lang.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(java.lang.Object key)

Returns the CopyAction associated with this key.

Specified by:

getUserDatumCopyAction in interface UserDataContainer

Parameters:

key -

Returns:

CopyAction

toString

public java.lang.String toString()

See Also:

Object.toString()