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

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