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