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}