1 /* 2 * Copyright (c) 2007-present, Stephen Colebourne & Michael Nascimento Santos 3 * 4 * All rights reserved. 5 * 6 * Redistribution and use in source and binary forms, with or without 7 * modification, are permitted provided that the following conditions are met: 8 * 9 * * Redistributions of source code must retain the above copyright notice, 10 * this list of conditions and the following disclaimer. 11 * 12 * * Redistributions in binary form must reproduce the above copyright notice, 13 * this list of conditions and the following disclaimer in the documentation 14 * and/or other materials provided with the distribution. 15 * 16 * * Neither the name of JSR-310 nor the names of its contributors 17 * may be used to endorse or promote products derived from this software 18 * without specific prior written permission. 19 * 20 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 21 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 22 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 23 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR 24 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 25 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, 26 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR 27 * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF 28 * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING 29 * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS 30 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 31 */ 32 package org.threeten.bp.temporal; 33 34 import org.threeten.bp.DateTimeException; 35 36 /** 37 * Strategy for adjusting a temporal object. 38 * <p> 39 * Adjusters are a key tool for modifying temporal objects. 40 * They exist to externalize the process of adjustment, permitting different 41 * approaches, as per the strategy design pattern. 42 * Examples might be an adjuster that sets the date avoiding weekends, or one that 43 * sets the date to the last day of the month. 44 * <p> 45 * There are two equivalent ways of using a {@code TemporalAdjuster}. 46 * The first is to invoke the method on this interface directly. 47 * The second is to use {@link Temporal#with(TemporalAdjuster)}: 48 * <pre> 49 * // these two lines are equivalent, but the second approach is recommended 50 * temporal = thisAdjuster.adjustInto(temporal); 51 * temporal = temporal.with(thisAdjuster); 52 * </pre> 53 * It is recommended to use the second approach, {@code with(TemporalAdjuster)}, 54 * as it is a lot clearer to read in code. 55 * <p> 56 * See {@link TemporalAdjusters} for a standard set of adjusters, including finding the 57 * last day of the month. 58 * Adjusters may also be defined by applications. 59 * 60 * <h3>Specification for implementors</h3> 61 * This interface places no restrictions on the mutability of implementations, 62 * however immutability is strongly recommended. 63 */ 64 public interface TemporalAdjuster { 65 66 /** 67 * Adjusts the specified temporal object. 68 * <p> 69 * This adjusts the specified temporal object using the logic 70 * encapsulated in the implementing class. 71 * Examples might be an adjuster that sets the date avoiding weekends, or one that 72 * sets the date to the last day of the month. 73 * <p> 74 * There are two equivalent ways of using this method. 75 * The first is to invoke this method directly. 76 * The second is to use {@link Temporal#with(TemporalAdjuster)}: 77 * <pre> 78 * // these two lines are equivalent, but the second approach is recommended 79 * temporal = thisAdjuster.adjustInto(temporal); 80 * temporal = temporal.with(thisAdjuster); 81 * </pre> 82 * It is recommended to use the second approach, {@code with(TemporalAdjuster)}, 83 * as it is a lot clearer to read in code. 84 * 85 * <h3>Specification for implementors</h3> 86 * The implementation must take the input object and adjust it. 87 * The implementation defines the logic of the adjustment and is responsible for 88 * documenting that logic. It may use any method on {@code Temporal} to 89 * query the temporal object and perform the adjustment. 90 * The returned object must have the same observable type as the input object 91 * <p> 92 * The input object must not be altered. 93 * Instead, an adjusted copy of the original must be returned. 94 * This provides equivalent, safe behavior for immutable and mutable temporal objects. 95 * <p> 96 * The input temporal object may be in a calendar system other than ISO. 97 * Implementations may choose to document compatibility with other calendar systems, 98 * or reject non-ISO temporal objects by {@link TemporalQueries#chronology() querying the chronology}. 99 * <p> 100 * This method may be called from multiple threads in parallel. 101 * It must be thread-safe when invoked. 102 * 103 * @param temporal the temporal object to adjust, not null 104 * @return an object of the same observable type with the adjustment made, not null 105 * @throws DateTimeException if unable to make the adjustment 106 * @throws ArithmeticException if numeric overflow occurs 107 */ adjustInto(Temporal temporal)108 Temporal adjustInto(Temporal temporal); 109 110 } 111