Coverage details for edu.uci.ics.jung.utils.UserData

LineHitsSource
1 /*
2  * Copyright (c) 2003, the JUNG Project and the Regents of the University of
3  * California All rights reserved.
4  *
5  * This software is open-source under the BSD license; see either "license.txt"
6  * or http://jung.sourceforge.net/license.txt for a description.
7  */
8 package edu.uci.ics.jung.utils;
9  
10 import java.util.Iterator;
11  
12 /**
13  * Represents custom user- and system-level information to extend the definition
14  * of a node. This is the easiest way to extend the class without subclassing.
15  *
16  * This works as a dictionary in order to help ensure that there are
17  * possibilities for extending user information to a variety of different sorts
18  * of data. (Each provider of information can register their own enhanced
19  * information without interfering with other providers.)
20  *
21  * Some suggested uses of UserData include
22  * <ul>
23  * <li/>Underlying data references, such as pointers to data sources</li>
24  * <li/>Raw data which can be analyzed or used by the constraint and filter systems
25  * <li/>Temporary enhanced information which can be used for visualization
26  * </ul>
27  *
28  * Consider a series of nodes that has, among other things, enhanced information
29  * about 3D coordinates. This might be stored in the 3DData data structure,
30  * which generates itself with an input from a node.
31  *
32  * Thus the relevant call might be <code>n.setUserInfo ("3DData", new 3DData (
33  * ))</code>.
34  * Later, to access this information, the call might be <code>3DData dd =
35  * (3DData) n.getUserInfo("3DData").</code>
36  *
37  * <h3>Shared and Individual Data</h3>
38  * Note that the there are no required semantics for the key or the information.
39  * However, it is necessary to specify information that is used for SHARED and
40  * for INDIVIDUAL data elements. When a new View of a graph is
41  * generated, the Node elements inside it are all shallow-copied. The UserInfo
42  * that they use, however, is <em>not</em> copied, by default. This is the
43  * correct and logical behavior if the UserInfo contains source information.
44  *
45  * But what when the UserInfo contains transient information, specific to the
46  * view, such as graph metrics or coordinates? In that case, the UserInfo would
47  * be quite inappropriate to share that information between copies.
48  *
49  * The solution to this is to add a third flag, "shared", which tells whether
50  * the currect data is shared or not. This flag is assigned when the data is
51  * added.
52  */
53179674public abstract class UserData implements UserDataContainer {
54  
55     /**
56      * @see java.lang.Object#toString()
57      */
58     public String toString() {
590        StringBuffer sb = new StringBuffer();
600        for (Iterator iter = getUserDatumKeyIterator(); iter.hasNext();) {
610            Object key = (Object) iter.next();
620            sb.append(key);
630            sb.append("=");
640            sb.append(getUserDatum(key));
650            if( iter.hasNext()) {
660                sb.append(", ");
67             }
68         }
690        return "USERDATA [" + sb + "]";
70     }
71  
72     public Object clone() throws CloneNotSupportedException
73     {
741749        return super.clone();
75     }
76     
77     /**
78      * A CopyAction that clones UserData--that is, it uses the Java
79      * {@link java.lang.Object#clone() clone()}call to clone the object. Throws
80      * a <tt>CloneNotSupportedException</tt> if clone isn't allowed.
81      */
8275    public static final CopyAction CLONE = new CopyAction.Clone();
83  
84     /**
85      * A CopyAction that links UserData--that is, points to the original data.
86      * At that point, both UserDataContainers will contain references to the
87      * same UserData, and, if that data is mutable, will both see changes to it.
88      * (In the case of immutable user data, such as Strings, they will
89      * disconnect if one or the other attempts to change its value: this is the
90      * normal behavior with <code>
91      * String s = "X";
92      * String t = s;
93      * s = "Y";
94      * System.out.pritnln( t ); // will still contain X.
95      * </code>
96      */
9775    public static final CopyAction SHARED = new CopyAction.Shared();
98  
99     /**
100      * Causes the userdata not to be copied over, and instead returns null.
101      * Useful for temporary userdata that isn't meant to be used.
102      */
10375    public static final CopyAction REMOVE = new CopyAction.Remove();
104  
105 }

this report was generated by version 1.0.5 of jcoverage.
visit www.jcoverage.com for updates.

copyright © 2003, jcoverage ltd. all rights reserved.
Java is a trademark of Sun Microsystems, Inc. in the United States and other countries.