001/* 002 * Shredzone Commons - suncalc 003 * 004 * Copyright (C) 2017 Richard "Shred" Körber 005 * http://commons.shredzone.org 006 * 007 * Licensed under the Apache License, Version 2.0 (the "License"); 008 * you may not use this file except in compliance with the License. 009 * 010 * This program is distributed in the hope that it will be useful, 011 * but WITHOUT ANY WARRANTY; without even the implied warranty of 012 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. 013 */ 014package org.shredzone.commons.suncalc.param; 015 016import java.util.Calendar; 017import java.util.Date; 018import java.util.TimeZone; 019 020/** 021 * Time based parameters. 022 * <p> 023 * Use them to give information about the desired time. If ommitted, the current time and 024 * the system's time zone is used. 025 * 026 * @param <T> 027 * Type of the final builder 028 */ 029public interface TimeParameter<T> { 030 031 /** 032 * Sets midnight of the year, month and date. Uses the system's time zone unless a 033 * different time zone is given. 034 * 035 * @param year 036 * Year 037 * @param month 038 * Month (1 = January, 2 = February, ...) 039 * @param date 040 * Day of month 041 * @return itself 042 */ 043 T on(int year, int month, int date); 044 045 /** 046 * Sets date and time. Note that also seconds can be passed in for convenience, but 047 * the results are not that accurate. Uses the system's time zone unless a different 048 * time zone is given. 049 * 050 * @param year 051 * Year 052 * @param month 053 * Month (1 = January, 2 = February, ...) 054 * @param date 055 * Day of month 056 * @param hour 057 * Hour of day 058 * @param minute 059 * Minute 060 * @param second 061 * Second 062 * @return itself 063 */ 064 T on(int year, int month, int date, int hour, int minute, int second); 065 066 /** 067 * Uses the given {@link Calendar} instance. 068 * 069 * @param cal 070 * {@link Calendar}. A copy of the date, time, and time zone is used. The 071 * {@link Calendar} instance may be reused after that. 072 * @return itself 073 */ 074 T on(Calendar cal); 075 076 /** 077 * Uses the given {@link Date} instance. Uses the system's time zone unless a 078 * different time zone is given. 079 * 080 * @param date 081 * {@link Date}. A copy of the date is used. The {@link Date} instance may 082 * be reused after that. 083 * @return itself 084 */ 085 T on(Date date); 086 087 /** 088 * Adds a number of days to the current date. 089 * 090 * @param days 091 * Number of days to add 092 * @return itself 093 * @since 2.2 094 */ 095 T plusDays(int days); 096 097 /** 098 * Sets today, midnight. 099 * <p> 100 * It is the same as <code>now().midnight()</code>. 101 * 102 * @return itself 103 */ 104 T today(); 105 106 /** 107 * Sets tomorrow, midnight. 108 * <p> 109 * It is the same as <code>now().midnight().plusDays(1)</code>. 110 * 111 * @return itself 112 * @since 2.2 113 */ 114 T tomorrow(); 115 116 /** 117 * Sets the current date and time. This is the default. 118 * 119 * @return itself 120 */ 121 T now(); 122 123 /** 124 * Sets the time to the start of the current date ("last midnight"). 125 * 126 * @return itself 127 */ 128 T midnight(); 129 130 /** 131 * Sets the given {@link TimeZone}. 132 * 133 * @param tz 134 * {@link TimeZone} to be used. 135 * @return itself 136 */ 137 T timezone(TimeZone tz); 138 139 /** 140 * Sets the given {@link TimeZone}. This is a convenience method that just invokes 141 * {@link TimeZone#getTimeZone(String)}. 142 * 143 * @param id 144 * ID of the time zone. "GMT" is used if the time zone ID was not 145 * understood. 146 * @return itself 147 * @see TimeZone#getTimeZone(String) 148 */ 149 T timezone(String id); 150 151 /** 152 * Sets the system's {@link TimeZone}. This is the default. 153 * 154 * @return itself 155 */ 156 T localTime(); 157 158 /** 159 * Sets the time zone to UTC. 160 * 161 * @return itself 162 */ 163 T utc(); 164 165 /** 166 * Uses the same time as given in the {@link TimeParameter}. 167 * <p> 168 * Changes to the source parameter will not affect this parameter, though. 169 * 170 * @param t {@link TimeParameter} to be used. 171 * @return itself 172 * @since 2.8 173 */ 174 T sameTimeAs(TimeParameter<?> t); 175 176}