Diff for "Outdated_Cytoscape_3.0/TunableDiscussion"

Tunables 2.0 Discussion

A Tunable is simply a value used in a class that can be modified by another class. The difference is that Tunables can be discovered dynamically and set using a generated user interface without any other information from, or knowledge about, the initial object. The goal is for a user interface to query an object about it's tunables, generate a user interface, and return modified values to the original object.

Use Cases

• Tunables were originally developed for Layout Algorithms that have a wide array of possible parameters that need to be defined for particular instances of algorithms that most likely don't have any applicability in other layout algorithms. For instance a force-directed algorithm might need to specify a spring-strength and repulsion force, which a hierarchical layout wouldn't have any need for. Likewise a hierarchical layout might need to know the distance between layers which would be meaningless for a force-directed layout. Since these parameters are different from implementation to implementation, they can't be captured in an interface and thus become good candidates from becoming Tunables.
• Similar to Layouts, Web Services have parameters that differ from service to service. Tunables are used here too.

Tunables 1.0

In Cytoscape 2.6, tunables are defined in a [http://chianti.ucsd.edu/svn/cytoscape/trunk/src/cytoscape/layout/Tunable.java Tunable] class that specifies the type of the Tunable. The class using the Tunable objects then also requires a [http://chianti.ucsd.edu/svn/cytoscape/trunk/src/cytoscape/util/ModuleProperties.java ModuleProperties] class to manage access to the various Tunable objects. Once a Tunable has been set the class using the Tunable just calls the getValue() method to access the value contained in the Tunable.

Motivations for Tunables 2.0

• Tunable is a class rather than interface.
• Tunables contain both model (the value) and presentation (JPanel - GUI specific) information limiting the applicability of the concept for other user interfaces (e.g. command line).
• When stripped of presentation information Tunables really just represent a single field used within a class.

• Using Tunables within a class requires a fair amount of code to be implemented (getSettings(),getSettingsPanel(),updateSettings(),revertSettings()).

Tunables 2.0 Design Idea

The first design motivation was to completely remove the GUI generation code from Tunables itself. This should properly be stored in the code that generates the dialog, menu option, or whatever other mechanism is used to set the Tunable. The Tunable itself shouldn't care how it gets set or presented to the user.

With the GUI code stripped from the Tunable, it really becomes little more than a container for an object. When this happens, all that ModuleProperties becomes responsible for is tracking these containers, passing them to GUI (or other ui), and applying the new values to the object using the Tunables.

The inspiration for this approach comes from how parameters to Maven Mojos are set. Mojos rely on a Javadoc tag @parameter that declares a field to be a parameter to the Mojo. Maven pom files automatically translate any <configuration> into parameters. If a parameter is found in the Mojo, the value is set. This makes it very simple for a Mojo author to make a parameter accessible from a pom. All they need to do is apply the @parameter tag in the Javadoc of the declared field.

Using Javadoc for this sort of identification is the motivation for annotations in Java 1.5 and later.

The idea for Tunables 2.0 is to use a @Tunable annotation to identify fields in objects that can be modified instead of using a separate Tunable object. The user interface that cares about tunables then reflects on the object and finds any fields annotated with the @Tunable annotation. It then uses the Fields it finds to generate a user interface which allows these values to be set and applies the new values to the original object.

Here an an implementation of this approach: [http://chianti.ucsd.edu/svn/csplugins/trunk/ucsd/mes/anntun/]. This code provides two different user interfaces for setting Tunable parameters: a command line interface and a GUI.

• Compile the code with: mvn clean package

• Run the code using:  java -jar target/anntun-1.0-SNAPSHOT-jar-with-dependencies.jar and you should see a name printed to stdout.

• To see the command line user interface run:  java -jar target/anntun-1.0-SNAPSHOT-jar-with-dependencies.jar -h

• To see the graphical user interface change the mainClass parameter on approximately line 53 of the pom.xml and recompile and run the same way. The results will be still be printed to stdout.

• Run mvn site to generate javadocs and whatnot.

Benefits

• The primary benefit of this approach is that it is dead simple for the tunable user. All you need to do is declare a field to be tunable and everything else follows automatically:

   1 import org.example.tunable.Tunable;
   2 
   3 public class SpringLayout implements Layout {
   4 
   5         @Tunable(description="spring length")   // no other tunable code needed!
   6         private int springLength = 10;  // initialize to the default value
   7 
   8         public void doLayout() {
   9                 // complicated algorithm that uses springLength, etc.
  10         }
  11 }
  12 

• Allowable types are only limited by the handlers that get written.
• Model and view are separate.

Sample Implementation based on comments below:

   1 @Retention(RetentionPolicy.RUNTIME)
   2 @Target(ElementType.FIELD)
   3 public @interface Tunable {
   4         // Description of the field.  Required.
   5         String description();
   6         
   7         // Will be used by Command object.  If set to true, cannot accept null.
   8         boolean required() default false;
   9         
  10         // Editable from UI or not.  UI includes command line and GUI.
  11         boolean immutable() default false;
  12         
  13         // Will be used for numerical fields.
  14         double upperBound() default 0;
  15         double lowerBound() default 0;
  16 }
  17 

   1 public interface TunableInterceptor {
   2 
   3         // Modify the fields in the object based on the annotation.
   4         public void intercept();
   5 
   6         // Get all tunable parameters
   7         public Map<String, Object> getTunables();
   8         
   9         // Use reflection to get all tunable parameters
  10         public Collection<String> getTunableNames();
  11         
  12         // Return true if the field exists and is a Tunable.
  13         public boolean isTunable(String fieldName);
  14         
  15         // For persistence
  16         public void save(TunableDAO dao);
  17         public void load(TunableDAO dao);
  18 }
  19 

   1 public abstract class AbstractTunableIntercepter implements TunableInterceptor {
   2         
   3         public AbstractTunableIntercepter(Object targetObject, Map<String, Object> tunableValues) {
   4                 // Set tunables of targetObject based on the Map.
   5         }
   6 
   7         // Implementation of methods starts here.
   8 }
   9 

   1 public interface TunableDAO {
   2         /**
   3          *  Write all of Tunable fields into file/DB/properties.
   4          */
   5         public void saveTunables();
   6 
   7         /**
   8          *  Restore tunable states of target object from the data source.
   9          */
  10         public void loadTunables();
  11 }
  12 

   1 // If a class is annotated by this, it will be used by Handler factory.
   2 // This makes handler extensible by plugin writers.
   3 @Retention(RetentionPolicy.RUNTIME)
   4 @Target(ElementType.TYPE)
   5 public @interface TunableHandler {}
   6 

• The TunableIntercepter interface is a bit busy in this version, but this solves most of the issues Scooter mentioned in the comment.

• Acceptable data type is not pre-defined. All kinds of complex data types can be a tunable in this version, although custom tunable handler should be implemented.

Concerns

The issue with this approach relates to access to Fields within classes. If the fields are private, as all good Java design protocol generally demands, then reflection on objects to set the fields from the UI break the Java access restrictions. This can be overcome, but this means that private fields are being accessed from outside of the class. Is this a signficant concern? This is easily avoided if the fields are public, however good java design usually demands that fields be as private as possible. Maybe this isn't much of an issue since all tunable users in this case (i.e. layout implementations or web service implementations) will be implementing interfaces, meaning these public fields won't accessible or visible from the interface. This is, of course, security through obscurity, but perhaps that is a reasonable trade-off. Another approach to provide normal getter and setter methods to access the fields (like a normal java bean) and then instead of reflecting a single @Tunable annotation on fields, reflect on the @TunableSetter and @TunableGetter annotated methods and infer the type of the tunable value being set from the arguments and return values of the methods. This would be more complicated for the UI generator and the object using the tunable would require more code, but this would perhaps be the most Java appropriate design.

ScooterMorris: There are some functions of the current Tunable mechanism that aren't covered by this design. First, in addition to handling the UI, Tunables also take care of dealing with persistence by storing and retrieving values into Cytoscape properties -- this is an important aspect of the current design. Second, while I can certainly see the benefits of the proposed implementation for base types, how would you handle the GROUP, BUTTON, LIST, NODEATTRIBUTE, and EDGEATTRIBUTE Tunables? Also, it will be important to be able to pass various values to the presentation layer to support bounds, UI hints, and possible callbacks. Some of this could certainly be handled by the proposed framework, but I think things like LIST, for example, would be very difficult.