bundles/org.simantics.browsing.ui.common/src/org/simantics/browsing/ui/common/EvaluatorData.java

   1 /*******************************************************************************
   2  * Copyright (c) 2007, 2010 Association for Decentralized Information Management
   3  * in Industry THTH ry.
   4  * All rights reserved. This program and the accompanying materials
   5  * are made available under the terms of the Eclipse Public License v1.0
   6  * which accompanies this distribution, and is available at
   7  * http://www.eclipse.org/legal/epl-v10.html
   8  *
   9  * Contributors:
  10  *     VTT Technical Research Centre of Finland - initial API and implementation
  11  *******************************************************************************/
  12 package org.simantics.browsing.ui.common;
  13
  14 import java.util.Collection;
  15
  16 import org.simantics.browsing.ui.GraphExplorer;
  17 import org.simantics.browsing.ui.NodeContext;
  18 import org.simantics.browsing.ui.Tester;
  19 import org.simantics.browsing.ui.content.CheckedStateFactory;
  20 import org.simantics.browsing.ui.content.ComparableContextFactory;
  21 import org.simantics.browsing.ui.content.ImageDecoratorFactory;
  22 import org.simantics.browsing.ui.content.ImagerFactory;
  23 import org.simantics.browsing.ui.content.LabelDecoratorFactory;
  24 import org.simantics.browsing.ui.content.LabelerFactory;
  25 import org.simantics.browsing.ui.content.ViewpointFactory;
  26 import org.simantics.utils.datastructures.ComparatorFactory;
  27
  28 /**
  29  * An interface for retrieving a collection of {@link Evaluator}s based on any
  30  * input object ({@link #get(Object)}.
  31  *
  32  * <p>
  33  * {@link EvaluatorDataImpl} is the default class-based concrete implementation of
  34  * this interface that clients can and should use.
  35  * </p>
  36  *
  37  * @see Evaluator
  38  * @see EvaluatorDataImpl
  39  */
  40 public interface EvaluatorData {
  41
  42     /**
  43      * A transformer from one input object to another. The idea is that before
  44      * resolving an Evaluator for an input object, all possible input
  45      * transformations have been executed.
  46      *
  47      * <p>
  48      * Consider classes A and B which have are of a separate inheritance
  49      * hierarchy and share no common interfaces. In principle, this mechanism
  50      * should allow clients to define evaluators for class B, define a
  51      * transformer from class A to B and give input objects of class A, and
  52      * evaluator for class B would get resolved for these inputs.
  53      * </p>
  54      *
  55      * NOTE: this mechanism is not in use yet.
  56      *
  57      */
  58     public interface Transformer {
  59         Object transform(Object source);
  60     }
  61
  62     /**
  63      * An evaluator describes available ways of
  64      * <ul>
  65      * <li>producing content for a {@link GraphExplorer}, i.e. detemining the
  66      * children of a {@link NodeContext} (see {@link ViewpointFactory})</li>
  67      * <li>sorting the produced child content for a {@link NodeContext} (see
  68      * {@link ComparableContextFactory})</li>
  69      * <li>producing labels for the produced {@link NodeContext}s (see
  70      * {@link LabelerFactory})</li>
  71      * <li>decorating labels produced for {@link NodeContext}s (see
  72      * {@link LabelDecoratorFactory})</li>
  73      * </ul>
  74      *
  75      * An evaluator may produce several alternatives for each of the above
  76      * tasks, sorted by preference numbers bound to the factories. Picking the
  77      * factory to use is not the task of the evaluator.
  78      *
  79      * @see EvaluatorImpl
  80      */
  81     public interface Evaluator {
  82
  83         EvaluatorTree<ComparableContextFactory> getComparableContextTree();
  84         EvaluatorTree<ImagerFactory> getImagerTree();
  85         EvaluatorTree<ImageDecoratorFactory> getImageDecoratorTree();
  86         EvaluatorTree<LabelDecoratorFactory> getLabelDecoratorTree();
  87         EvaluatorTree<LabelerFactory> getLabelerTree();
  88         EvaluatorTree<CheckedStateFactory> getCheckStateTree();
  89         EvaluatorTree<ViewpointFactory> getViewpointTree();
  90
  91         /**
  92          * A convenience method for building an evaluator by adding viewpoint to
  93          * the ViewpointFactory EvaluatorTree root. Maybe should not be in the
  94          * interface.
  95          *
  96          * @param factory the factory to add
  97          * @param preference
  98          * @return this evaluator to allow chained initialization
  99          */
 100         Evaluator addViewpoint(ViewpointFactory factory, double preference);
 101         Evaluator addComparableContext(ComparableContextFactory factory, double preference);
 102         Evaluator addLabeler(LabelerFactory factory, double preference);
 103         Evaluator addCheckState(CheckedStateFactory factory, double preference);
 104         Evaluator addLabelDecorator(LabelDecoratorFactory factory, double preference);
 105         Evaluator addComparator(ComparableContextFactory factory, double preference);
 106         Evaluator addImager(ImagerFactory factory, double preference);
 107         Evaluator addImageDecorator(ImageDecoratorFactory factory, double preference);
 108
 109     };
 110
 111     /**
 112      * A node in a tree of factories. Each node is associated with a
 113      * {@link Tester} that determines whether the factories associated with this
 114      * node should be included in the available factory evaluation result of the
 115      * specified {@link NodeContext} input.
 116      *
 117      * <p>
 118      * The factory tree structure allows optimization of factory resolution when
 119      * there are lots of factories available. By grouping factories under tree
 120      * nodes with a suitable tester allows more efficient result calculation.
 121      *
 122      * <p>
 123      * Should not be created directly. Use
 124      * <code>Evaluator.add*Branch(Tester)</code> to create new evaluation tree
 125      * branches.
 126      *
 127      * @param <Factory> one of factories listed as "see also"
 128      *
 129      * @see ViewpointFactory
 130      * @see ComparatorFactory
 131      * @see LabelerFactory
 132      * @see LabelDecoratorFactory
 133      */
 134     public interface EvaluatorTree<Factory> {
 135
 136         /**
 137          * @return a tester to indicate whether the factories in this tree node
 138          *         should be added to the factory evaluation result.
 139          */
 140         Tester getTester();
 141
 142         /**
 143          * @param factory
 144          * @param preference
 145          * @return this {@link EvaluatorTree} instance for chained initialization
 146          */
 147         EvaluatorTree<Factory> addFactory(Factory factory, double preference);
 148
 149         /**
 150          * @param tester
 151          * @return the new {@link EvaluatorTree} branch created as a child of
 152          *         this {@link EvaluatorTree}
 153          */
 154         EvaluatorTree<Factory> addBranch(Tester tester);
 155
 156         /**
 157          * @return preference-wrapped factories accepted by this EvaluatorTree node
 158          */
 159         Collection<Preference<Factory>> getAcceptedFactories();
 160
 161         /**
 162          * @return preference-wrapped child tree nodes of this EvaluatorTree node
 163          */
 164         Collection<EvaluatorTree<Factory>> getChildren();
 165
 166     }
 167
 168     /**
 169      * Creates a new Evaluator that is completely separate from this
 170      * {@link EvaluatorData}. {@link #addEvaluator(Class, Evaluator)} can later
 171      * be used to bind the evaluator to any number of EvaluatorData instances.
 172      *
 173      * @return new {@link Evaluator} instance
 174      */
 175     Evaluator newEvaluator();
 176
 177     /**
 178      * Bind the specified evaluator to the specified class. After this results
 179      * of {@link #get(Object)} should include <code>eval</code> for any input
 180      * object that is an instance of <code>clazz</code>.
 181      *
 182      * @param clazz
 183      * @param eval
 184      */
 185     void addEvaluator(Class<?> clazz, Evaluator eval);
 186
 187     /**
 188      * Attempts to get a collection of possible <code>Evaluator</code> instances
 189      * for the specified input object.
 190      *
 191      * <p>
 192      * The resolution of "possible evaluators" can be based on, e.g. Class
 193      * comparison, <code>instanceof</code> queries or adaptation through
 194      * Eclipse's <code>IAdaptable</code> interface.
 195      * </p>
 196      *
 197      * @param input any object that represents the input for producing some
 198      *        output.
 199      * @return an empty collection if no <code>Evaluator</code> could be found
 200      *         to take care of the specified kind of input
 201      */
 202     Collection<Evaluator> get(Object input);
 203
 204     /**
 205      * An evaluator entry descriptor returned by
 206      * {@link EvaluatorData#enumEvaluators()}.
 207      */
 208     public static interface EvaluatorEntry {
 209         public Class<?> getClazz();
 210         public Collection<Evaluator> getEvaluators();
 211     };
 212
 213     /**
 214      * Enumerates all the evaluators added by the client using
 215      * {@link #addEvaluator(Class, Evaluator)}.
 216      */
 217     Collection<EvaluatorEntry> enumEvaluators();
 218     <T> T getBrowseContext();
 219
 220 }