* This factory obtains a range where the minimum and maximum values are fixed. * For example, the ISO month-of-year always runs from 1 to 12. * - * @param min the minimum value - * @param max the maximum value + * @param min the minimum value + * @param max the maximum value + * * @return the ValueRange for min, max, not null + * * @throws IllegalArgumentException if the minimum is greater than the maximum */ + /* + * 构造时间量字段的取值区间 + * + * min - 下区间最小值 + * min - 下区间最大值 + * max - 上区间最小值 + * max - 上区间最大值 + */ public static ValueRange of(long min, long max) { - if (min > max) { + if(min>max) { throw new IllegalArgumentException("Minimum value must be less than maximum value"); } + return new ValueRange(min, min, max, max); } @@ -143,6 +170,14 @@ public static ValueRange of(long min, long max) { * the minimum is greater than the smallest maximum, * or the smallest maximum is greater than the largest maximum */ + /* + * 构造时间量字段的取值区间 + * + * min - 下区间最小值 + * min - 下区间最大值 + * maxSmallest - 上区间最小值 + * maxLargest - 上区间最大值 + */ public static ValueRange of(long min, long maxSmallest, long maxLargest) { return of(min, min, maxSmallest, maxLargest); } @@ -162,49 +197,27 @@ public static ValueRange of(long min, long maxSmallest, long maxLargest) { * or the smallest maximum is greater than the largest maximum * or the largest minimum is greater than the largest maximum */ + /* + * 构造时间量字段的取值区间 + * + * minSmallest - 下区间最小值 + * minLargest - 下区间最大值 + * maxSmallest - 上区间最小值 + * maxLargest - 上区间最大值 + */ public static ValueRange of(long minSmallest, long minLargest, long maxSmallest, long maxLargest) { - if (minSmallest > minLargest) { + if(minSmallest>minLargest) { throw new IllegalArgumentException("Smallest minimum value must be less than largest minimum value"); } - if (maxSmallest > maxLargest) { + if(maxSmallest>maxLargest) { throw new IllegalArgumentException("Smallest maximum value must be less than largest maximum value"); } - if (minLargest > maxLargest) { + if(minLargest>maxLargest) { throw new IllegalArgumentException("Minimum value must be less than maximum value"); } return new ValueRange(minSmallest, minLargest, maxSmallest, maxLargest); } - /** - * Restrictive constructor. - * - * @param minSmallest the smallest minimum value - * @param minLargest the largest minimum value - * @param maxSmallest the smallest minimum value - * @param maxLargest the largest minimum value - */ - private ValueRange(long minSmallest, long minLargest, long maxSmallest, long maxLargest) { - this.minSmallest = minSmallest; - this.minLargest = minLargest; - this.maxSmallest = maxSmallest; - this.maxLargest = maxLargest; - } - - //----------------------------------------------------------------------- - /** - * Is the value range fixed and fully known. - *
- * For example, the ISO day-of-month runs from 1 to between 28 and 31. - * Since there is uncertainty about the maximum value, the range is not fixed. - * However, for the month of January, the range is always 1 to 31, thus it is fixed. - * - * @return true if the set of values is fixed - */ - public boolean isFixed() { - return minSmallest == minLargest && maxSmallest == maxLargest; - } - - //----------------------------------------------------------------------- /** * Gets the minimum value that the field can take. *
@@ -213,10 +226,11 @@ public boolean isFixed() { * * @return the minimum value for this field */ + // 返回下区间最小值 public long getMinimum() { return minSmallest; } - + /** * Gets the largest possible minimum value that the field can take. *
@@ -225,10 +239,24 @@ public long getMinimum() { * * @return the largest possible minimum value for this field */ + // 返回下区间最大值 public long getLargestMinimum() { return minLargest; } - + + /** + * Gets the maximum value that the field can take. + *
+ * For example, the ISO day-of-month runs to between 28 and 31 days. + * The maximum is therefore 31. + * + * @return the maximum value for this field + */ + // 返回上区间最大值 + public long getMaximum() { + return maxLargest; + } + /** * Gets the smallest possible maximum value that the field can take. *
@@ -237,23 +265,25 @@ public long getLargestMinimum() { * * @return the smallest possible maximum value for this field */ + // 返回上区间最小值 public long getSmallestMaximum() { return maxSmallest; } - + /** - * Gets the maximum value that the field can take. + * Is the value range fixed and fully known. *
- * For example, the ISO day-of-month runs to between 28 and 31 days. - * The maximum is therefore 31. + * For example, the ISO day-of-month runs from 1 to between 28 and 31. + * Since there is uncertainty about the maximum value, the range is not fixed. + * However, for the month of January, the range is always 1 to 31, thus it is fixed. * - * @return the maximum value for this field + * @return true if the set of values is fixed */ - public long getMaximum() { - return maxLargest; + // 判断字段的取值是否固定 + public boolean isFixed() { + return minSmallest == minLargest && maxSmallest == maxLargest; } - - //----------------------------------------------------------------------- + /** * Checks if all values in the range fit in an {@code int}. *
@@ -266,53 +296,62 @@ public long getMaximum() { * * @return true if a valid value always fits in an {@code int} */ + // 判断字段的取值区间是否在int的范围内 public boolean isIntValue() { - return getMinimum() >= Integer.MIN_VALUE && getMaximum() <= Integer.MAX_VALUE; + return getMinimum() >= Integer.MIN_VALUE && getMaximum()<=Integer.MAX_VALUE; } - + /** * Checks if the value is within the valid range. *
* This checks that the value is within the stored range of values. * - * @param value the value to check + * @param value the value to check + * * @return true if the value is valid */ + // 判断给定的值是否落在字段的取值区间中 public boolean isValidValue(long value) { - return (value >= getMinimum() && value <= getMaximum()); + return (value >= getMinimum() && value<=getMaximum()); } - + /** * Checks if the value is within the valid range and that all values * in the range fit in an {@code int}. *
* This method combines {@link #isIntValue()} and {@link #isValidValue(long)}. * - * @param value the value to check + * @param value the value to check + * * @return true if the value is valid and fits in an {@code int} */ + // 判断字段的取值区间是否在int的范围内，且给定的值是否落在字段的取值区间中 public boolean isValidIntValue(long value) { return isIntValue() && isValidValue(value); } - + /** * Checks that the specified value is valid. *
* This validates that the value is within the valid range of values. * The field is only used to improve the error message. * - * @param value the value to check - * @param field the field being checked, may be null + * @param value the value to check + * @param field the field being checked, may be null + * * @return the value that was passed in + * * @see #isValidValue(long) */ + // 确保给定的值落在字段field的取值区间中，否则抛异常 public long checkValidValue(long value, TemporalField field) { - if (isValidValue(value) == false) { - throw new DateTimeException(genInvalidFieldMessage(field, value)); + if(isValidValue(value)) { + return value; } - return value; + + throw new DateTimeException(genInvalidFieldMessage(field, value)); } - + /** * Checks that the specified value is valid and fits in an {@code int}. *
@@ -320,54 +359,55 @@ public long checkValidValue(long value, TemporalField field) { * all valid values are within the bounds of an {@code int}. * The field is only used to improve the error message. * - * @param value the value to check - * @param field the field being checked, may be null + * @param value the value to check + * @param field the field being checked, may be null + * * @return the value that was passed in + * * @see #isValidIntValue(long) */ + // 确保字段field的取值区间在int的范围内，且给定的值value落在字段field的取值区间中，否则抛异常 public int checkValidIntValue(long value, TemporalField field) { - if (isValidIntValue(value) == false) { + if(!isValidIntValue(value)) { throw new DateTimeException(genInvalidFieldMessage(field, value)); } + return (int) value; } - + + // 给出异常信息 private String genInvalidFieldMessage(TemporalField field, long value) { - if (field != null) { + if(field != null) { return "Invalid value for " + field + " (valid values " + this + "): " + value; } else { return "Invalid value (valid values " + this + "): " + value; } } - - //----------------------------------------------------------------------- + + /** - * Restore the state of an ValueRange from the stream. - * Check that the values are valid. + * Outputs this range as a {@code String}. + *
+ * The format will be '{min}/{largestMin} - {smallestMax}/{max}', + * where the largestMin or smallestMax sections may be omitted, together + * with associated slash, if they are the same as the min or max. * - * @param s the stream to read - * @throws InvalidObjectException if - * the smallest minimum is greater than the smallest maximum, - * or the smallest maximum is greater than the largest maximum - * or the largest minimum is greater than the largest maximum - * @throws ClassNotFoundException if a class cannot be resolved + * @return a string representation of this range, not null */ - private void readObject(ObjectInputStream s) - throws IOException, ClassNotFoundException, InvalidObjectException - { - s.defaultReadObject(); - if (minSmallest > minLargest) { - throw new InvalidObjectException("Smallest minimum value must be less than largest minimum value"); - } - if (maxSmallest > maxLargest) { - throw new InvalidObjectException("Smallest maximum value must be less than largest maximum value"); + @Override + public String toString() { + StringBuilder buf = new StringBuilder(); + buf.append(minSmallest); + if(minSmallest != minLargest) { + buf.append('/').append(minLargest); } - if (minLargest > maxLargest) { - throw new InvalidObjectException("Minimum value must be less than maximum value"); + buf.append(" - ").append(maxSmallest); + if(maxSmallest != maxLargest) { + buf.append('/').append(maxLargest); } + return buf.toString(); } - - //----------------------------------------------------------------------- + /** * Checks if this range is equal to another range. *
@@ -375,22 +415,22 @@ private void readObject(ObjectInputStream s) * smallest maximum and maximum. * Only objects of type {@code ValueRange} are compared, other types return false. * - * @param obj the object to check, null returns false + * @param obj the object to check, null returns false + * * @return true if this is equal to the other range */ @Override public boolean equals(Object obj) { - if (obj == this) { + if(obj == this) { return true; } - if (obj instanceof ValueRange) { + if(obj instanceof ValueRange) { ValueRange other = (ValueRange) obj; - return minSmallest == other.minSmallest && minLargest == other.minLargest && - maxSmallest == other.maxSmallest && maxLargest == other.maxLargest; + return minSmallest == other.minSmallest && minLargest == other.minLargest && maxSmallest == other.maxSmallest && maxLargest == other.maxLargest; } return false; } - + /** * A hash code for this range. * @@ -398,34 +438,34 @@ public boolean equals(Object obj) { */ @Override public int hashCode() { - long hash = minSmallest + (minLargest << 16) + (minLargest >> 48) + - (maxSmallest << 32) + (maxSmallest >> 32) + (maxLargest << 48) + - (maxLargest >> 16); + long hash = minSmallest + (minLargest << 16) + (minLargest >> 48) + (maxSmallest << 32) + (maxSmallest >> 32) + (maxLargest << 48) + (maxLargest >> 16); return (int) (hash ^ (hash >>> 32)); } - - //----------------------------------------------------------------------- + + /** - * Outputs this range as a {@code String}. - *
- * The format will be '{min}/{largestMin} - {smallestMax}/{max}', - * where the largestMin or smallestMax sections may be omitted, together - * with associated slash, if they are the same as the min or max. + * Restore the state of an ValueRange from the stream. + * Check that the values are valid. * - * @return a string representation of this range, not null + * @param s the stream to read + * + * @throws InvalidObjectException if + * the smallest minimum is greater than the smallest maximum, + * or the smallest maximum is greater than the largest maximum + * or the largest minimum is greater than the largest maximum + * @throws ClassNotFoundException if a class cannot be resolved */ - @Override - public String toString() { - StringBuilder buf = new StringBuilder(); - buf.append(minSmallest); - if (minSmallest != minLargest) { - buf.append('/').append(minLargest); + private void readObject(ObjectInputStream s) throws IOException, ClassNotFoundException, InvalidObjectException { + s.defaultReadObject(); + if(minSmallest>minLargest) { + throw new InvalidObjectException("Smallest minimum value must be less than largest minimum value"); } - buf.append(" - ").append(maxSmallest); - if (maxSmallest != maxLargest) { - buf.append('/').append(maxLargest); + if(maxSmallest>maxLargest) { + throw new InvalidObjectException("Smallest maximum value must be less than largest maximum value"); + } + if(minLargest>maxLargest) { + throw new InvalidObjectException("Minimum value must be less than maximum value"); } - return buf.toString(); } - + }