001    package jigcell.compare;
002    
003    import java.awt.datatransfer.Transferable;
004    
005    /**
006     * A generic transfer agent for a source of data.  Data source options can safely be set on the event thread.  Users of a data source should
007     * treat all objects acquired by getOption or passed to setOption as immutable.
008     *
009     * <p>
010     * This code is licensed under the DARPA BioCOMP Open Source License.  See LICENSE for more details.
011     * </p>
012     *
013     * @author Nicholas Allen
014     */
015    
016    public interface IDataSource extends Cloneable, Transferable {
017    
018       /**
019        * Option indicating the name of this generator
020        */
021    
022       String OPTION_NAME = "IDataSource.name";
023    
024       /**
025        * An enumeration of possible persistence types for an option.
026        */
027    
028       final class Option {
029    
030          /**
031           * Indicates that an option should be copied and persisted with the data source.  The value of an option marked safe must be a String.
032           */
033    
034          public final static Option SAFE = new Option ("safe");
035    
036          /**
037           * Indicates that an option should be copied but not persisted with the data source
038           */
039    
040          public final static Option COPYONLY = new Option ("copyonly");
041    
042          /**
043           * Indicates that an option should neither be copied nor persisted with the data source
044           */
045    
046          public final static Option UNSAFE = new Option ("unsafe");
047    
048          /**
049           * Type of option
050           */
051    
052          private final String type;
053    
054          /**
055           * Not allowed
056           */
057    
058          private Option () {
059             throw new UnsupportedOperationException ();
060          }
061    
062          /**
063           * Create a new type of option.
064           *
065           * @param type Option type
066           */
067    
068          private Option (String type) {
069             this.type = type;
070          }
071    
072          public String toString () {
073             return type;
074          }
075       }
076    
077       /**
078        * Adds a new configuration option.  The name of the option should be globally unique.  A Comparator convention is to prefix the option name
079        * with the name of the class it is defined in.  An option may safely be added multiple times but the type must be the same each time.
080        *
081        * @param key Option name
082        * @param type Option type
083        */
084    
085       void addOption (String key, Option type);
086    
087       /**
088        * A copy of this data source.  This method will return null instead of throwing an exception on failure.
089        */
090    
091       Object clone ();
092    
093       /**
094        * Does whatever configuration this data source requires and returns whether the configuration was completed successfully.
095        */
096    
097       boolean configure ();
098    
099       /**
100        * The name of this data source.
101        */
102    
103       String getName ();
104    
105       /**
106        * A configuration option.
107        *
108        * @param key Option name
109        */
110    
111       Object getOption (String key);
112    
113       /**
114        * A textual representation of the configuration of this data source or null if the configuration of this generator cannot be represented.
115        */
116    
117       String getState ();
118    
119       /**
120        * Sets a configuration optoin.  Returns whether the configuration was changed.
121        *
122        * @param key Option name
123        * @param value Option value
124        */
125    
126       boolean setOption (String key, Object value);
127    
128       /**
129        * Completely replaces the previous configuration of this data source.
130        *
131        * @param state State
132        */
133    
134       void setState (String state);
135    }