1 /*
2 * Copyright 2001-2005 Stephen Colebourne
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16 package org.joda.time;
17
18 /**
19 * Defines an instant in the datetime continuum that can be queried and modified.
20 * This interface expresses the datetime as milliseconds from 1970-01-01T00:00:00Z.
21 * <p>
22 * The implementation of this interface will be mutable.
23 * It may provide more advanced methods than those in the interface.
24 *
25 * @author Stephen Colebourne
26 * @since 1.0
27 */
28 public interface ReadWritableInstant extends ReadableInstant {
29
30 /**
31 * Sets the value as the number of milliseconds since
32 * the epoch, 1970-01-01T00:00:00Z.
33 *
34 * @param instant the milliseconds since 1970-01-01T00:00:00Z to set the
35 * instant to
36 * @throws IllegalArgumentException if the value is invalid
37 */
38 void setMillis(long instant);
39
40 /**
41 * Sets the millisecond instant of this instant from another.
42 * <p>
43 * This method does not change the chronology of this instant, just the
44 * millisecond instant.
45 *
46 * @param instant the instant to use, null means now
47 */
48 void setMillis(ReadableInstant instant);
49
50 /**
51 * Sets the chronology of the datetime, which has no effect if not applicable.
52 *
53 * @param chronology the chronology to use, null means ISOChronology in default zone
54 * @throws IllegalArgumentException if the value is invalid
55 */
56 void setChronology(Chronology chronology);
57
58 /**
59 * Sets the time zone of the datetime, changing the chronology and field values.
60 * <p>
61 * Changing the zone using this method retains the millisecond instant.
62 * The millisecond instant is adjusted in the new zone to compensate.
63 *
64 * chronology. Setting the time zone does not affect the millisecond value
65 * of this instant.
66 * <p>
67 * If the chronology already has this time zone, no change occurs.
68 *
69 * @param zone the time zone to use, null means default zone
70 * @see #setZoneRetainFields
71 */
72 void setZone(DateTimeZone zone);
73
74 /**
75 * Sets the time zone of the datetime, changing the chronology and millisecond.
76 * <p>
77 * Changing the zone using this method retains the field values.
78 * The millisecond instant is adjusted in the new zone to compensate.
79 * <p>
80 * If the chronology already has this time zone, no change occurs.
81 *
82 * @param zone the time zone to use, null means default zone
83 * @see #setZone
84 */
85 void setZoneRetainFields(DateTimeZone zone);
86
87 //-----------------------------------------------------------------------
88 /**
89 * Adds a millisecond duration to this instant.
90 * <p>
91 * This will typically change the value of ost fields.
92 *
93 * @param duration the millis to add
94 * @throws IllegalArgumentException if the value is invalid
95 */
96 void add(long duration);
97
98 /**
99 * 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 }