001/*
002 * Shredzone Commons - suncalc
003 *
004 * Copyright (C) 2024 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.time.Duration;
017
018/**
019 * Time window based parameters.
020 * <p>
021 * Use them to give information about the desired time window. If ommitted, a forward
022 * window of 365 days is assumed.
023 *
024 * @since 3.11
025 * @param <T>
026 *            Type of the final builder
027 */
028public interface WindowParameter<T> {
029
030    /**
031     * Limits the calculation window to the given {@link Duration}.
032     *
033     * @param duration
034     *         Duration of the calculation window. A negative duration sets a reverse time
035     *         window, giving result times in the past.
036     * @return itself
037     */
038    T limit(Duration duration);
039
040    /**
041     * Limits the time window to the next 24 hours.
042     *
043     * @return itself
044     */
045    default T oneDay() {
046        return limit(Duration.ofDays(1L));
047    }
048
049    /**
050     * Computes until all times are found.
051     * <p>
052     * This is the default.
053     *
054     * @return itself
055     */
056    default T fullCycle() {
057        return limit(Duration.ofDays(365L));
058    }
059
060    /**
061     * Sets a reverse calculation window. It will end at the given date.
062     *
063     * @return itself
064     * @since 3.11
065     */
066    T reverse();
067
068    /**
069     * Sets a forward calculation window. It will start at the given date.
070     * <p>
071     * This is the default.
072     *
073     * @return itself
074     * @since 3.11
075     */
076    T forward();
077
078    /**
079     * Uses the same window as given in the {@link WindowParameter}.
080     * <p>
081     * Changes to the source parameter will not affect this parameter, though.
082     *
083     * @param w
084     *         {@link WindowParameter} to be used.
085     * @return itself
086     * @since 3.11
087     */
088    T sameWindowAs(WindowParameter<?> w);
089
090}