--- /dev/null
+/*******************************************************************************\r
+ * Copyright (c) 2007, 2010 Association for Decentralized Information Management\r
+ * in Industry THTH ry.\r
+ * All rights reserved. This program and the accompanying materials\r
+ * are made available under the terms of the Eclipse Public License v1.0\r
+ * which accompanies this distribution, and is available at\r
+ * http://www.eclipse.org/legal/epl-v10.html\r
+ *\r
+ * Contributors:\r
+ * VTT Technical Research Centre of Finland - initial API and implementation\r
+ *******************************************************************************/\r
+package org.simantics.browsing.ui.common;\r
+\r
+import java.util.Collection;\r
+\r
+import org.simantics.browsing.ui.GraphExplorer;\r
+import org.simantics.browsing.ui.NodeContext;\r
+import org.simantics.browsing.ui.Tester;\r
+import org.simantics.browsing.ui.content.CheckedStateFactory;\r
+import org.simantics.browsing.ui.content.ComparableContextFactory;\r
+import org.simantics.browsing.ui.content.ImageDecoratorFactory;\r
+import org.simantics.browsing.ui.content.ImagerFactory;\r
+import org.simantics.browsing.ui.content.LabelDecoratorFactory;\r
+import org.simantics.browsing.ui.content.LabelerFactory;\r
+import org.simantics.browsing.ui.content.ViewpointFactory;\r
+import org.simantics.utils.datastructures.ComparatorFactory;\r
+\r
+/**\r
+ * An interface for retrieving a collection of {@link Evaluator}s based on any\r
+ * input object ({@link #get(Object)}.\r
+ * \r
+ * <p>\r
+ * {@link EvaluatorDataImpl} is the default class-based concrete implementation of\r
+ * this interface that clients can and should use.\r
+ * </p>\r
+ * \r
+ * @see Evaluator\r
+ * @see EvaluatorDataImpl\r
+ */\r
+public interface EvaluatorData {\r
+\r
+ /**\r
+ * A transformer from one input object to another. The idea is that before\r
+ * resolving an Evaluator for an input object, all possible input\r
+ * transformations have been executed.\r
+ * \r
+ * <p>\r
+ * Consider classes A and B which have are of a separate inheritance\r
+ * hierarchy and share no common interfaces. In principle, this mechanism\r
+ * should allow clients to define evaluators for class B, define a\r
+ * transformer from class A to B and give input objects of class A, and\r
+ * evaluator for class B would get resolved for these inputs.\r
+ * </p>\r
+ * \r
+ * NOTE: this mechanism is not in use yet.\r
+ * \r
+ */\r
+ public interface Transformer {\r
+ Object transform(Object source);\r
+ }\r
+\r
+ /**\r
+ * An evaluator describes available ways of\r
+ * <ul>\r
+ * <li>producing content for a {@link GraphExplorer}, i.e. detemining the\r
+ * children of a {@link NodeContext} (see {@link ViewpointFactory})</li>\r
+ * <li>sorting the produced child content for a {@link NodeContext} (see\r
+ * {@link ComparableContextFactory})</li>\r
+ * <li>producing labels for the produced {@link NodeContext}s (see\r
+ * {@link LabelerFactory})</li>\r
+ * <li>decorating labels produced for {@link NodeContext}s (see\r
+ * {@link LabelDecoratorFactory})</li>\r
+ * </ul>\r
+ * \r
+ * An evaluator may produce several alternatives for each of the above\r
+ * tasks, sorted by preference numbers bound to the factories. Picking the\r
+ * factory to use is not the task of the evaluator.\r
+ * \r
+ * @see EvaluatorImpl\r
+ */\r
+ public interface Evaluator {\r
+\r
+ EvaluatorTree<ComparableContextFactory> getComparableContextTree();\r
+ EvaluatorTree<ImagerFactory> getImagerTree();\r
+ EvaluatorTree<ImageDecoratorFactory> getImageDecoratorTree();\r
+ EvaluatorTree<LabelDecoratorFactory> getLabelDecoratorTree();\r
+ EvaluatorTree<LabelerFactory> getLabelerTree();\r
+ EvaluatorTree<CheckedStateFactory> getCheckStateTree();\r
+ EvaluatorTree<ViewpointFactory> getViewpointTree();\r
+\r
+ /**\r
+ * A convenience method for building an evaluator by adding viewpoint to\r
+ * the ViewpointFactory EvaluatorTree root. Maybe should not be in the\r
+ * interface.\r
+ * \r
+ * @param factory the factory to add\r
+ * @param preference\r
+ * @return this evaluator to allow chained initialization\r
+ */\r
+ Evaluator addViewpoint(ViewpointFactory factory, double preference);\r
+ Evaluator addComparableContext(ComparableContextFactory factory, double preference);\r
+ Evaluator addLabeler(LabelerFactory factory, double preference);\r
+ Evaluator addCheckState(CheckedStateFactory factory, double preference);\r
+ Evaluator addLabelDecorator(LabelDecoratorFactory factory, double preference);\r
+ Evaluator addComparator(ComparableContextFactory factory, double preference);\r
+ Evaluator addImager(ImagerFactory factory, double preference);\r
+ Evaluator addImageDecorator(ImageDecoratorFactory factory, double preference);\r
+\r
+ };\r
+\r
+ /**\r
+ * A node in a tree of factories. Each node is associated with a\r
+ * {@link Tester} that determines whether the factories associated with this\r
+ * node should be included in the available factory evaluation result of the\r
+ * specified {@link NodeContext} input.\r
+ * \r
+ * <p>\r
+ * The factory tree structure allows optimization of factory resolution when\r
+ * there are lots of factories available. By grouping factories under tree\r
+ * nodes with a suitable tester allows more efficient result calculation.\r
+ * \r
+ * <p>\r
+ * Should not be created directly. Use\r
+ * <code>Evaluator.add*Branch(Tester)</code> to create new evaluation tree\r
+ * branches.\r
+ * \r
+ * @param <Factory> one of factories listed as "see also"\r
+ * \r
+ * @see ViewpointFactory\r
+ * @see ComparatorFactory\r
+ * @see LabelerFactory\r
+ * @see LabelDecoratorFactory\r
+ */\r
+ public interface EvaluatorTree<Factory> {\r
+\r
+ /**\r
+ * @return a tester to indicate whether the factories in this tree node\r
+ * should be added to the factory evaluation result.\r
+ */\r
+ Tester getTester();\r
+\r
+ /**\r
+ * @param factory\r
+ * @param preference\r
+ * @return this {@link EvaluatorTree} instance for chained initialization\r
+ */\r
+ EvaluatorTree<Factory> addFactory(Factory factory, double preference);\r
+\r
+ /**\r
+ * @param tester\r
+ * @return the new {@link EvaluatorTree} branch created as a child of\r
+ * this {@link EvaluatorTree}\r
+ */\r
+ EvaluatorTree<Factory> addBranch(Tester tester);\r
+\r
+ /**\r
+ * @return preference-wrapped factories accepted by this EvaluatorTree node\r
+ */\r
+ Collection<Preference<Factory>> getAcceptedFactories();\r
+\r
+ /**\r
+ * @return preference-wrapped child tree nodes of this EvaluatorTree node\r
+ */\r
+ Collection<EvaluatorTree<Factory>> getChildren();\r
+\r
+ }\r
+\r
+ /**\r
+ * Creates a new Evaluator that is completely separate from this\r
+ * {@link EvaluatorData}. {@link #addEvaluator(Class, Evaluator)} can later\r
+ * be used to bind the evaluator to any number of EvaluatorData instances.\r
+ * \r
+ * @return new {@link Evaluator} instance\r
+ */\r
+ Evaluator newEvaluator();\r
+\r
+ /**\r
+ * Bind the specified evaluator to the specified class. After this results\r
+ * of {@link #get(Object)} should include <code>eval</code> for any input\r
+ * object that is an instance of <code>clazz</code>.\r
+ * \r
+ * @param clazz\r
+ * @param eval\r
+ */\r
+ void addEvaluator(Class<?> clazz, Evaluator eval);\r
+\r
+ /**\r
+ * Attempts to get a collection of possible <code>Evaluator</code> instances\r
+ * for the specified input object.\r
+ * \r
+ * <p>\r
+ * The resolution of "possible evaluators" can be based on, e.g. Class\r
+ * comparison, <code>instanceof</code> queries or adaptation through\r
+ * Eclipse's <code>IAdaptable</code> interface.\r
+ * </p>\r
+ * \r
+ * @param input any object that represents the input for producing some\r
+ * output.\r
+ * @return an empty collection if no <code>Evaluator</code> could be found\r
+ * to take care of the specified kind of input\r
+ */\r
+ Collection<Evaluator> get(Object input);\r
+\r
+ /**\r
+ * An evaluator entry descriptor returned by\r
+ * {@link EvaluatorData#enumEvaluators()}.\r
+ */\r
+ public static interface EvaluatorEntry {\r
+ public Class<?> getClazz();\r
+ public Collection<Evaluator> getEvaluators();\r
+ };\r
+\r
+ /**\r
+ * Enumerates all the evaluators added by the client using\r
+ * {@link #addEvaluator(Class, Evaluator)}.\r
+ */\r
+ Collection<EvaluatorEntry> enumEvaluators();\r
+ <T> T getBrowseContext();\r
+\r
+}\r
Code Review / simantics / platform.git / blobdiff