476 lines
18 KiB
Java
476 lines
18 KiB
Java
/*
|
|
* Copyright (c) 2009, 2013, Oracle and/or its affiliates. All rights reserved.
|
|
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
|
|
*
|
|
* This code is free software; you can redistribute it and/or modify it
|
|
* under the terms of the GNU General Public License version 2 only, as
|
|
* published by the Free Software Foundation. Oracle designates this
|
|
* particular file as subject to the "Classpath" exception as provided
|
|
* by Oracle in the LICENSE file that accompanied this code.
|
|
*
|
|
* This code is distributed in the hope that it will be useful, but WITHOUT
|
|
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
|
|
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
|
|
* version 2 for more details (a copy is included in the LICENSE file that
|
|
* accompanied this code).
|
|
*
|
|
* You should have received a copy of the GNU General Public License version
|
|
* 2 along with this work; if not, write to the Free Software Foundation,
|
|
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
|
|
*
|
|
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
|
|
* or visit www.oracle.com if you need additional information or have any
|
|
* questions.
|
|
*/
|
|
|
|
package java.nio.file.attribute;
|
|
|
|
import java.time.Instant;
|
|
import java.time.LocalDateTime;
|
|
import java.time.ZoneOffset;
|
|
import java.util.Objects;
|
|
import java.util.concurrent.TimeUnit;
|
|
|
|
/**
|
|
* Represents the value of a file's time stamp attribute. For example, it may
|
|
* represent the time that the file was last
|
|
* {@link BasicFileAttributes#lastModifiedTime() modified},
|
|
* {@link BasicFileAttributes#lastAccessTime() accessed},
|
|
* or {@link BasicFileAttributes#creationTime() created}.
|
|
*
|
|
* <p> Instances of this class are immutable.
|
|
*
|
|
* @since 1.7
|
|
* @see java.nio.file.Files#setLastModifiedTime
|
|
* @see java.nio.file.Files#getLastModifiedTime
|
|
*/
|
|
|
|
public final class FileTime
|
|
implements Comparable<FileTime>
|
|
{
|
|
/**
|
|
* The unit of granularity to interpret the value. Null if
|
|
* this {@code FileTime} is converted from an {@code Instant},
|
|
* the {@code value} and {@code unit} pair will not be used
|
|
* in this scenario.
|
|
*/
|
|
private final TimeUnit unit;
|
|
|
|
/**
|
|
* The value since the epoch; can be negative.
|
|
*/
|
|
private final long value;
|
|
|
|
/**
|
|
* The value as Instant (created lazily, if not from an instant)
|
|
*/
|
|
private Instant instant;
|
|
|
|
/**
|
|
* The value return by toString (created lazily)
|
|
*/
|
|
private String valueAsString;
|
|
|
|
/**
|
|
* Initializes a new instance of this class.
|
|
*/
|
|
private FileTime(long value, TimeUnit unit, Instant instant) {
|
|
this.value = value;
|
|
this.unit = unit;
|
|
this.instant = instant;
|
|
}
|
|
|
|
/**
|
|
* Returns a {@code FileTime} representing a value at the given unit of
|
|
* granularity.
|
|
*
|
|
* @param value
|
|
* the value since the epoch (1970-01-01T00:00:00Z); can be
|
|
* negative
|
|
* @param unit
|
|
* the unit of granularity to interpret the value
|
|
*
|
|
* @return a {@code FileTime} representing the given value
|
|
*/
|
|
public static FileTime from(long value, TimeUnit unit) {
|
|
Objects.requireNonNull(unit, "unit");
|
|
return new FileTime(value, unit, null);
|
|
}
|
|
|
|
/**
|
|
* Returns a {@code FileTime} representing the given value in milliseconds.
|
|
*
|
|
* @param value
|
|
* the value, in milliseconds, since the epoch
|
|
* (1970-01-01T00:00:00Z); can be negative
|
|
*
|
|
* @return a {@code FileTime} representing the given value
|
|
*/
|
|
public static FileTime fromMillis(long value) {
|
|
return new FileTime(value, TimeUnit.MILLISECONDS, null);
|
|
}
|
|
|
|
/**
|
|
* Returns a {@code FileTime} representing the same point of time value
|
|
* on the time-line as the provided {@code Instant} object.
|
|
*
|
|
* @param instant
|
|
* the instant to convert
|
|
* @return a {@code FileTime} representing the same point on the time-line
|
|
* as the provided instant
|
|
* @since 1.8
|
|
*/
|
|
public static FileTime from(Instant instant) {
|
|
Objects.requireNonNull(instant, "instant");
|
|
return new FileTime(0, null, instant);
|
|
}
|
|
|
|
/**
|
|
* Returns the value at the given unit of granularity.
|
|
*
|
|
* <p> Conversion from a coarser granularity that would numerically overflow
|
|
* saturate to {@code Long.MIN_VALUE} if negative or {@code Long.MAX_VALUE}
|
|
* if positive.
|
|
*
|
|
* @param unit
|
|
* the unit of granularity for the return value
|
|
*
|
|
* @return value in the given unit of granularity, since the epoch
|
|
* since the epoch (1970-01-01T00:00:00Z); can be negative
|
|
*/
|
|
public long to(TimeUnit unit) {
|
|
Objects.requireNonNull(unit, "unit");
|
|
if (this.unit != null) {
|
|
return unit.convert(this.value, this.unit);
|
|
} else {
|
|
long secs = unit.convert(instant.getEpochSecond(), TimeUnit.SECONDS);
|
|
if (secs == Long.MIN_VALUE || secs == Long.MAX_VALUE) {
|
|
return secs;
|
|
}
|
|
long nanos = unit.convert(instant.getNano(), TimeUnit.NANOSECONDS);
|
|
long r = secs + nanos;
|
|
// Math.addExact() variant
|
|
if (((secs ^ r) & (nanos ^ r)) < 0) {
|
|
return (secs < 0) ? Long.MIN_VALUE : Long.MAX_VALUE;
|
|
}
|
|
return r;
|
|
}
|
|
}
|
|
|
|
/**
|
|
* Returns the value in milliseconds.
|
|
*
|
|
* <p> Conversion from a coarser granularity that would numerically overflow
|
|
* saturate to {@code Long.MIN_VALUE} if negative or {@code Long.MAX_VALUE}
|
|
* if positive.
|
|
*
|
|
* @return the value in milliseconds, since the epoch (1970-01-01T00:00:00Z)
|
|
*/
|
|
public long toMillis() {
|
|
if (unit != null) {
|
|
return unit.toMillis(value);
|
|
} else {
|
|
long secs = instant.getEpochSecond();
|
|
int nanos = instant.getNano();
|
|
// Math.multiplyExact() variant
|
|
long r = secs * 1000;
|
|
long ax = Math.abs(secs);
|
|
if (((ax | 1000) >>> 31 != 0)) {
|
|
if ((r / 1000) != secs) {
|
|
return (secs < 0) ? Long.MIN_VALUE : Long.MAX_VALUE;
|
|
}
|
|
}
|
|
return r + nanos / 1000_000;
|
|
}
|
|
}
|
|
|
|
/**
|
|
* Time unit constants for conversion.
|
|
*/
|
|
private static final long HOURS_PER_DAY = 24L;
|
|
private static final long MINUTES_PER_HOUR = 60L;
|
|
private static final long SECONDS_PER_MINUTE = 60L;
|
|
private static final long SECONDS_PER_HOUR = SECONDS_PER_MINUTE * MINUTES_PER_HOUR;
|
|
private static final long SECONDS_PER_DAY = SECONDS_PER_HOUR * HOURS_PER_DAY;
|
|
private static final long MILLIS_PER_SECOND = 1000L;
|
|
private static final long MICROS_PER_SECOND = 1000_000L;
|
|
private static final long NANOS_PER_SECOND = 1000_000_000L;
|
|
private static final int NANOS_PER_MILLI = 1000_000;
|
|
private static final int NANOS_PER_MICRO = 1000;
|
|
// The epoch second of Instant.MIN.
|
|
private static final long MIN_SECOND = -31557014167219200L;
|
|
// The epoch second of Instant.MAX.
|
|
private static final long MAX_SECOND = 31556889864403199L;
|
|
|
|
/*
|
|
* Scale d by m, checking for overflow.
|
|
*/
|
|
private static long scale(long d, long m, long over) {
|
|
if (d > over) return Long.MAX_VALUE;
|
|
if (d < -over) return Long.MIN_VALUE;
|
|
return d * m;
|
|
}
|
|
|
|
/**
|
|
* Converts this {@code FileTime} object to an {@code Instant}.
|
|
*
|
|
* <p> The conversion creates an {@code Instant} that represents the
|
|
* same point on the time-line as this {@code FileTime}.
|
|
*
|
|
* <p> {@code FileTime} can store points on the time-line further in the
|
|
* future and further in the past than {@code Instant}. Conversion
|
|
* from such further time points saturates to {@link Instant#MIN} if
|
|
* earlier than {@code Instant.MIN} or {@link Instant#MAX} if later
|
|
* than {@code Instant.MAX}.
|
|
*
|
|
* @return an instant representing the same point on the time-line as
|
|
* this {@code FileTime} object
|
|
* @since 1.8
|
|
*/
|
|
public Instant toInstant() {
|
|
if (instant == null) {
|
|
long secs = 0L;
|
|
int nanos = 0;
|
|
switch (unit) {
|
|
case DAYS:
|
|
secs = scale(value, SECONDS_PER_DAY,
|
|
Long.MAX_VALUE/SECONDS_PER_DAY);
|
|
break;
|
|
case HOURS:
|
|
secs = scale(value, SECONDS_PER_HOUR,
|
|
Long.MAX_VALUE/SECONDS_PER_HOUR);
|
|
break;
|
|
case MINUTES:
|
|
secs = scale(value, SECONDS_PER_MINUTE,
|
|
Long.MAX_VALUE/SECONDS_PER_MINUTE);
|
|
break;
|
|
case SECONDS:
|
|
secs = value;
|
|
break;
|
|
case MILLISECONDS:
|
|
secs = Math.floorDiv(value, MILLIS_PER_SECOND);
|
|
nanos = (int)Math.floorMod(value, MILLIS_PER_SECOND)
|
|
* NANOS_PER_MILLI;
|
|
break;
|
|
case MICROSECONDS:
|
|
secs = Math.floorDiv(value, MICROS_PER_SECOND);
|
|
nanos = (int)Math.floorMod(value, MICROS_PER_SECOND)
|
|
* NANOS_PER_MICRO;
|
|
break;
|
|
case NANOSECONDS:
|
|
secs = Math.floorDiv(value, NANOS_PER_SECOND);
|
|
nanos = (int)Math.floorMod(value, NANOS_PER_SECOND);
|
|
break;
|
|
default : throw new AssertionError("Unit not handled");
|
|
}
|
|
if (secs <= MIN_SECOND)
|
|
instant = Instant.MIN;
|
|
else if (secs >= MAX_SECOND)
|
|
instant = Instant.MAX;
|
|
else
|
|
instant = Instant.ofEpochSecond(secs, nanos);
|
|
}
|
|
return instant;
|
|
}
|
|
|
|
/**
|
|
* Tests this {@code FileTime} for equality with the given object.
|
|
*
|
|
* <p> The result is {@code true} if and only if the argument is not {@code
|
|
* null} and is a {@code FileTime} that represents the same time. This
|
|
* method satisfies the general contract of the {@code Object.equals} method.
|
|
*
|
|
* @param obj
|
|
* the object to compare with
|
|
*
|
|
* @return {@code true} if, and only if, the given object is a {@code
|
|
* FileTime} that represents the same time
|
|
*/
|
|
@Override
|
|
public boolean equals(Object obj) {
|
|
return (obj instanceof FileTime) ? compareTo((FileTime)obj) == 0 : false;
|
|
}
|
|
|
|
/**
|
|
* Computes a hash code for this file time.
|
|
*
|
|
* <p> The hash code is based upon the value represented, and satisfies the
|
|
* general contract of the {@link Object#hashCode} method.
|
|
*
|
|
* @return the hash-code value
|
|
*/
|
|
@Override
|
|
public int hashCode() {
|
|
// hashcode of instant representation to satisfy contract with equals
|
|
return toInstant().hashCode();
|
|
}
|
|
|
|
private long toDays() {
|
|
if (unit != null) {
|
|
return unit.toDays(value);
|
|
} else {
|
|
return TimeUnit.SECONDS.toDays(toInstant().getEpochSecond());
|
|
}
|
|
}
|
|
|
|
private long toExcessNanos(long days) {
|
|
if (unit != null) {
|
|
return unit.toNanos(value - unit.convert(days, TimeUnit.DAYS));
|
|
} else {
|
|
return TimeUnit.SECONDS.toNanos(toInstant().getEpochSecond()
|
|
- TimeUnit.DAYS.toSeconds(days));
|
|
}
|
|
}
|
|
|
|
/**
|
|
* Compares the value of two {@code FileTime} objects for order.
|
|
*
|
|
* @param other
|
|
* the other {@code FileTime} to be compared
|
|
*
|
|
* @return {@code 0} if this {@code FileTime} is equal to {@code other}, a
|
|
* value less than 0 if this {@code FileTime} represents a time
|
|
* that is before {@code other}, and a value greater than 0 if this
|
|
* {@code FileTime} represents a time that is after {@code other}
|
|
*/
|
|
@Override
|
|
public int compareTo(FileTime other) {
|
|
// same granularity
|
|
if (unit != null && unit == other.unit) {
|
|
return Long.compare(value, other.value);
|
|
} else {
|
|
// compare using instant representation when unit differs
|
|
long secs = toInstant().getEpochSecond();
|
|
long secsOther = other.toInstant().getEpochSecond();
|
|
int cmp = Long.compare(secs, secsOther);
|
|
if (cmp != 0) {
|
|
return cmp;
|
|
}
|
|
cmp = Long.compare(toInstant().getNano(), other.toInstant().getNano());
|
|
if (cmp != 0) {
|
|
return cmp;
|
|
}
|
|
if (secs != MAX_SECOND && secs != MIN_SECOND) {
|
|
return 0;
|
|
}
|
|
// if both this and other's Instant reps are MIN/MAX,
|
|
// use daysSinceEpoch and nanosOfDays, which will not
|
|
// saturate during calculation.
|
|
long days = toDays();
|
|
long daysOther = other.toDays();
|
|
if (days == daysOther) {
|
|
return Long.compare(toExcessNanos(days), other.toExcessNanos(daysOther));
|
|
}
|
|
return Long.compare(days, daysOther);
|
|
}
|
|
}
|
|
|
|
// days in a 400 year cycle = 146097
|
|
// days in a 10,000 year cycle = 146097 * 25
|
|
// seconds per day = 86400
|
|
private static final long DAYS_PER_10000_YEARS = 146097L * 25L;
|
|
private static final long SECONDS_PER_10000_YEARS = 146097L * 25L * 86400L;
|
|
private static final long SECONDS_0000_TO_1970 = ((146097L * 5L) - (30L * 365L + 7L)) * 86400L;
|
|
|
|
// append year/month/day/hour/minute/second/nano with width and 0 padding
|
|
private StringBuilder append(StringBuilder sb, int w, int d) {
|
|
while (w > 0) {
|
|
sb.append((char)(d/w + '0'));
|
|
d = d % w;
|
|
w /= 10;
|
|
}
|
|
return sb;
|
|
}
|
|
|
|
/**
|
|
* Returns the string representation of this {@code FileTime}. The string
|
|
* is returned in the <a
|
|
* href="http://www.w3.org/TR/NOTE-datetime">ISO 8601</a> format:
|
|
* <pre>
|
|
* YYYY-MM-DDThh:mm:ss[.s+]Z
|
|
* </pre>
|
|
* where "{@code [.s+]}" represents a dot followed by one of more digits
|
|
* for the decimal fraction of a second. It is only present when the decimal
|
|
* fraction of a second is not zero. For example, {@code
|
|
* FileTime.fromMillis(1234567890000L).toString()} yields {@code
|
|
* "2009-02-13T23:31:30Z"}, and {@code FileTime.fromMillis(1234567890123L).toString()}
|
|
* yields {@code "2009-02-13T23:31:30.123Z"}.
|
|
*
|
|
* <p> A {@code FileTime} is primarily intended to represent the value of a
|
|
* file's time stamp. Where used to represent <i>extreme values</i>, where
|
|
* the year is less than "{@code 0001}" or greater than "{@code 9999}" then
|
|
* this method deviates from ISO 8601 in the same manner as the
|
|
* <a href="http://www.w3.org/TR/xmlschema-2/#deviantformats">XML Schema
|
|
* language</a>. That is, the year may be expanded to more than four digits
|
|
* and may be negative-signed. If more than four digits then leading zeros
|
|
* are not present. The year before "{@code 0001}" is "{@code -0001}".
|
|
*
|
|
* @return the string representation of this file time
|
|
*/
|
|
@Override
|
|
public String toString() {
|
|
if (valueAsString == null) {
|
|
long secs = 0L;
|
|
int nanos = 0;
|
|
if (instant == null && unit.compareTo(TimeUnit.SECONDS) >= 0) {
|
|
secs = unit.toSeconds(value);
|
|
} else {
|
|
secs = toInstant().getEpochSecond();
|
|
nanos = toInstant().getNano();
|
|
}
|
|
LocalDateTime ldt;
|
|
int year = 0;
|
|
if (secs >= -SECONDS_0000_TO_1970) {
|
|
// current era
|
|
long zeroSecs = secs - SECONDS_PER_10000_YEARS + SECONDS_0000_TO_1970;
|
|
long hi = Math.floorDiv(zeroSecs, SECONDS_PER_10000_YEARS) + 1;
|
|
long lo = Math.floorMod(zeroSecs, SECONDS_PER_10000_YEARS);
|
|
ldt = LocalDateTime.ofEpochSecond(lo - SECONDS_0000_TO_1970, nanos, ZoneOffset.UTC);
|
|
year = ldt.getYear() + (int)hi * 10000;
|
|
} else {
|
|
// before current era
|
|
long zeroSecs = secs + SECONDS_0000_TO_1970;
|
|
long hi = zeroSecs / SECONDS_PER_10000_YEARS;
|
|
long lo = zeroSecs % SECONDS_PER_10000_YEARS;
|
|
ldt = LocalDateTime.ofEpochSecond(lo - SECONDS_0000_TO_1970, nanos, ZoneOffset.UTC);
|
|
year = ldt.getYear() + (int)hi * 10000;
|
|
}
|
|
if (year <= 0) {
|
|
year = year - 1;
|
|
}
|
|
int fraction = ldt.getNano();
|
|
StringBuilder sb = new StringBuilder(64);
|
|
sb.append(year < 0 ? "-" : "");
|
|
year = Math.abs(year);
|
|
if (year < 10000) {
|
|
append(sb, 1000, Math.abs(year));
|
|
} else {
|
|
sb.append(String.valueOf(year));
|
|
}
|
|
sb.append('-');
|
|
append(sb, 10, ldt.getMonthValue());
|
|
sb.append('-');
|
|
append(sb, 10, ldt.getDayOfMonth());
|
|
sb.append('T');
|
|
append(sb, 10, ldt.getHour());
|
|
sb.append(':');
|
|
append(sb, 10, ldt.getMinute());
|
|
sb.append(':');
|
|
append(sb, 10, ldt.getSecond());
|
|
if (fraction != 0) {
|
|
sb.append('.');
|
|
// adding leading zeros and stripping any trailing zeros
|
|
int w = 100_000_000;
|
|
while (fraction % 10 == 0) {
|
|
fraction /= 10;
|
|
w /= 10;
|
|
}
|
|
append(sb, w, fraction);
|
|
}
|
|
sb.append('Z');
|
|
valueAsString = sb.toString();
|
|
}
|
|
return valueAsString;
|
|
}
|
|
}
|