Cytoscape Wiki
Cytoscape RFC #1: Replacing Graph Obj Attributes
This is an official Request for Comment (RFC) for replacing GraphObjAttributes.
Status: Version 0.1 of the proposal is below. This represents Ethan's first stab at creating a new API.
How to Comment: To view/add comments, click on any of 'Comment' links below. By adding your ideas to the Wiki directly, we can more easily organize everyone's ideas, and keep clear records. Be sure to include today's date and your name for each comment. Here is an example to get things started: ["RFC1_Comment_Name"].
<FONT COLOR=BLUE>Try to keep your comments as concrete and constructive as possible. For example, if you find a part of the API makes no sense, please say so, but don't stop there. Take the extra step and propose alternatives.</FONT>
General Notes:
I propose that the interface be called AttributeData, rather than CytoscapeData. I think this is more descriptive, and besides, not all our classes have to have the word Cytoscape in it. ["RFC1_Comment_Name"]
We provide several overloaded version of setAttribute, one for each basic data type, e.g. setAttribute(String id, String attributeName, double value). We also provide several varients of getAttribute, e.g. Double getDoubleAttribute(String id, String attributeName). ["RFC1_Comment_Getters_Setters"]
AttributeData provides support for 'simple' lists. By simple, I mean that each list can only contain Objects of type: Boolean, Integer, Double and String, and each item must be of the same data type. AttributeData enforces this requirement explicitly. See proposed API below. ["RFC1_Comment_Lists"]
AttributeData provides support for 'simple' maps. By simple, I mean that all keys in the map must be of type String, and all values must be of the same type, and must be one of: Boolean, Integer, Double, and String. AttributeData enforces these requirement explicitly. See proposed API below. ["RFC1_Comment_Maps"]
To do complicated things, such as create arbitarily complex data structures, you can obtain a copy of CyData and CyDataDefinition from AttributeData. Advanced users who need this functionality can read through the CyData and CyDataDefinition Javadocs. ["RFC1_Comment_Complex_Data_Structures"]
- Item not yet covered: Event / Listener Framework ["RFC1_Comment_Event_Framework"]
Item not yet covered: support for Labels (Rowan has this feature in the current implementation of CytoscapeData) ["RFC1_Comment_Labels"]
Proposed API: Version 0.1
1 package cytoscape.data;
2
3 import cytoscape.data.attr.CyData;
4 import cytoscape.data.attr.CyDataDefinition;
5
6 import java.util.List;
7 import java.util.Map;
8
9 /**
10 * Proposed API for AttributeData Interface.
11 *
12 * [Lots of descriptive comments here...]
13 */
14 public interface AttributeData {
15
16 /**
17 * Gets a List of All Attribute Names.
18 *
19 * @return An Array of String Objects.
20 */
21 public String[] getAttributeNames();
22
23 /**
24 * Determines if the specified id/attributeName pair exists.
25 *
26 * @param id unique identifier.
27 * @param attributeName attribute name.
28 * @return true or false.
29 */
30 public boolean hasAttribute(String id, String attributeName);
31
32 /**
33 * Sets an id/attributeName pair of type boolean.
34 *
35 * @param id unique identifier.
36 * @param attributeName attribute name.
37 * @param value boolean value.
38 */
39 public void setAttribute(String id, String attributeName, boolean value);
40
41 /**
42 * Sets an id/attributeName pair of type integer.
43 *
44 * @param id unique identifier.
45 * @param attributeName attribute name.
46 * @param value integer value.
47 */
48 public void setAttribute(String id, String attributeName, int value);
49
50 /**
51 * Sets an id/attributeName pair of type double.
52 *
53 * @param id unique identifier.
54 * @param attributeName attribute name.
55 * @param value double value.
56 */
57 public void setAttribute(String id, String attributeName, double value);
58
59 /**
60 * Sets an id/attributeName pair of type String.
61 *
62 * @param id unique identifier.
63 * @param attributeName attribute name.
64 * @param value string value.
65 */
66 public void setAttribute(String id, String attributeName, String value);
67
68 /**
69 * Gets a boolean value at the specified id/attributeName.
70 * <P>If attributeName refers to a List, the zeroeth element in
71 * that list is returned.
72 *
73 * @param id unique identifier.
74 * @param attributeName attribute name.
75 * @return Boolean object, or null if no id/attributeName pair is found.
76 * @throws ClassCastException Indicates that the specified attribute
77 * is not of type Boolean.
78 */
79 public Boolean getBooleanAttribute(String id, String attributeName)
80 throws ClassCastException;
81
82 /**
83 * Gets an integer value at the specified id/attributeName.
84 * <P>If attributeName refers to a List, the zeroeth element in
85 * that list is returned.
86 *
87 * @param id unique identifier.
88 * @param attributeName attribute name.
89 * @return Integer object, or null if no id/attributeName pair is found.
90 * @throws ClassCastException Indicates that the specified attribute
91 * is not of type Integer.
92 */
93 public Integer getIntegerAttribute(String id, String attributeName)
94 throws ClassCastException;
95
96 /**
97 * Gets a double value at the specified id/attributeName.
98 * <P>If attributeName refers to a List, the zeroeth element in
99 * that list is returned.
100 *
101 * @param id unique identifier.
102 * @param attributeName attribute name.
103 * @return Double object, or null if no id/attributeName pair is found..
104 * @throws ClassCastException Indicates that the specified attribute
105 * is not of type Double.
106 */
107 public Double getDoubleAttribute(String id, String attributeName)
108 throws ClassCastException;
109
110 /**
111 * Gets a String value at the specified id/attributeName.
112 * <P>If attributeName refers to a List, the zeroeth element
113 * in that list is returned.
114 *
115 * @param id unique identifier.
116 * @param attributeName attribute name.
117 * @return String object, or null if no id/attributeName pair is found.
118 * @throws ClassCastException Indicates that the specified attribute
119 * is not of type String.
120 */
121 public String getStringAttribute(String id, String attributeName)
122 throws ClassCastException;
123
124 /**
125 * Gets the Class of the specified attribute.
126 *
127 * @param attributeName Attribute Name.
128 * @return Return type will be of type: Boolean, Integer, Double,
129 * String, List or Map. If attributeName has not been
130 * defined, this method will return null.
131 */
132 public Class getClass(String attributeName);
133
134 /**
135 * Delete the id/attributeName pair.
136 *
137 * @param id unique identifier.
138 * @param attributeName attribute name.
139 * @return true indicates attribute was
140 * successfully removed.
141 */
142 public boolean deleteAttribute(String id, String attributeName);
143
144 /**
145 * Sets a List of Attributes.
146 * <P><B>Note:</B>
147 * <UL>
148 * <LI>All items within the list must be of the same type,
149 * and and chosen from the following list: Boolean, Integer, Double,
150 * or String.
151 * </LI>
152 * </UL>
153 * If the above requirement is not met, an IllegalArgumentException
154 * will be thrown.
155 *
156 * @param id unique identifier.
157 * @param list attribute name.
158 * @param list List Object.
159 */
160 public void setAttributeList(String id, String attributeName, List list)
161 throws IllegalArgumentException;
162
163 /**
164 * Gets a List of attributes for the id/attributeName pair.
165 *
166 * @param id unique identifier.
167 * @param attributeName attribute name.
168 * @return List object.
169 * @throws ClassCastException Indicates that the specified attribute
170 * is not of type List.
171 */
172 public List getAttributeList(String id, String attributeName)
173 throws ClassCastException;
174
175 /**
176 * Sets a Map of Attribute Values.
177 * <P><B>Note:</B>
178 * <UL>
179 * <LI>All keys within the Map must be of type String.
180 * <LI>All values within the Map must be of the same type,
181 * and chosen from the following list: Boolean, Integer,
182 * Double, or String.
183 * </UL>
184 * If the above requirements are not met, an IllegalArgumentException
185 * will be thrown.
186 *
187 * @param id unique identifier.
188 * @param attributeName attribute name.
189 * @param map Map Object.
190 */
191 public void setAttributeMap(String id, String attributeName,
192 Map map);
193
194 /**
195 * Gets a Map of Attribute Value.
196 *
197 * @param id unique identifier.
198 * @param attributeName attribute name.
199 * @return Map Object.
200 */
201 public Map getAttributeMap(String id, String attributeName);
202
203 /**
204 * Gets the CyData Object, which stores the actual attribute values.
205 * <P>By using CyData and CyDataDefintion directly, you can store
206 * arbitrarily complex data structures. Recommended for advanced
207 * coders only.
208 *
209 * @return CyData Object.
210 */
211 public CyData getCyData();
212
213 /**
214 * Gets the CyDataDefinition Object, which stores attribute definitions.
215 * <P>By using CyData and CyDataDefintion directly, you can store
216 * arbitrarily complex data structures. Recommended for advanced
217 * coders only.
218 *
219 * @return CyDataDefintion Object.
220 */
221 public CyDataDefinition getCyDataDefinition();
222 }
223