001/*
002 *  Copyright 2001-2005 Stephen Colebourne
003 *
004 *  Licensed under the Apache License, Version 2.0 (the "License");
005 *  you may not use this file except in compliance with the License.
006 *  You may obtain a copy of the License at
007 *
008 *      http://www.apache.org/licenses/LICENSE-2.0
009 *
010 *  Unless required by applicable law or agreed to in writing, software
011 *  distributed under the License is distributed on an "AS IS" BASIS,
012 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 *  See the License for the specific language governing permissions and
014 *  limitations under the License.
015 */
016package org.joda.time;
017
018/**
019 * Defines an instant in the datetime continuum that can be queried and modified.
020 * This interface expresses the datetime as milliseconds from 1970-01-01T00:00:00Z.
021 * <p>
022 * The implementation of this interface will be mutable.
023 * It may provide more advanced methods than those in the interface.
024 *
025 * @author Stephen Colebourne
026 * @since 1.0
027 */
028public interface ReadWritableInstant extends ReadableInstant {
029
030    /**
031     * Sets the value as the number of milliseconds since
032     * the epoch, 1970-01-01T00:00:00Z.
033     * 
034     * @param instant  the milliseconds since 1970-01-01T00:00:00Z to set the
035     * instant to
036     * @throws IllegalArgumentException if the value is invalid
037     */
038    void setMillis(long instant);
039
040    /**
041     * Sets the millisecond instant of this instant from another.
042     * <p>
043     * This method does not change the chronology of this instant, just the
044     * millisecond instant.
045     * 
046     * @param instant  the instant to use, null means now
047     */
048    void setMillis(ReadableInstant instant);
049
050    /**
051     * Sets the chronology of the datetime, which has no effect if not applicable.
052     * 
053     * @param chronology  the chronology to use, null means ISOChronology in default zone
054     * @throws IllegalArgumentException if the value is invalid
055     */
056    void setChronology(Chronology chronology);
057
058    /**
059     * Sets the time zone of the datetime, changing the chronology and field values.
060     * <p>
061     * Changing the zone using this method retains the millisecond instant.
062     * The millisecond instant is adjusted in the new zone to compensate.
063     * 
064     * chronology. Setting the time zone does not affect the millisecond value
065     * of this instant.
066     * <p>
067     * If the chronology already has this time zone, no change occurs.
068     *
069     * @param zone  the time zone to use, null means default zone
070     * @see #setZoneRetainFields
071     */
072    void setZone(DateTimeZone zone);
073
074    /**
075     * Sets the time zone of the datetime, changing the chronology and millisecond.
076     * <p>
077     * Changing the zone using this method retains the field values.
078     * The millisecond instant is adjusted in the new zone to compensate.
079     * <p>
080     * If the chronology already has this time zone, no change occurs.
081     *
082     * @param zone  the time zone to use, null means default zone
083     * @see #setZone
084     */
085    void setZoneRetainFields(DateTimeZone zone);
086
087    //-----------------------------------------------------------------------
088    /**
089     * Adds a millisecond duration to this instant.
090     * <p>
091     * This will typically change the value of ost fields.
092     *
093     * @param duration  the millis to add
094     * @throws IllegalArgumentException if the value is invalid
095     */
096    void add(long duration);
097
098    /**
099     * Adds a duration to this instant.
100     * <p>
101     * This will typically change the value of most fields.
102     *
103     * @param duration  the duration to add, null means add zero
104     * @throws ArithmeticException if the result exceeds the capacity of the instant
105     */
106    void add(ReadableDuration duration);
107
108    /**
109     * Adds a duration to this instant specifying how many times to add.
110     * <p>
111     * This will typically change the value of most fields.
112     *
113     * @param duration  the duration to add, null means add zero
114     * @param scalar  direction and amount to add, which may be negative
115     * @throws ArithmeticException if the result exceeds the capacity of the instant
116     */
117    void add(ReadableDuration duration, int scalar);
118
119    /**
120     * Adds a period to this instant.
121     * <p>
122     * This will typically change the value of most fields.
123     *
124     * @param period  the period to add, null means add zero
125     * @throws ArithmeticException if the result exceeds the capacity of the instant
126     */
127    void add(ReadablePeriod period);
128
129    /**
130     * Adds a period to this instant specifying how many times to add.
131     * <p>
132     * This will typically change the value of most fields.
133     *
134     * @param period  the period to add, null means add zero
135     * @param scalar  direction and amount to add, which may be negative
136     * @throws ArithmeticException if the result exceeds the capacity of the instant
137     */
138    void add(ReadablePeriod period, int scalar);
139
140    //-----------------------------------------------------------------------
141    /**
142     * Sets the value of one of the fields of the instant, such as hourOfDay.
143     *
144     * @param type  a field type, usually obtained from DateTimeFieldType, null ignored
145     * @param value  the value to set the field to
146     * @throws IllegalArgumentException if the value is invalid
147     */
148    void set(DateTimeFieldType type, int value);
149
150    /**
151     * Adds to the instant specifying the duration and multiple to add.
152     *
153     * @param type  a field type, usually obtained from DateTimeFieldType, null ignored
154     * @param amount  the amount to add of this duration
155     * @throws ArithmeticException if the result exceeds the capacity of the instant
156     */
157    void add(DurationFieldType type, int amount);
158
159}