      1 /*
      2  * Copyright (c) 2012, 2020, Oracle and/or its affiliates. All rights reserved.
      3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
      4  *
      5  * This code is free software; you can redistribute it and/or modify it
      6  * under the terms of the GNU General Public License version 2 only, as
      7  * published by the Free Software Foundation.  Oracle designates this
      8  * particular file as subject to the "Classpath" exception as provided
      9  * by Oracle in the LICENSE file that accompanied this code.
     10  *
     11  * This code is distributed in the hope that it will be useful, but WITHOUT
     12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
     13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
     14  * version 2 for more details (a copy is included in the LICENSE file that
     15  * accompanied this code).
     16  *
     17  * You should have received a copy of the GNU General Public License version
     18  * 2 along with this work; if not, write to the Free Software Foundation,
     19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
     20  *
     21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
     22  * or visit www.oracle.com if you need additional information or have any
     23  * questions.
     24  */
     25
     26 /*
     27  * This file is available under and governed by the GNU General Public
     28  * License version 2 only, as published by the Free Software Foundation.
     29  * However, the following notice accompanied the original version of this
     30  * file:
     31  *
     32  * Copyright (c) 2011-2012, Stephen Colebourne & Michael Nascimento Santos
     33  *
     34  * All rights reserved.
     35  *
     36  * Redistribution and use in source and binary forms, with or without
     37  * modification, are permitted provided that the following conditions are met:
     38  *
     39  *  * Redistributions of source code must retain the above copyright notice,
     40  *    this list of conditions and the following disclaimer.
     41  *
     42  *  * Redistributions in binary form must reproduce the above copyright notice,
     43  *    this list of conditions and the following disclaimer in the documentation
     44  *    and/or other materials provided with the distribution.
     45  *
     46  *  * Neither the name of JSR-310 nor the names of its contributors
     47  *    may be used to endorse or promote products derived from this software
     48  *    without specific prior written permission.
     49  *
     50  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
     51  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
     52  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
     53  * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
     54  * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
     55  * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
     56  * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
     57  * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
     58  * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
     59  * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
     60  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
     61  */
     62 package java.time.temporal;
     63
     64 import java.io.IOException;
     65 import java.io.InvalidObjectException;
     66 import java.io.ObjectInputStream;
     67 import java.io.Serializable;
     68 import java.time.DateTimeException;
     69
     70 /**
     71  * The range of valid values for a date-time field.
     72  * <p>
     73  * All {@link TemporalField} instances have a valid range of values.
     74  * For example, the ISO day-of-month runs from 1 to somewhere between 28 and 31.
     75  * This class captures that valid range.
     76  * <p>
     77  * It is important to be aware of the limitations of this class.
     78  * Only the minimum and maximum values are provided.
     79  * It is possible for there to be invalid values within the outer range.
     80  * For example, a weird field may have valid values of 1, 2, 4, 6, 7, thus
     81  * have a range of '1 - 7', despite that fact that values 3 and 5 are invalid.
     82  * <p>
     83  * Instances of this class are not tied to a specific field.
     84  *
     85  * @implSpec
     86  * This class is immutable and thread-safe.
     87  *
     88  * @since 1.8
     89  */
     90 public final class ValueRange implements Serializable {
     91
     92     /**
     93      * Serialization version.
     94      */
     95     @java.io.Serial
     96     private static final long serialVersionUID = -7317881728594519368L;
     97
     98     /**
     99      * The smallest minimum value.
    100      */
    101     private final long minSmallest;
    102     /**
    103      * The largest minimum value.
    104      */
    105     private final long minLargest;
    106     /**
    107      * The smallest maximum value.
    108      */
    109     private final long maxSmallest;
    110     /**
    111      * The largest maximum value.
    112      */
    113     private final long maxLargest;
    114
    115     /**
    116      * Obtains a fixed value range.
    117      * <p>
    118      * This factory obtains a range where the minimum and maximum values are fixed.
    119      * For example, the ISO month-of-year always runs from 1 to 12.
    120      *
    121      * @param min  the minimum value
    122      * @param max  the maximum value
    123      * @return the ValueRange for min, max, not null
    124      * @throws IllegalArgumentException if the minimum is greater than the maximum
    125      */
    126     public static ValueRange of(long min, long max) {
    127         if (min > max) {
    128             throw new IllegalArgumentException("Minimum value must be less than maximum value");
    129         }
    130         return new ValueRange(min, min, max, max);
    131     }
    132
    133     /**
    134      * Obtains a variable value range.
    135      * <p>
    136      * This factory obtains a range where the minimum value is fixed and the maximum value may vary.
    137      * For example, the ISO day-of-month always starts at 1, but ends between 28 and 31.
    138      *
    139      * @param min  the minimum value
    140      * @param maxSmallest  the smallest maximum value
    141      * @param maxLargest  the largest maximum value
    142      * @return the ValueRange for min, smallest max, largest max, not null
    143      * @throws IllegalArgumentException if
    144      *     the minimum is greater than the smallest maximum,
    145      *  or the smallest maximum is greater than the largest maximum
    146      */
    147     public static ValueRange of(long min, long maxSmallest, long maxLargest) {
    148         if (min > maxSmallest) {
    149             throw new IllegalArgumentException("Minimum value must be less than smallest maximum value");
    150         }
    151         return of(min, min, maxSmallest, maxLargest);
    152     }
    153
    154     /**
    155      * Obtains a fully variable value range.
    156      * <p>
    157      * This factory obtains a range where both the minimum and maximum value may vary.
    158      *
    159      * @param minSmallest  the smallest minimum value
    160      * @param minLargest  the largest minimum value
    161      * @param maxSmallest  the smallest maximum value
    162      * @param maxLargest  the largest maximum value
    163      * @return the ValueRange for smallest min, largest min, smallest max, largest max, not null
    164      * @throws IllegalArgumentException if
    165      *     the smallest minimum is greater than the smallest maximum,
    166      *  or the smallest maximum is greater than the largest maximum,
    167      *  or the largest minimum is greater than the largest maximum,
    168      *  or the smallest minimum is greater than the largest minimum
    169      */
    170     public static ValueRange of(long minSmallest, long minLargest, long maxSmallest, long maxLargest) {
    171         if (minSmallest > minLargest) {
    172             throw new IllegalArgumentException("Smallest minimum value must be less than largest minimum value");
    173         }
    174         if (maxSmallest > maxLargest) {
    175             throw new IllegalArgumentException("Smallest maximum value must be less than largest maximum value");
    176         }
    177         if (minLargest > maxLargest) {
    178             throw new IllegalArgumentException("Largest minimum value must be less than largest maximum value");
    179         }
    180         if (minSmallest > maxSmallest) {
    181             throw new IllegalArgumentException("Smallest minimum value must be less than smallest maximum value");
    182         }
    183         return new ValueRange(minSmallest, minLargest, maxSmallest, maxLargest);
    184     }
    185
    186     /**
    187      * Restrictive constructor.
    188      *
    189      * @param minSmallest  the smallest minimum value
    190      * @param minLargest  the largest minimum value
    191      * @param maxSmallest  the smallest minimum value
    192      * @param maxLargest  the largest minimum value
    193      */
    194     private ValueRange(long minSmallest, long minLargest, long maxSmallest, long maxLargest) {
    195         this.minSmallest = minSmallest;
    196         this.minLargest = minLargest;
    197         this.maxSmallest = maxSmallest;
    198         this.maxLargest = maxLargest;
    199     }
    200
    201     //-----------------------------------------------------------------------
    202     /**
    203      * Is the value range fixed and fully known.
    204      * <p>
    205      * For example, the ISO day-of-month runs from 1 to between 28 and 31.
    206      * Since there is uncertainty about the maximum value, the range is not fixed.
    207      * However, for the month of January, the range is always 1 to 31, thus it is fixed.
    208      *
    209      * @return true if the set of values is fixed
    210      */
    211     public boolean isFixed() {
    212         return minSmallest == minLargest && maxSmallest == maxLargest;
    213     }
    214
    215     //-----------------------------------------------------------------------
    216     /**
    217      * Gets the minimum value that the field can take.
    218      * <p>
    219      * For example, the ISO day-of-month always starts at 1.
    220      * The minimum is therefore 1.
    221      *
    222      * @return the minimum value for this field
    223      */
    224     public long getMinimum() {
    225         return minSmallest;
    226     }
    227
    228     /**
    229      * Gets the largest possible minimum value that the field can take.
    230      * <p>
    231      * For example, the ISO day-of-month always starts at 1.
    232      * The largest minimum is therefore 1.
    233      *
    234      * @return the largest possible minimum value for this field
    235      */
    236     public long getLargestMinimum() {
    237         return minLargest;
    238     }
    239
    240     /**
    241      * Gets the smallest possible maximum value that the field can take.
    242      * <p>
    243      * For example, the ISO day-of-month runs to between 28 and 31 days.
    244      * The smallest maximum is therefore 28.
    245      *
    246      * @return the smallest possible maximum value for this field
    247      */
    248     public long getSmallestMaximum() {
    249         return maxSmallest;
    250     }
    251
    252     /**
    253      * Gets the maximum value that the field can take.
    254      * <p>
    255      * For example, the ISO day-of-month runs to between 28 and 31 days.
    256      * The maximum is therefore 31.
    257      *
    258      * @return the maximum value for this field
    259      */
    260     public long getMaximum() {
    261         return maxLargest;
    262     }
    263
    264     //-----------------------------------------------------------------------
    265     /**
    266      * Checks if all values in the range fit in an {@code int}.
    267      * <p>
    268      * This checks that all valid values are within the bounds of an {@code int}.
    269      * <p>
    270      * For example, the ISO month-of-year has values from 1 to 12, which fits in an {@code int}.
    271      * By comparison, ISO nano-of-day runs from 1 to 86,400,000,000,000 which does not fit in an {@code int}.
    272      * <p>
    273      * This implementation uses {@link #getMinimum()} and {@link #getMaximum()}.
    274      *
    275      * @return true if a valid value always fits in an {@code int}
    276      */
    277     public boolean isIntValue() {
    278         return getMinimum() >= Integer.MIN_VALUE && getMaximum() <= Integer.MAX_VALUE;
    279     }
    280
    281     /**
    282      * Checks if the value is within the valid range.
    283      * <p>
    284      * This checks that the value is within the stored range of values.
    285      *
    286      * @param value  the value to check
    287      * @return true if the value is valid
    288      */
    289     public boolean isValidValue(long value) {
    290         return (value >= getMinimum() && value <= getMaximum());
    291     }
    292
    293     /**
    294      * Checks if the value is within the valid range and that all values
    295      * in the range fit in an {@code int}.
    296      * <p>
    297      * This method combines {@link #isIntValue()} and {@link #isValidValue(long)}.
    298      *
    299      * @param value  the value to check
    300      * @return true if the value is valid and fits in an {@code int}
    301      */
    302     public boolean isValidIntValue(long value) {
    303         return isIntValue() && isValidValue(value);
    304     }
    305
    306     /**
    307      * Checks that the specified value is valid.
    308      * <p>
    309      * This validates that the value is within the valid range of values.
    310      * The field is only used to improve the error message.
    311      *
    312      * @param value  the value to check
    313      * @param field  the field being checked, may be null
    314      * @return the value that was passed in
    315      * @see #isValidValue(long)
    316      */
    317     public long checkValidValue(long value, TemporalField field) {
    318         if (isValidValue(value) == false) {
    319             throw new DateTimeException(genInvalidFieldMessage(field, value));
    320         }
    321         return value;
    322     }
    323
    324     /**
    325      * Checks that the specified value is valid and fits in an {@code int}.
    326      * <p>
    327      * This validates that the value is within the valid range of values and that
    328      * all valid values are within the bounds of an {@code int}.
    329      * The field is only used to improve the error message.
    330      *
    331      * @param value  the value to check
    332      * @param field  the field being checked, may be null
    333      * @return the value that was passed in
    334      * @see #isValidIntValue(long)
    335      */
    336     public int checkValidIntValue(long value, TemporalField field) {
    337         if (isValidIntValue(value) == false) {
    338             throw new DateTimeException(genInvalidFieldMessage(field, value));
    339         }
    340         return (int) value;
    341     }
    342
    343     private String genInvalidFieldMessage(TemporalField field, long value) {
    344         if (field != null) {
    345             return "Invalid value for " + field + " (valid values " + this + "): " + value;
    346         } else {
    347             return "Invalid value (valid values " + this + "): " + value;
    348         }
    349     }
    350
    351     //-----------------------------------------------------------------------
    352     /**
    353      * Restore the state of an ValueRange from the stream.
    354      * Check that the values are valid.
    355      *
    356      * @param s the stream to read
    357      * @throws InvalidObjectException if
    358      *     the smallest minimum is greater than the smallest maximum,
    359      *  or the smallest maximum is greater than the largest maximum
    360      *  or the largest minimum is greater than the largest maximum
    361      * @throws ClassNotFoundException if a class cannot be resolved
    362      */
    363     @java.io.Serial
    364     private void readObject(ObjectInputStream s)
    365          throws IOException, ClassNotFoundException, InvalidObjectException
    366     {
    367         s.defaultReadObject();
    368         if (minSmallest > minLargest) {
    369             throw new InvalidObjectException("Smallest minimum value must be less than largest minimum value");
    370         }
    371         if (maxSmallest > maxLargest) {
    372             throw new InvalidObjectException("Smallest maximum value must be less than largest maximum value");
    373         }
    374         if (minLargest > maxLargest) {
    375             throw new InvalidObjectException("Minimum value must be less than maximum value");
    376         }
    377     }
    378
    379     //-----------------------------------------------------------------------
    380     /**
    381      * Checks if this range is equal to another range.
    382      * <p>
    383      * The comparison is based on the four values, minimum, largest minimum,
    384      * smallest maximum and maximum.
    385      * Only objects of type {@code ValueRange} are compared, other types return false.
    386      *
    387      * @param obj  the object to check, null returns false
    388      * @return true if this is equal to the other range
    389      */
    390     @Override
    391     public boolean equals(Object obj) {
    392         if (obj == this) {
    393             return true;
    394         }
    395         if (obj instanceof ValueRange) {
    396             ValueRange other = (ValueRange) obj;
    397             return minSmallest == other.minSmallest && minLargest == other.minLargest &&
    398                    maxSmallest == other.maxSmallest && maxLargest == other.maxLargest;
    399         }
    400         return false;
    401     }
    402
    403     /**
    404      * A hash code for this range.
    405      *
    406      * @return a suitable hash code
    407      */
    408     @Override
    409     public int hashCode() {
    410         long hash = minSmallest + (minLargest << 16) + (minLargest >> 48) +
    411                 (maxSmallest << 32) + (maxSmallest >> 32) + (maxLargest << 48) +
    412                 (maxLargest >> 16);
    413         return (int) (hash ^ (hash >>> 32));
    414     }
    415
    416     //-----------------------------------------------------------------------
    417     /**
    418      * Outputs this range as a {@code String}.
    419      * <p>
    420      * The format will be '{min}/{largestMin} - {smallestMax}/{max}',
    421      * where the largestMin or smallestMax sections may be omitted, together
    422      * with associated slash, if they are the same as the min or max.
    423      *
    424      * @return a string representation of this range, not null
    425      */
    426     @Override
    427     public String toString() {
    428         StringBuilder buf = new StringBuilder();
    429         buf.append(minSmallest);
    430         if (minSmallest != minLargest) {
    431             buf.append('/').append(minLargest);
    432         }
    433         buf.append(" - ").append(maxSmallest);
    434         if (maxSmallest != maxLargest) {
    435             buf.append('/').append(maxLargest);
    436         }
    437         return buf.toString();
    438     }
    439
    440 }