hbase-common/src/main/java/org/apache/hadoop/hbase/io/TimeRange.java

   1 /*
   2  * Licensed to the Apache Software Foundation (ASF) under one
   3  * or more contributor license agreements.  See the NOTICE file
   4  * distributed with this work for additional information
   5  * regarding copyright ownership.  The ASF licenses this file
   6  * to you under the Apache License, Version 2.0 (the
   7  * "License"); you may not use this file except in compliance
   8  * with the License.  You may obtain a copy of the License at
   9  *
  10  *     http://www.apache.org/licenses/LICENSE-2.0
  11  *
  12  * Unless required by applicable law or agreed to in writing, software
  13  * distributed under the License is distributed on an "AS IS" BASIS,
  14  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  15  * See the License for the specific language governing permissions and
  16  * limitations under the License.
  17  */
  18
  19 package org.apache.hadoop.hbase.io;
  20
  21 import org.apache.yetus.audience.InterfaceAudience;
  22
  23 /**
  24  * Represents an interval of version timestamps. Presumes timestamps between
  25  * {@link #INITIAL_MIN_TIMESTAMP} and {@link #INITIAL_MAX_TIMESTAMP} only. Gets freaked out if
  26  * passed a timestamp that is < {@link #INITIAL_MIN_TIMESTAMP},
  27  * <p/>
  28  * Evaluated according to minStamp &lt;= timestamp &lt; maxStamp or [minStamp,maxStamp) in interval
  29  * notation.
  30  * <p/>
  31  * Can be returned and read by clients. Should not be directly created by clients. Thus, all
  32  * constructors are purposely @InterfaceAudience.Private.
  33  * <p/>
  34  * Immutable. Thread-safe.
  35  */
  36 @InterfaceAudience.Public
  37 public final class TimeRange {
  38   public static final long INITIAL_MIN_TIMESTAMP = 0L;
  39   public static final long INITIAL_MAX_TIMESTAMP = Long.MAX_VALUE;
  40   private static final TimeRange ALL_TIME = new TimeRange(INITIAL_MIN_TIMESTAMP,
  41     INITIAL_MAX_TIMESTAMP);
  42
  43   public static TimeRange allTime() {
  44     return ALL_TIME;
  45   }
  46
  47   public static TimeRange at(long ts) {
  48     if (ts < 0 || ts == Long.MAX_VALUE) {
  49       throw new IllegalArgumentException("invalid ts:" + ts);
  50     }
  51     return new TimeRange(ts, ts + 1);
  52   }
  53
  54   /**
  55    * Represents the time interval [minStamp, Long.MAX_VALUE)
  56    * @param minStamp the minimum timestamp value, inclusive
  57    */
  58   public static TimeRange from(long minStamp) {
  59     check(minStamp, INITIAL_MAX_TIMESTAMP);
  60     return new TimeRange(minStamp, INITIAL_MAX_TIMESTAMP);
  61   }
  62
  63   /**
  64    * Represents the time interval [0, maxStamp)
  65    * @param maxStamp the minimum timestamp value, exclusive
  66    */
  67   public static TimeRange until(long maxStamp) {
  68     check(INITIAL_MIN_TIMESTAMP, maxStamp);
  69     return new TimeRange(INITIAL_MIN_TIMESTAMP, maxStamp);
  70   }
  71
  72   /**
  73    * Represents the time interval [minStamp, maxStamp)
  74    * @param minStamp the minimum timestamp, inclusive
  75    * @param maxStamp the maximum timestamp, exclusive
  76    */
  77   public static TimeRange between(long minStamp, long maxStamp) {
  78     check(minStamp, maxStamp);
  79     return new TimeRange(minStamp, maxStamp);
  80   }
  81
  82   private final long minStamp;
  83   private final long maxStamp;
  84   private final boolean allTime;
  85
  86   /**
  87    * Represents interval [minStamp, maxStamp)
  88    * @param minStamp the minimum timestamp, inclusive
  89    * @param maxStamp the maximum timestamp, exclusive
  90    * @throws IllegalArgumentException if either <0,
  91    */
  92   private TimeRange(long minStamp, long maxStamp) {
  93     this.minStamp = minStamp;
  94     this.maxStamp = maxStamp;
  95     this.allTime = isAllTime(minStamp, maxStamp);
  96   }
  97
  98   private static boolean isAllTime(long minStamp, long maxStamp) {
  99     return minStamp == INITIAL_MIN_TIMESTAMP && maxStamp == INITIAL_MAX_TIMESTAMP;
 100   }
 101
 102   private static void check(long minStamp, long maxStamp) {
 103     if (minStamp < 0 || maxStamp < 0) {
 104       throw new IllegalArgumentException("Timestamp cannot be negative. minStamp:" + minStamp
 105         + ", maxStamp:" + maxStamp);
 106     }
 107     if (maxStamp < minStamp) {
 108       throw new IllegalArgumentException("maxStamp is smaller than minStamp");
 109     }
 110   }
 111
 112   /**
 113    * @return the smallest timestamp that should be considered
 114    */
 115   public long getMin() {
 116     return minStamp;
 117   }
 118
 119   /**
 120    * @return the biggest timestamp that should be considered
 121    */
 122   public long getMax() {
 123     return maxStamp;
 124   }
 125
 126   /**
 127    * Check if it is for all time
 128    * @return true if it is for all time
 129    */
 130   public boolean isAllTime() {
 131     return allTime;
 132   }
 133
 134   /**
 135    * Check if the specified timestamp is within this TimeRange.
 136    * <p/>
 137    * Returns true if within interval [minStamp, maxStamp), false if not.
 138    * @param timestamp timestamp to check
 139    * @return true if within TimeRange, false if not
 140    */
 141   public boolean withinTimeRange(long timestamp) {
 142     assert timestamp >= 0;
 143     if (this.allTime) {
 144       return true;
 145     }
 146     // check if >= minStamp
 147     return (minStamp <= timestamp && timestamp < maxStamp);
 148   }
 149
 150   /**
 151    * Check if the range has any overlap with TimeRange
 152    * @param tr TimeRange
 153    * @return True if there is overlap, false otherwise
 154    */
 155   // This method came from TimeRangeTracker. We used to go there for this function but better
 156   // to come here to the immutable, unsynchronized datastructure at read time.
 157   public boolean includesTimeRange(final TimeRange tr) {
 158     if (this.allTime) {
 159       return true;
 160     }
 161     assert tr.getMin() >= 0;
 162     return getMin() < tr.getMax() && getMax() >= tr.getMin();
 163   }
 164
 165   /**
 166    * Check if the specified timestamp is within or after this TimeRange.
 167    * <p>
 168    * Returns true if greater than minStamp, false if not.
 169    * @param timestamp timestamp to check
 170    * @return true if within or after TimeRange, false if not
 171    */
 172   public boolean withinOrAfterTimeRange(long timestamp) {
 173     assert timestamp >= 0;
 174     if (allTime) {
 175       return true;
 176     }
 177     // check if >= minStamp
 178     return timestamp >= minStamp;
 179   }
 180
 181   /**
 182    * Compare the timestamp to timerange.
 183    * @return -1 if timestamp is less than timerange,
 184    * 0 if timestamp is within timerange,
 185    * 1 if timestamp is greater than timerange
 186    */
 187   public int compare(long timestamp) {
 188     assert timestamp >= 0;
 189     if (this.allTime) {
 190       return 0;
 191     }
 192     if (timestamp < minStamp) {
 193       return -1;
 194     }
 195     return timestamp >= maxStamp? 1: 0;
 196   }
 197
 198   @Override
 199   public String toString() {
 200     StringBuilder sb = new StringBuilder();
 201     sb.append("maxStamp=");
 202     sb.append(this.maxStamp);
 203     sb.append(", minStamp=");
 204     sb.append(this.minStamp);
 205     return sb.toString();
 206   }
 207 }