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 */
016 package 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 */
028 public 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 }