IntervalProvider.java

/* 
*	Copyright 2013 Gordon Burgett and individual contributors
*
*	Licensed under the Apache License, Version 2.0 (the "License");
*	you may not use this file except in compliance with the License.
*	You may obtain a copy of the License at
*
*      http://www.apache.org/licenses/LICENSE-2.0
*
*	Unless required by applicable law or agreed to in writing, software
*	distributed under the License is distributed on an "AS IS" BASIS,
*	WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
*	See the License for the specific language governing permissions and
*	limitations under the License.
*/
package org.xflatdb.xflat.query;

import java.util.Comparator;

/**
 * Interval Providers are used to determine intervals for sharding.  An interval
 * provider determines an unlimited set of fixed-width intervals, each of which is mapped
 * to a "bucket" into which data that fits into that interval is stored.
 * <p/>
 * IntervalProvider implementations ought to be able to handle any value that
 * is expected to be selected by a sharding selector.
 * @author Gordon
 */
public interface IntervalProvider<T> {
    
    /**
     * Gets the interval that contains the given value.  This interval
     * will be used to determine the bucket into which the data associated
     * to the value is stored.
     * 
     * @param value The value for which a interval is needed.
     * @return The interval for that value.
     */
    public Interval<T> getInterval(T value);
    
    /**
     * Gets another interval, which is a number of standard intervals away from the 
     * given interval.
     * <p/>
     * For instance, on an integer interval provider, if the current interval is
     * [0, 10) and the factor is 1, the nextRange is [10, 20).<br/>
     * If the factor is -2, the nextRange is [-20, -10).
     * @param currentInterval The base interval
     * @param factor The number of ranges to skip.
     * @return A new interval that is factor ranges away from currentRange.
     */
    public Interval<T> nextInterval(Interval<T> currentInterval, long factor);
    
    /**
     * Returns a comparator that can compare the values provided by this interval.
     * @return An instance of Comparator that compares this interval's values.
     */
    public Comparator<T> getComparator();
    
    /**
     * Gets a unique name for this interval.  This name should be unique
     * within the intervals provided by this IntervalProvider.  This will
     * be used by sharded engines to name shard files, and so cannot contain any
     * illegal file path characters.
     * @param interval The interval for which a unique name is needed.
     * @return The unique name of the interval, not containing any illegal file characters.
     */
    public String getName(Interval<T> interval);
    
    /**
     * Gets an interval from the interval's unique name.
     * Since the name is unique it should reliably map to an interval.
     * If the name is unparseable or cannot be mapped to an interval, null should
     * be returned instead of throwing an exception.
     * @param name The interval's unique name, generated by {@link #getName(org.xflatdb.xflat.query.Interval) }
     * @return The interval for the given unique name.
     */
    public Interval<T> getInterval(String name);
}