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: }
|