org.shredzone.commons.suncalc.param.TimeParameter Maven / Gradle / Ivy
Show all versions of commons-suncalc Show documentation
/*
* Shredzone Commons - suncalc
*
* Copyright (C) 2017 Richard "Shred" Körber
* http://commons.shredzone.org
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
*
* This program 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.
*/
package org.shredzone.commons.suncalc.param;
import java.time.Instant;
import java.time.LocalDate;
import java.time.LocalDateTime;
import java.time.ZoneId;
import java.time.ZonedDateTime;
import java.util.Calendar;
import java.util.Date;
import java.util.Objects;
import java.util.TimeZone;
/**
* Time based parameters.
*
* Use them to give information about the desired time. If ommitted, the current time and
* the system's time zone is used.
*
* @param
* Type of the final builder
*/
@SuppressWarnings("unchecked")
public interface TimeParameter {
/**
* Sets date and time. Note that also seconds can be passed in for convenience, but
* the results are not that accurate.
*
* @param year
* Year
* @param month
* Month (1 = January, 2 = February, ...)
* @param date
* Day of month
* @param hour
* Hour of day
* @param minute
* Minute
* @param second
* Second
* @return itself
*/
T on(int year, int month, int date, int hour, int minute, int second);
/**
* Sets midnight of the year, month and date.
*
* @param year
* Year
* @param month
* Month (1 = January, 2 = February, ...)
* @param date
* Day of month
* @return itself
*/
default T on(int year, int month, int date) {
return on(year, month, date, 0, 0, 0);
}
/**
* Uses the given {@link ZonedDateTime} instance.
*
* @param dateTime
* {@link ZonedDateTime} to be used.
* @return itself
*/
T on(ZonedDateTime dateTime);
/**
* Uses the given {@link LocalDateTime} instance.
*
* @param dateTime
* {@link LocalDateTime} to be used.
* @return itself
*/
T on(LocalDateTime dateTime);
/**
* Uses the given {@link LocalDate} instance, and assumes midnight.
*
* @param date
* {@link LocalDate} to be used.
* @return itself
*/
T on(LocalDate date);
/**
* Uses the given {@link Instant} instance.
*
* @param instant
* {@link Instant} to be used.
* @return itself
*/
T on(Instant instant);
/**
* Uses the given {@link Date} instance.
*
* @param date
* {@link Date} to be used.
* @return itself
*/
default T on(Date date) {
Objects.requireNonNull(date, "date");
return on(date.toInstant());
}
/**
* Uses the given {@link Calendar} instance.
*
* @param cal
* {@link Calendar} to be used
* @return itself
*/
default T on(Calendar cal) {
Objects.requireNonNull(cal, "cal");
return on(ZonedDateTime.ofInstant(cal.toInstant(), cal.getTimeZone().toZoneId()));
}
/**
* Sets the current date and time. This is the default.
*
* @return itself
*/
T now();
/**
* Sets the time to the start of the current date ("last midnight").
*
* @return itself
*/
T midnight();
/**
* Adds a number of days to the current date.
*
* @param days
* Number of days to add
* @return itself
*/
T plusDays(int days);
/**
* Sets today, midnight.
*
* It is the same as now().midnight().
*
* @return itself
*/
default T today() {
now();
midnight();
return (T) this;
}
/**
* Sets tomorrow, midnight.
*
* It is the same as now().midnight().plusDays(1).
*
* @return itself
*/
default T tomorrow() {
today();
plusDays(1);
return (T) this;
}
/**
* Sets the given {@link ZoneId}. The local time is retained, so the parameter order
* is not important.
*
* @param tz
* {@link ZoneId} to be used.
* @return itself
*/
T timezone(ZoneId tz);
/**
* Sets the given timezone. This is a convenience method that just invokes
* {@link ZoneId#of(String)}.
*
* @param id
* ID of the time zone.
* @return itself
* @see ZoneId#of(String)
*/
default T timezone(String id) {
return timezone(ZoneId.of(id));
}
/**
* Sets the system's timezone. This is the default.
*
* @return itself
*/
default T localTime() {
return timezone(ZoneId.systemDefault());
}
/**
* Sets the time zone to UTC.
*
* @return itself
*/
default T utc() {
return timezone("UTC");
}
/**
* Sets the {@link TimeZone}.
*
* @param tz {@link TimeZone} to be used
* @return itself
*/
default T timezone(TimeZone tz) {
Objects.requireNonNull(tz, "tz");
return timezone(tz.toZoneId());
}
/**
* Uses the same time as given in the {@link TimeParameter}.
*
* Changes to the source parameter will not affect this parameter, though.
*
* @param t {@link TimeParameter} to be used.
* @return itself
*/
T sameTimeAs(TimeParameter t);
}