1 /*******************************************************************************
2 * Copyright (c) 2007, 2010 Association for Decentralized Information Management
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
10 * VTT Technical Research Centre of Finland - initial API and implementation
11 *******************************************************************************/
12 package org.simantics.browsing.ui.common;
14 import java.util.Collection;
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;
29 * An interface for retrieving a collection of {@link Evaluator}s based on any
30 * input object ({@link #get(Object)}.
33 * {@link EvaluatorDataImpl} is the default class-based concrete implementation of
34 * this interface that clients can and should use.
38 * @see EvaluatorDataImpl
40 public interface EvaluatorData {
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.
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.
55 * NOTE: this mechanism is not in use yet.
58 public interface Transformer {
59 Object transform(Object source);
63 * An evaluator describes available ways of
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>
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.
81 public interface Evaluator {
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();
92 * A convenience method for building an evaluator by adding viewpoint to
93 * the ViewpointFactory EvaluatorTree root. Maybe should not be in the
96 * @param factory the factory to add
98 * @return this evaluator to allow chained initialization
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);
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.
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.
123 * Should not be created directly. Use
124 * <code>Evaluator.add*Branch(Tester)</code> to create new evaluation tree
127 * @param <Factory> one of factories listed as "see also"
129 * @see ViewpointFactory
130 * @see ComparatorFactory
131 * @see LabelerFactory
132 * @see LabelDecoratorFactory
134 public interface EvaluatorTree<Factory> {
137 * @return a tester to indicate whether the factories in this tree node
138 * should be added to the factory evaluation result.
145 * @return this {@link EvaluatorTree} instance for chained initialization
147 EvaluatorTree<Factory> addFactory(Factory factory, double preference);
151 * @return the new {@link EvaluatorTree} branch created as a child of
152 * this {@link EvaluatorTree}
154 EvaluatorTree<Factory> addBranch(Tester tester);
157 * @return preference-wrapped factories accepted by this EvaluatorTree node
159 Collection<Preference<Factory>> getAcceptedFactories();
162 * @return preference-wrapped child tree nodes of this EvaluatorTree node
164 Collection<EvaluatorTree<Factory>> getChildren();
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.
173 * @return new {@link Evaluator} instance
175 Evaluator newEvaluator();
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>.
185 void addEvaluator(Class<?> clazz, Evaluator eval);
188 * Attempts to get a collection of possible <code>Evaluator</code> instances
189 * for the specified input object.
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.
197 * @param input any object that represents the input for producing some
199 * @return an empty collection if no <code>Evaluator</code> could be found
200 * to take care of the specified kind of input
202 Collection<Evaluator> get(Object input);
205 * An evaluator entry descriptor returned by
206 * {@link EvaluatorData#enumEvaluators()}.
208 public static interface EvaluatorEntry {
209 public Class<?> getClazz();
210 public Collection<Evaluator> getEvaluators();
214 * Enumerates all the evaluators added by the client using
215 * {@link #addEvaluator(Class, Evaluator)}.
217 Collection<EvaluatorEntry> enumEvaluators();
218 <T> T getBrowseContext();