Differences between revisions 42 and 51 (spanning 9 versions)
← Revision 42 as of 2005-09-30 20:57:32 →
Size: 10677
Editor: pix39
Comment:
← Revision 51 as of 2005-10-04 20:05:13 →
Size: 3336
Editor: mskresolve-b
Comment:
Deletions are marked like this. Additions are marked like this.
Line 3: Line 3:
=== Cytoscape RFC #1: Replacing Graph Obj Attributes === [[TableOfContents([2])]]

=== About this Document ===
Line 7: Line 9:
'''Status:''' 9/30/2005, Version 0.1 of the proposal is below. This represents Ethan's first stab at creating a new API. === Status ===
Line 9: Line 11:
'''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"]. 10/4/2005, Version 0.2 of the proposal is below. This represents a beta version of the API, with input from: Nerius, Iliana, Rowan, Gary and Ethan.

=== 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"].
Line 13: Line 19:
'''General Notes:''' === General Notes:  ===
Line 15: Line 21:
  * 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"] The following represents Version 0.2 notes, as agreed by Nerius, Iliana and Ethan:
Line 17: Line 23:
  * 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"]   * The new interface is now called {{{CyAttributes}}}. ["/RFC1 Comment Name"]
 
  * {{{CyData}}} is now called {{{MultiHashMap}}}. We wanted to give it a name that reflected its role as a core data structure. ["/RFC1 Comment CyData Name"]
Line 19: Line 27:
  * {{{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"]   * {{{CyAttributes}}} uses a {{{MultiHashMap}}} as a back-end data store, but does not extend {{{MultiHashMap}}}.
Line 21: Line 29:
  * {{{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"]   * {{{CyAttributes}}} provides several overloaded versions of {{{setAttribute}}}, one for each basic data type, e.g. {{{setAttribute(String id, String attributeName, double value)}}}. It also provides several varients of getAttribute, e.g. {{{Double getDoubleAttribute(String id, String attributeName)}}}. ["/RFC1 Comment Getters Setters"]
Line 23: Line 31:
  * 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"]   * {{{CyAttributes}}} provides support for 'simple' lists. A 'simple' list is defined as follows:
     * All items within the list are of the same type, and are chosen from one of the following: Boolean, Integer, Double or String. ["/RFC1 Comment Lists"]
Line 25: Line 34:
  * Item not yet covered: Event / Listener Framework ["/RFC1 Comment Event Framework"]   * {{{CyAttributes}}} provides support for 'simple' maps. A 'simple' map is defined as follows:
    * All keys within the map are of type: String.
    * All values within the map are of the same type, and are chosen from one of the following: Boolean, Integer, Double or String. ["/RFC1 Comment Maps"]

  * To do complicated things, such as create arbitarily complex data structures, you can obtain the {{{MultiHashMap}}} and {{{MultiHashMapDataDefinition}}} from {{{CyAttributes}}}. ["/RFC1 Comment Complex Data Structures"]

  * Event / Listener Framework: Coders who wish to register for attribute events can use the existing listener API provided by {{{MultiHashMap}}}. ["/RFC1 Comment Event Framework"]
Line 29: Line 44:
 ["/RFC1 Comment API"]   * Item not yet covered: recommended attribute names ["/RFC1 Comment Attribute Names"]

  * Misc items that didn't fit in any existing category: ["/RFC1 Comment API"]
Line 33: Line 50:
{{{#!java
package cytoscape.data;

import cytoscape.data.attr.CyData;
import cytoscape.data.attr.CyDataDefinition;

import java.util.List;
import java.util.Map;

/**
 * Proposed API for AttributeData Interface.
 *
 * [Lots of descriptive comments here...]
 */
public interface AttributeData {

    /**
     * Gets a List of All Attribute Names.
     *
     * @return An Array of String Objects.
     */
    public String[] getAttributeNames();

    /**
     * Determines if the specified id/attributeName pair exists.
     *
     * @param id unique identifier.
     * @param attributeName attribute name.
     * @return true or false.
     */
    public boolean hasAttribute(String id, String attributeName);

    /**
     * Sets an id/attributeName pair of type boolean.
     *
     * @param id unique identifier.
     * @param attributeName attribute name.
     * @param value boolean value.
     */
    public void setAttribute(String id, String attributeName, boolean value);

    /**
     * Sets an id/attributeName pair of type integer.
     *
     * @param id unique identifier.
     * @param attributeName attribute name.
     * @param value integer value.
     */
    public void setAttribute(String id, String attributeName, int value);

    /**
     * Sets an id/attributeName pair of type double.
     *
     * @param id unique identifier.
     * @param attributeName attribute name.
     * @param value double value.
     */
    public void setAttribute(String id, String attributeName, double value);

    /**
     * Sets an id/attributeName pair of type String.
     *
     * @param id unique identifier.
     * @param attributeName attribute name.
     * @param value string value.
     */
    public void setAttribute(String id, String attributeName, String value);

    /**
     * Gets a boolean value at the specified id/attributeName.
     * <P>If attributeName refers to a List, the zeroeth element in
     * that list is returned.
     *
     * @param id unique identifier.
     * @param attributeName attribute name.
     * @return Boolean object, or null if no id/attributeName pair is found.
     * @throws ClassCastException Indicates that the specified attribute
     * is not of type Boolean.
     */
    public Boolean getBooleanAttribute(String id, String attributeName)
            throws ClassCastException;

    /**
     * Gets an integer value at the specified id/attributeName.
     * <P>If attributeName refers to a List, the zeroeth element in
     * that list is returned.
     *
     * @param id unique identifier.
     * @param attributeName attribute name.
     * @return Integer object, or null if no id/attributeName pair is found.
     * @throws ClassCastException Indicates that the specified attribute
     * is not of type Integer.
     */
    public Integer getIntegerAttribute(String id, String attributeName)
            throws ClassCastException;

    /**
     * Gets a double value at the specified id/attributeName.
     * <P>If attributeName refers to a List, the zeroeth element in
     * that list is returned.
     *
     * @param id unique identifier.
     * @param attributeName attribute name.
     * @return Double object, or null if no id/attributeName pair is found..
     * @throws ClassCastException Indicates that the specified attribute
     * is not of type Double.
     */
    public Double getDoubleAttribute(String id, String attributeName)
            throws ClassCastException;

    /**
     * Gets a String value at the specified id/attributeName.
     * <P>If attributeName refers to a List, the zeroeth element
     * in that list is returned.
     *
     * @param id unique identifier.
     * @param attributeName attribute name.
     * @return String object, or null if no id/attributeName pair is found.
     * @throws ClassCastException Indicates that the specified attribute
     * is not of type String.
     */
    public String getStringAttribute(String id, String attributeName)
            throws ClassCastException;

    /**
     * Gets the Class of the specified attribute.
     *
     * @param attributeName Attribute Name.
     * @return Return type will be of type: Boolean, Integer, Double,
     * String, List or Map. If attributeName has not been
     * defined, this method will return null.
     */
    public Class getClass(String attributeName);

    /**
     * Delete the id/attributeName pair.
     *
     * @param id unique identifier.
     * @param attributeName attribute name.
     * @return true indicates attribute was
     * successfully removed.
     */
    public boolean deleteAttribute(String id, String attributeName);

    /**
     * Sets a List of Attributes.
     * <P><B>Note:</B>
     * <UL>
     * <LI>All items within the list must be of the same type,
     * and and chosen from the following list: Boolean, Integer, Double,
     * or String.
     * </LI>
     * </UL>
     * If the above requirement is not met, an IllegalArgumentException
     * will be thrown.
     *
     * @param id unique identifier.
     * @param list attribute name.
     * @param list List Object.
     * @throws IllegalArgumentException List requirements have not been met.
     */
    public void setAttributeList(String id, String attributeName, List list)
            throws IllegalArgumentException;

    /**
     * Gets a List of attributes for the id/attributeName pair.
     *
     * @param id unique identifier.
     * @param attributeName attribute name.
     * @return List object.
     * @throws ClassCastException Indicates that the specified attribute
     * is not of type List.
     */
    public List getAttributeList(String id, String attributeName)
            throws ClassCastException;

    /**
     * Sets a Map of Attribute Values.
     * <P><B>Note:</B>
     * <UL>
     * <LI>All keys within the Map must be of type String.
     * <LI>All values within the Map must be of the same type,
     * and chosen from the following list: Boolean, Integer,
     * Double, or String.
     * </UL>
     * If the above requirements are not met, an IllegalArgumentException
     * will be thrown.
     *
     * @param id unique identifier.
     * @param attributeName attribute name.
     * @param map Map Object.
     * @throws IllegalArgumentException Map requirements have not been met.
     */
    public void setAttributeMap(String id, String attributeName,
            Map map);

    /**
     * Gets a Map of Attribute Value.
     *
     * @param id unique identifier.
     * @param attributeName attribute name.
     * @return Map Object.
     */
    public Map getAttributeMap(String id, String attributeName);

    /**
     * Gets the CyData Object, which stores the actual attribute values.
     * <P>By using CyData and CyDataDefintion directly, you can store
     * arbitrarily complex data structures. Recommended for advanced
     * coders only.
     *
     * @return CyData Object.
     */
    public CyData getCyData();

    /**
     * Gets the CyDataDefinition Object, which stores attribute definitions.
     * <P>By using CyData and CyDataDefintion directly, you can store
     * arbitrarily complex data structures. Recommended for advanced
     * coders only.
     *
     * @return CyDataDefintion Object.
     */
    public CyDataDefinition getCyDataDefinition();
}
}}} 		  * Version 0.2 of {{{CyAttributes}}} is now checked in CVS at: src/cytoscape/data/
  * [http://http://cbio.mskcc.org/~cerami/cyto/docs/cytoscape/data/CyAttributes.html View Proposed JavaDocs]

TableOfContents([2])

About this Document

This is an official Request for Comment (RFC) for replacing GraphObjAttributes.

Status

10/4/2005, Version 0.2 of the proposal is below. This represents a beta version of the API, with input from: Nerius, Iliana, Rowan, Gary and Ethan.

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"].

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.

General Notes:

The following represents Version 0.2 notes, as agreed by Nerius, Iliana and Ethan:

  • The new interface is now called CyAttributes. ["/RFC1 Comment Name"]

  • CyData is now called MultiHashMap. We wanted to give it a name that reflected its role as a core data structure. ["/RFC1 Comment CyData Name"]

  • CyAttributes uses a MultiHashMap as a back-end data store, but does not extend MultiHashMap.

  • CyAttributes provides several overloaded versions of setAttribute, one for each basic data type, e.g. setAttribute(String id, String attributeName, double value). It also provides several varients of getAttribute, e.g. Double getDoubleAttribute(String id, String attributeName). ["/RFC1 Comment Getters Setters"]

  • CyAttributes provides support for 'simple' lists. A 'simple' list is defined as follows:

    • All items within the list are of the same type, and are chosen from one of the following: Boolean, Integer, Double or String. ["/RFC1 Comment Lists"]

  • CyAttributes provides support for 'simple' maps. A 'simple' map is defined as follows:

    • All keys within the map are of type: String.
    • All values within the map are of the same type, and are chosen from one of the following: Boolean, Integer, Double or String. ["/RFC1 Comment Maps"]

  • To do complicated things, such as create arbitarily complex data structures, you can obtain the MultiHashMap and MultiHashMapDataDefinition from CyAttributes. ["/RFC1 Comment Complex Data Structures"]

  • Event / Listener Framework: Coders who wish to register for attribute events can use the existing listener API provided by MultiHashMap. ["/RFC1 Comment Event Framework"]

  • Item not yet covered: support for Labels (Rowan has this feature in the current implementation of CytoscapeData) ["/RFC1 Comment Labels"]

  • Item not yet covered: recommended attribute names ["/RFC1 Comment Attribute Names"]
  • Misc items that didn't fit in any existing category: ["/RFC1 Comment API"]

Proposed API: Version 0.1

RFC_1 (last edited 2009-02-12 01:04:12 by localhost)

Funding for Cytoscape is provided by a federal grant from the U.S. National Institute of General Medical Sciences (NIGMS) of the Na tional Institutes of Health (NIH) under award number GM070743-01. Corporate funding is provided through a contract from Unilever PLC.

MoinMoin Appliance - Powered by TurnKey Linux