attachment:EquationAPI.java of Cytoscape_2.8/EquationAttributes

   1 public interface CyAttributes {
   2 	// new method for CyAttributes
   3 	void setEquationAttribute(final String id, final String attributeName, final String eqn) throws IllegalArgumentException;
   4 
   5 	// All other get methods will be the same.  
   6 }
   7 
   8 
   9 /**
  10  * The implementation of an equation attribute that is defined by a
  11  * string, which in turn specifies various Functions that get evaluated
  12  * to produce the result of the Equation. 
  13  */
  14 public interface Equation {
  15 	byte getType();
  16 
  17 	/**
  18 	 * @param id The node/edge ID used to identify the row in CyAttributes.
  19 	 * @returns either the result of a successful equation evaluation or null if an error occurred.
  20 	 */
  21 	Object eval(final String id);
  22 }
  23 
  24 
  25 public interface BooleanEquation extends Equation {
  26 	@Override Boolean eval(final String id);
  27 }
  28 
  29 
  30 public interface StringEquation extends Equation {
  31 	@Override String eval(final String id);
  32 }
  33 
  34 
  35 public interface DoubleEquation extends Equation {
  36 	@Override Double eval(final String id);
  37 }
  38 
  39 
  40 /**
  41  * This is the low level, builtin function that performs a single 
  42  * operation on input values.
  43  */
  44 public interface Function {
  45 	/**
  46 	 * Used to parse the function string.
  47 	 * @returns the name by which you must call the function when used in an attribute equation.
  48 	 */
  49 	String getName();
  50 
  51 	/**
  52 	 * Used to parse the function parameters.
  53 	 * @returns the list of argument types for this function, like MultiHashMapDefinition.TYPE_FLOATING_POINT etc.
  54 	 */
  55 	byte[] getParameterTypes();
  56 
  57 	/**
  58 	 * Used to define the function's return type. 
  59 	 * @returns one of the MultiHashMapDefinition.* constants, e.g. TYPE_FLOATING_POINT.
  60 	 */
  61 	byte getReturnType();
  62 
  63 	/**
  64 	 * Used to provide help for users.
  65 	 * @returns a description of how to use this function for a casual user.
  66 	 */
  67 	String getHelpDescription();
  68 
  69 	/** Used to invoke this function.
  70 	 * @param args the function arguments which must correspond in type and number to what getParameterTypes() returns.
  71 	 * @returns the result of the function evaluation.  The actual type of the returned object will be what getReturnType() returns.
  72 	 * @throws ArithmeticException thrown if a numeric error, e.g. a division by zero occurred.
  73 	 * @thrown IllegalArgumentException thrown for any error that is not a numeric error, for example if a function only accepts positive
  74 	 * numbers and a negative number was passed in.
  75 	 */
  76 	Object evaluateFunction(Object args...) throws IllegalArgumentException, ArithmeticException;
  77 }
  78 
  79 
  80 public interface EquationFactory {
  81 	/** Cashes equations and returns one of a number of descendents of class Equation.
  82 	 *  @param eqn  The string representation of an attribute equation.
  83 	 *  @note May return the same object when given an identical equation string.
  84 	 */
  85 	Equation createEquation(final String eqn) throws IllegalArgumentException;
  86 
  87 	/** Installs a new function as a built-in for the attribute equations.
  88 	 *  @throws IllegalArgumentException Thrown if a function with same name has already been registered.
  89 	 */
  90 	void registerFunction(final Function f) throws IllegalArgumentException;
  91 }
  92 
  93 
  94 /**
  95  * Sample implementation for CyAttributes.
  96  */
  97 public void setEquationAttribute(final String id, final String attributeName, final String eqnString) {
  98 	// Sanity checks:
  99         if (id == null)
 100 		throw new IllegalArgumentException("id is null");
 101         if (attributeName == null)
 102 		throw new IllegalArgumentException("attributeName is null");
 103         if (eqnString == null)
 104 		throw new IllegalArgumentException("eqnString is null");
 105 
 106 	final Equation eqn = EquationFactory.createEquation(eqnString);
 107 
 108         final byte type = mmapDef.getAttributeValueType(attributeName);
 109         if (type < 0) {
 110 		mmapDef.defineAttribute(attributeName, eqn.getType(), null);
 111         } else {
 112 		if ( type != eqn.getType() ) 
 113 			throw new IllegalArgumentException("definition for attributeName '" + attributeName
 114 							   + "' already exists and it is not of type " + eqn.getType());
 115 		final byte[] dimTypes = mmapDef.getAttributeKeyspaceDimensionTypes(attributeName);
 116 
 117 		if (dimTypes.length != 0)
 118 			throw new IllegalArgumentException("definition for attributeName '" + attributeName
 119 							   + "' already exists and it is not of TYPE_INTEGER");
 120         }
 121 
 122         mmap.setAttributeValue(id, attributeName, eqn, null);
 123 }
 124 
 125 
 126 /**
 127  * Sample implementation of CyAttributes.getDoubleAttribute. This shows
 128  * how Equations are handled internally and how they get evaluated.
 129  */
 130 public Double getDoubleAttribute(final String id, final String attrName) {
 131         final byte type = mmapDef.getAttributeValueType(attributeName);
 132         if (type < 0) {
 133 		return null;
 134         }
 135 
 136         if (type == MultiHashMapDefinition.TYPE_FLOATING_POINT) {
 137         	return (Double) mmap.getAttributeValue(id, attributeName, null);
 138         } else if (type == MultiHashMapDefinition.TYPE_FLOATING_POINT_FUNCTION) {
 139         	DoubleFunction df = (DoubleFunction) mmap.getAttributeValue(id, attributeName, null);
 140 		return df.eval(id);
 141 	} else {
 142 		throw new ClassCastException("definition for attributeName '" + attributeName + "' is not of TYPE_FLOATING");
 143 	}
 144 }
 145