* A {@code SimplePeriod} represents an amount of time measured in terms of a * single {@link TemporalUnit unit}. Any unit may be used with this class. * An alternative period implementation is {@link java.time.Period Period}, which * allows a combination of date and time units. *
* This class is the return type from {@link TemporalUnit#between}. * It can be used more generally, but is designed to enable the following code: *
* date = date.minus(MONTHS.between(start, end)); ** The unit determines which calendar systems it can be added to. *
* The period is modeled as a directed amount of time, meaning that the period may * be negative. See {@link #abs()} to ensure the period is positive. * *
* The parameters represent the two parts of a phrase like '6 Days'. For example: *
* SimplePeriod.of(3, SECONDS);
* SimplePeriod.of(5, YEARS);
*
*
* @param amount the amount of the period, measured in terms of the unit, positive or negative
* @param unit the unit that the period is measured in, not null
* @return the period, not null
*/
public static SimplePeriod of(long amount, TemporalUnit unit) {
Objects.requireNonNull(unit, "unit");
return new SimplePeriod(amount, unit);
}
//-----------------------------------------------------------------------
/**
* Constructor.
*
* @param amount the amount of the period, measured in terms of the unit, positive or negative
* @param unit the unit that the period is measured in, not null
*/
SimplePeriod(long amount, TemporalUnit unit) {
this.amount = amount;
this.unit = unit;
}
//-----------------------------------------------------------------------
/**
* Gets the amount of this period.
* * In the phrase "2 Months", the amount is 2. * * @return the amount of the period, may be negative */ public long getAmount() { return amount; } /** * Gets the unit of this period. *
* In the phrase "2 Months", the unit is "Months". * * @return the unit of the period, not null */ public TemporalUnit getUnit() { return unit; } //------------------------------------------------------------------------- /** * Adds this period to the specified temporal object. *
* This returns a temporal object of the same observable type as the input * with this period added. *
* In most cases, it is clearer to reverse the calling pattern by using * {@link Temporal#plus(TemporalAdder)}. *
* // these two lines are equivalent, but the second approach is recommended
* dateTime = thisPeriod.addTo(dateTime);
* dateTime = dateTime.plus(thisPeriod);
*
* * The calculation is equivalent to invoking {@link Temporal#plus(long, TemporalUnit)}. *
* This instance is immutable and unaffected by this method call. * * @param temporal the temporal object to adjust, not null * @return an object of the same type with the adjustment made, not null * @throws DateTimeException if unable to add * @throws ArithmeticException if numeric overflow occurs */ @Override public Temporal addTo(Temporal temporal) { return temporal.plus(amount, unit); } /** * Subtracts this period to the specified temporal object. *
* This returns a temporal object of the same observable type as the input * with this period subtracted. *
* In most cases, it is clearer to reverse the calling pattern by using * {@link Temporal#plus(TemporalAdder)}. *
* // these two lines are equivalent, but the second approach is recommended
* dateTime = thisPeriod.subtractFrom(dateTime);
* dateTime = dateTime.minus(thisPeriod);
*
* * The calculation is equivalent to invoking {@link Temporal#minus(long, TemporalUnit)}. *
* This instance is immutable and unaffected by this method call. * * @param temporal the temporal object to adjust, not null * @return an object of the same type with the adjustment made, not null * @throws DateTimeException if unable to subtract * @throws ArithmeticException if numeric overflow occurs */ @Override public Temporal subtractFrom(Temporal temporal) { return temporal.minus(amount, unit); } //----------------------------------------------------------------------- /** * Returns a copy of this period with a positive amount. *
* This returns a period with the absolute value of the amount and the same unit. * If the amount of this period is positive or zero, then this period is returned. * If the amount of this period is negative, then a period with the negated * amount is returned. If the amount equals {@code Long.MIN_VALUE}, * an {@code ArithmeticException} is thrown *
* This is useful to convert the result of {@link TemporalUnit#between} to * a positive amount when you do not know which date is the earlier and * which is the later. * * @return a period with a positive amount and the same unit, not null * @throws ArithmeticException if the amount is {@code Long.MIN_VALUE} */ public SimplePeriod abs() { if (amount == Long.MIN_VALUE) { throw new ArithmeticException("Unable to call abs() on MIN_VALUE"); } return (amount >= 0 ? this : new SimplePeriod(-amount, unit)); } //----------------------------------------------------------------------- /** * Compares this {@code SimplePeriod} to another period. *
* The comparison is based on the amount within the unit. * Only two periods with the same unit can be compared. * * @param other the other period to compare to, not null * @return the comparator value, negative if less, positive if greater * @throws IllegalArgumentException if the units do not match */ @Override public int compareTo(SimplePeriod other) { if (unit.equals(other.unit) == false) { throw new IllegalArgumentException("Unable to compare periods with different units"); } return Long.compare(amount, other.amount); } //----------------------------------------------------------------------- /** * Checks if this period is equal to another period. *
* The comparison is based on the amount and unit. * * @param obj the object to check, null returns false * @return true if this is equal to the other period */ @Override public boolean equals(Object obj) { if (this == obj) { return true; } if (obj instanceof SimplePeriod) { SimplePeriod other = (SimplePeriod) obj; return amount == other.amount && unit.equals(other.unit); } return false; } /** * A hash code for this period. * * @return a suitable hash code */ @Override public int hashCode() { return unit.hashCode() ^ (int) (amount ^ (amount >>> 32)); } //----------------------------------------------------------------------- /** * Outputs this period as a {@code String}, such as {@code 2 Months}. *
* The string consists of the amount, then a space, then the unit name. * * @return a string representation of this period, not null */ @Override public String toString() { return amount + " " + unit.getName(); } //----------------------------------------------------------------------- /** * Writes the object using a * dedicated serialized form. *
* out.writeByte(10); // identifies this as a SimplePeriod
* out.writeLong(amount);
* out.writeObject(unit);
*
*
* @return the instance of {@code Ser}, not null
*/
private Object writeReplace() {
return new Ser(Ser.SIMPLE_PERIOD_TYPE, this);
}
/**
* Defend against malicious streams.
* @return never
* @throws InvalidObjectException always
*/
private Object readResolve() throws ObjectStreamException {
throw new InvalidObjectException("Deserialization via serialization delegate");
}
void writeExternal(ObjectOutput out) throws IOException {
out.writeLong(amount);
out.writeObject(unit);
}
static SimplePeriod readExternal(ObjectInput in) throws IOException, ClassNotFoundException {
long amount = in.readLong();
TemporalUnit unit = (TemporalUnit) in.readObject();
return SimplePeriod.of(amount, unit);
}
}