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}