com.bol.ipresource.ip.Interval Maven / Gradle / Ivy

Go to download

Show more of this group Show more artifacts with this name
Show all versions of ip-resource Show documentation

High performance, low memory IP library (originally developed for RIPE NCC Whois server)

There is a newer version: 1.4.7

package com.bol.ipresource.ip;

import com.bol.ipresource.etree.NestedIntervalMap;

/**
 * An interval with a lower-bound and upper-bound. Both bounds are considered to
 * be inclusive.
 * 
 * Implementations of this interface must be immutable and must correctly
 * override {@link Object#equals(Object)} and {@link Object#hashCode()} based on
 * the bounds.
 *
 * @param  the interval type
 */
public interface Interval> {

    /**
     * Tests if this interval contains that. Note that if two
     * intervals are equal, they also contain each other (and vice
     * versa). An interval always contains itself.
     *
     * @param that the interval to test for containment
     * @return true if this contains that interval
     */
    boolean contains(K that);

    /**
     * Tests if these two intervals intersect. Two intervals intersect if there
     * exists a point which is contained within both intervals. An interval
     * always intersects itself.
     *
     * @param that the other interval to test for intersection
     * @return true if this interval intersects that
     *         interval
     */
    boolean intersects(K that);

    /**
     * Copies this interval into a new interval that has both its lower and
     * upper-bound set to the original's lower-bound. This is used to be able to
     * compare an interval's lower-bound with another interval's upper-bound.
     * 

     * 
     *   Interval a = ...
     *   Interval b = ...
     *   if (a.singletonIntervalAtLowerBound().compareUpperBoundTo(b) < 0) ...
     * 
     *
     * @return a new interval that has both its lower- and upper-bound set to
     *         this interval's lower-bound
     */
    K singletonIntervalAtLowerBound();

    /**
     * Compare two intervals based on their upper-bounds. This is used by the
     * {@link NestedIntervalMap} implementation to quickly find two potentially
     * intersecting intervals by ordering intervals on the upper-bound and
     * searching based on the lower-bound.
     *
     * @param that the interval to compare the upper-bound with
     * @return <0 if this upper-bound is less than that upper-bound,
 =0 if
     *         this upper-bound equals that upper-bound,
 >0 if this
     *         upper-bound is greater than that upper-bound
     */
    int compareUpperBound(K that);
}