    001package com.hammurapi.extract;
    002
    003import java.util.Map;
    004import java.util.Set;
    005
    006/**
    007 * Extractors extract values from objects.
    008 * Extractors are used to reduce number of calcluations performed on
    009 * objects through caching of extracted values.
    010 * Extractors shall implement equals() and hashCode(). Two extractors
    011 * which extract the same value from the same objects shall be equal.
    012 * @author Pavel Vlasov.
    013 *
    014 * @param <T> Object type.
    015 * @param <V> Value type.
    016 * @param <C> Context type.
    017 */
    018public interface Extractor<T, V, C> {
    019
    020        /**
    021         * Extracts value.
    022         * @param context Extraction context. Extraction context may provide source for constants for comparison
    023         * with object values.
    024         * @param cache Cache of values extracted from the source object for the given context.
    025         * Composite extractors can use cache to find already extracted values and to store extracted values.
    026         * For example extractor which extracts object area as obj.getWidth()*obj.getHeight() may find that width was already
    027         * extracted and getWidth() doesn't have to be invoked. So it invokes getHeight() and stores
    028         * returned value to the cache. It also calculates object area and stores it to the cache. A particular cache instance
    029         * is valid only for a particular obj array, i.e. it can be re-used between extractors but not between arguments.
    030         * @param obj Source objects.
    031         * @return Extracted value.
    032         */
    033        V extract(C context, Map<C, Map<Extractor<T, ? super V, C>, ? super V>> cache, T... obj);
    034
    035        /**
    036         * @return Indexes of objects which this extractor uses for computations.
    037         */
    038        Set<Integer> parameterIndices();
    039
    040        /**
    041         * @return True if extractor uses context for extraction. False if only object(s) are used.
    042         */
    043        boolean isContextDependent();
    044
    045        /**
    046         * Compares two extractors
    047         * @param other Other extractor
    048         * @return Comparison result.
    049         */
    050        ComparisonResult compareTo(Extractor<T, V, C> other);
    051
    052        /**
    053         * @return Extractor evaluation cost. Cost is used for optimization of computation intensive algorithms.
    054         * E.g. in Store it is used for selection of indices for query operations.
    055         */
    056        double getCost();
    057
    058}