/*

* Copyright (c) 2012, 2013, Oracle and/or its affiliates. All rights reserved.

* ORACLE PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.

*

*

*

*

*

*

*

*

*

*

*

*

*

*

*

*

*

*

*

*

*/

/*

*

*

*

*

*

* Copyright (c) 2007-2012, Stephen Colebourne & Michael Nascimento Santos

*

* All rights reserved.

*

* Redistribution and use in source and binary forms, with or without

* modification, are permitted provided that the following conditions are met:

*

* * Redistributions of source code must retain the above copyright notice,

* this list of conditions and the following disclaimer.

*

* * Redistributions in binary form must reproduce the above copyright notice,

* this list of conditions and the following disclaimer in the documentation

* and/or other materials provided with the distribution.

*

* * Neither the name of JSR-310 nor the names of its contributors

* may be used to endorse or promote products derived from this software

* without specific prior written permission.

*

* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS

* "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT

* LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR

* A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR

* CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,

* EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,

* PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR

* PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF

* LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING

* NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS

* SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

*/

package java.time;

import static java.time.temporal.ChronoField.EPOCH_DAY;

import static java.time.temporal.ChronoField.INSTANT_SECONDS;

import static java.time.temporal.ChronoField.NANO_OF_DAY;

import static java.time.temporal.ChronoField.OFFSET_SECONDS;

import static java.time.temporal.ChronoUnit.FOREVER;

import static java.time.temporal.ChronoUnit.NANOS;

import java.io.IOException;

import java.io.ObjectInput;

import java.io.ObjectOutput;

import java.io.InvalidObjectException;

import java.io.ObjectInputStream;

import java.io.Serializable;

import java.time.chrono.IsoChronology;

import java.time.format.DateTimeFormatter;

import java.time.format.DateTimeParseException;

import java.time.temporal.ChronoField;

import java.time.temporal.ChronoUnit;

import java.time.temporal.Temporal;

import java.time.temporal.TemporalAccessor;

import java.time.temporal.TemporalAdjuster;

import java.time.temporal.TemporalAmount;

import java.time.temporal.TemporalField;

import java.time.temporal.TemporalQueries;

import java.time.temporal.TemporalQuery;

import java.time.temporal.TemporalUnit;

import java.time.temporal.UnsupportedTemporalTypeException;

import java.time.temporal.ValueRange;

import java.time.zone.ZoneRules;

import java.util.Comparator;

import java.util.Objects;

/**

* A date-time with an offset from UTC/Greenwich in the ISO-8601 calendar system,

* such as {@code 2007-12-03T10:15:30+01:00}.

* <p>

* {@code OffsetDateTime} is an immutable representation of a date-time with an offset.

* This class stores all date and time fields, to a precision of nanoseconds,

* as well as the offset from UTC/Greenwich. For example, the value

* "2nd October 2007 at 13:45.30.123456789 +02:00" can be stored in an {@code OffsetDateTime}.

* <p>

* {@code OffsetDateTime}, {@link java.time.ZonedDateTime} and {@link java.time.Instant} all store an instant

* on the time-line to nanosecond precision.

* {@code Instant} is the simplest, simply representing the instant.

* {@code OffsetDateTime} adds to the instant the offset from UTC/Greenwich, which allows

* the local date-time to be obtained.

* {@code ZonedDateTime} adds full time-zone rules.

* <p>

* It is intended that {@code ZonedDateTime} or {@code Instant} is used to model data

* in simpler applications. This class may be used when modeling date-time concepts in

* more detail, or when communicating to a database or in a network protocol.

*

* <p>

* This is a <a href="{@docRoot}/java/lang/doc-files/ValueBased.html">value-based</a>

* class; use of identity-sensitive operations (including reference equality

* ({@code ==}), identity hash code, or synchronization) on instances of

* {@code OffsetDateTime} may have unpredictable results and should be avoided.

* The {@code equals} method should be used for comparisons.

*

* @implSpec

* This class is immutable and thread-safe.

*

* @since 1.8

*/

public final class OffsetDateTime

implements Temporal, TemporalAdjuster, Comparable<OffsetDateTime>, Serializable {

/**

* The minimum supported {@code OffsetDateTime}, '-999999999-01-01T00:00:00+18:00'.

* This is the local date-time of midnight at the start of the minimum date

* in the maximum offset (larger offsets are earlier on the time-line).

* This combines {@link LocalDateTime#MIN} and {@link ZoneOffset#MAX}.

* This could be used by an application as a "far past" date-time.

*/

public static final OffsetDateTime MIN = LocalDateTime.MIN.atOffset(ZoneOffset.MAX);

/**

* The maximum supported {@code OffsetDateTime}, '+999999999-12-31T23:59:59.999999999-18:00'.

* This is the local date-time just before midnight at the end of the maximum date

* in the minimum offset (larger negative offsets are later on the time-line).

* This combines {@link LocalDateTime#MAX} and {@link ZoneOffset#MIN}.

* This could be used by an application as a "far future" date-time.

*/

public static final OffsetDateTime MAX = LocalDateTime.MAX.atOffset(ZoneOffset.MIN);

/**

* Gets a comparator that compares two {@code OffsetDateTime} instances

* based solely on the instant.

* <p>

* This method differs from the comparison in {@link #compareTo} in that it

* only compares the underlying instant.

*

* @return a comparator that compares in time-line order

*

* @see #isAfter

* @see #isBefore

* @see #isEqual

*/

public static Comparator<OffsetDateTime> timeLineOrder() {

return OffsetDateTime::compareInstant;

}

/**

* Compares this {@code OffsetDateTime} to another date-time.

* The comparison is based on the instant.

*

* @param datetime1 the first date-time to compare, not null

* @param datetime2 the other date-time to compare to, not null

* @return the comparator value, negative if less, positive if greater

*/

private static int compareInstant(OffsetDateTime datetime1, OffsetDateTime datetime2) {

if (datetime1.getOffset().equals(datetime2.getOffset())) {

return datetime1.toLocalDateTime().compareTo(datetime2.toLocalDateTime());

}

int cmp = Long.compare(datetime1.toEpochSecond(), datetime2.toEpochSecond());

if (cmp == 0) {

cmp = datetime1.toLocalTime().getNano() - datetime2.toLocalTime().getNano();

}

return cmp;

}

/**

* Serialization version.

*/

private static final long serialVersionUID = 2287754244819255394L;

/**

* The local date-time.

*/

private final LocalDateTime dateTime;

/**

* The offset from UTC/Greenwich.

*/

private final ZoneOffset offset;

//-----------------------------------------------------------------------

/**

* Obtains the current date-time from the system clock in the default time-zone.

* <p>

* This will query the {@link java.time.Clock#systemDefaultZone() system clock} in the default

* time-zone to obtain the current date-time.

* The offset will be calculated from the time-zone in the clock.

* <p>

* Using this method will prevent the ability to use an alternate clock for testing

* because the clock is hard-coded.

*

* @return the current date-time using the system clock, not null

*/

public static OffsetDateTime now() {

return now(Clock.systemDefaultZone());

}

/**

* Obtains the current date-time from the system clock in the specified time-zone.

* <p>

* This will query the {@link Clock#system(java.time.ZoneId) system clock} to obtain the current date-time.

* Specifying the time-zone avoids dependence on the default time-zone.

* The offset will be calculated from the specified time-zone.

* <p>

* Using this method will prevent the ability to use an alternate clock for testing

* because the clock is hard-coded.

*

* @param zone the zone ID to use, not null

* @return the current date-time using the system clock, not null

*/

public static OffsetDateTime now(ZoneId zone) {

return now(Clock.system(zone));

}

/**

* Obtains the current date-time from the specified clock.

* <p>

* This will query the specified clock to obtain the current date-time.

* The offset will be calculated from the time-zone in the clock.

* <p>

* Using this method allows the use of an alternate clock for testing.

* The alternate clock may be introduced using {@link Clock dependency injection}.

*

* @param clock the clock to use, not null

* @return the current date-time, not null

*/

public static OffsetDateTime now(Clock clock) {

Objects.requireNonNull(clock, "clock");

final Instant now = clock.instant(); // called once

return ofInstant(now, clock.getZone().getRules().getOffset(now));

}

//-----------------------------------------------------------------------

/**

* Obtains an instance of {@code OffsetDateTime} from a date, time and offset.

* <p>

* This creates an offset date-time with the specified local date, time and offset.

*

* @param date the local date, not null

* @param time the local time, not null

* @param offset the zone offset, not null

* @return the offset date-time, not null

*/

public static OffsetDateTime of(LocalDate date, LocalTime time, ZoneOffset offset) {

LocalDateTime dt = LocalDateTime.of(date, time);

return new OffsetDateTime(dt, offset);

}

/**

* Obtains an instance of {@code OffsetDateTime} from a date-time and offset.

* <p>

* This creates an offset date-time with the specified local date-time and offset.

*

* @param dateTime the local date-time, not null

* @param offset the zone offset, not null

* @return the offset date-time, not null

*/

public static OffsetDateTime of(LocalDateTime dateTime, ZoneOffset offset) {

return new OffsetDateTime(dateTime, offset);

}

/**

* Obtains an instance of {@code OffsetDateTime} from a year, month, day,

* hour, minute, second, nanosecond and offset.

* <p>

* This creates an offset date-time with the seven specified fields.

* <p>

* This method exists primarily for writing test cases.

* Non test-code will typically use other methods to create an offset time.

* {@code LocalDateTime} has five additional convenience variants of the

* equivalent factory method taking fewer arguments.

* They are not provided here to reduce the footprint of the API.

*

* @param year the year to represent, from MIN_YEAR to MAX_YEAR

* @param month the month-of-year to represent, from 1 (January) to 12 (December)

* @param dayOfMonth the day-of-month to represent, from 1 to 31

* @param hour the hour-of-day to represent, from 0 to 23

* @param minute the minute-of-hour to represent, from 0 to 59

* @param second the second-of-minute to represent, from 0 to 59

* @param nanoOfSecond the nano-of-second to represent, from 0 to 999,999,999

* @param offset the zone offset, not null

* @return the offset date-time, not null

* @throws DateTimeException if the value of any field is out of range, or

* if the day-of-month is invalid for the month-year

*/

public static OffsetDateTime of(

int year, int month, int dayOfMonth,

int hour, int minute, int second, int nanoOfSecond, ZoneOffset offset) {

LocalDateTime dt = LocalDateTime.of(year, month, dayOfMonth, hour, minute, second, nanoOfSecond);

return new OffsetDateTime(dt, offset);

}

//-----------------------------------------------------------------------

/**

* Obtains an instance of {@code OffsetDateTime} from an {@code Instant} and zone ID.

* <p>

* This creates an offset date-time with the same instant as that specified.

* Finding the offset from UTC/Greenwich is simple as there is only one valid

* offset for each instant.

*

* @param instant the instant to create the date-time from, not null

* @param zone the time-zone, which may be an offset, not null

* @return the offset date-time, not null

* @throws DateTimeException if the result exceeds the supported range

*/

public static OffsetDateTime ofInstant(Instant instant, ZoneId zone) {

Objects.requireNonNull(instant, "instant");

Objects.requireNonNull(zone, "zone");

ZoneRules rules = zone.getRules();

ZoneOffset offset = rules.getOffset(instant);

LocalDateTime ldt = LocalDateTime.ofEpochSecond(instant.getEpochSecond(), instant.getNano(), offset);

return new OffsetDateTime(ldt, offset);

}

//-----------------------------------------------------------------------

/**

* Obtains an instance of {@code OffsetDateTime} from a temporal object.

* <p>

* This obtains an offset date-time based on the specified temporal.

* A {@code TemporalAccessor} represents an arbitrary set of date and time information,

* which this factory converts to an instance of {@code OffsetDateTime}.

* <p>

* The conversion will first obtain a {@code ZoneOffset} from the temporal object.

* It will then try to obtain a {@code LocalDateTime}, falling back to an {@code Instant} if necessary.

* The result will be the combination of {@code ZoneOffset} with either

* with {@code LocalDateTime} or {@code Instant}.

* Implementations are permitted to perform optimizations such as accessing

* those fields that are equivalent to the relevant objects.

* <p>

* This method matches the signature of the functional interface {@link TemporalQuery}

* allowing it to be used in queries via method reference, {@code OffsetDateTime::from}.

*

* @param temporal the temporal object to convert, not null

* @return the offset date-time, not null

* @throws DateTimeException if unable to convert to an {@code OffsetDateTime}

*/

public static OffsetDateTime from(TemporalAccessor temporal) {

if (temporal instanceof OffsetDateTime) {

return (OffsetDateTime) temporal;

}

try {

ZoneOffset offset = ZoneOffset.from(temporal);

try {

LocalDateTime ldt = LocalDateTime.from(temporal);

return OffsetDateTime.of(ldt, offset);

} catch (DateTimeException ignore) {

Instant instant = Instant.from(temporal);

return OffsetDateTime.ofInstant(instant, offset);

}

} catch (DateTimeException ex) {

throw new DateTimeException("Unable to obtain OffsetDateTime from TemporalAccessor: " +

temporal + " of type " + temporal.getClass().getName(), ex);

}

}

//-----------------------------------------------------------------------

/**

* Obtains an instance of {@code OffsetDateTime} from a text string

* such as {@code 2007-12-03T10:15:30+01:00}.

* <p>

* The string must represent a valid date-time and is parsed using

* {@link java.time.format.DateTimeFormatter#ISO_OFFSET_DATE_TIME}.

*

* @param text the text to parse such as "2007-12-03T10:15:30+01:00", not null

* @return the parsed offset date-time, not null

* @throws DateTimeParseException if the text cannot be parsed

*/

public static OffsetDateTime parse(CharSequence text) {

return parse(text, DateTimeFormatter.ISO_OFFSET_DATE_TIME);

}

/**

* Obtains an instance of {@code OffsetDateTime} from a text string using a specific formatter.

* <p>

* The text is parsed using the formatter, returning a date-time.

*

* @param text the text to parse, not null

* @param formatter the formatter to use, not null

* @return the parsed offset date-time, not null

* @throws DateTimeParseException if the text cannot be parsed

*/

public static OffsetDateTime parse(CharSequence text, DateTimeFormatter formatter) {

Objects.requireNonNull(formatter, "formatter");

return formatter.parse(text, OffsetDateTime::from);

}

//-----------------------------------------------------------------------

/**

* Constructor.

*

* @param dateTime the local date-time, not null

* @param offset the zone offset, not null

*/

private OffsetDateTime(LocalDateTime dateTime, ZoneOffset offset) {

this.dateTime = Objects.requireNonNull(dateTime, "dateTime");

this.offset = Objects.requireNonNull(offset, "offset");

}

/**

* Returns a new date-time based on this one, returning {@code this} where possible.

*

* @param dateTime the date-time to create with, not null

* @param offset the zone offset to create with, not null

*/

private OffsetDateTime with(LocalDateTime dateTime, ZoneOffset offset) {

if (this.dateTime == dateTime && this.offset.equals(offset)) {

return this;

}

return new OffsetDateTime(dateTime, offset);

}

//-----------------------------------------------------------------------

/**

* Checks if the specified field is supported.

* <p>

* This checks if this date-time can be queried for the specified field.

* If false, then calling the {@link #range(TemporalField) range},

* {@link #get(TemporalField) get} and {@link #with(TemporalField, long)}

* methods will throw an exception.

* <p>

* If the field is a {@link ChronoField} then the query is implemented here.

* The supported fields are:

* <ul>

* <li>{@code NANO_OF_SECOND}

* <li>{@code NANO_OF_DAY}

* <li>{@code MICRO_OF_SECOND}

* <li>{@code MICRO_OF_DAY}

* <li>{@code MILLI_OF_SECOND}

* <li>{@code MILLI_OF_DAY}

* <li>{@code SECOND_OF_MINUTE}

* <li>{@code SECOND_OF_DAY}

* <li>{@code MINUTE_OF_HOUR}

* <li>{@code MINUTE_OF_DAY}

* <li>{@code HOUR_OF_AMPM}

* <li>{@code CLOCK_HOUR_OF_AMPM}

* <li>{@code HOUR_OF_DAY}

* <li>{@code CLOCK_HOUR_OF_DAY}

* <li>{@code AMPM_OF_DAY}

* <li>{@code DAY_OF_WEEK}

* <li>{@code ALIGNED_DAY_OF_WEEK_IN_MONTH}

* <li>{@code ALIGNED_DAY_OF_WEEK_IN_YEAR}

* <li>{@code DAY_OF_MONTH}

* <li>{@code DAY_OF_YEAR}

* <li>{@code EPOCH_DAY}

* <li>{@code ALIGNED_WEEK_OF_MONTH}

* <li>{@code ALIGNED_WEEK_OF_YEAR}

* <li>{@code MONTH_OF_YEAR}

* <li>{@code PROLEPTIC_MONTH}

* <li>{@code YEAR_OF_ERA}

* <li>{@code YEAR}

* <li>{@code ERA}

* <li>{@code INSTANT_SECONDS}

* <li>{@code OFFSET_SECONDS}

* </ul>

* All other {@code ChronoField} instances will return false.

* <p>

* If the field is not a {@code ChronoField}, then the result of this method

* is obtained by invoking {@code TemporalField.isSupportedBy(TemporalAccessor)}

* passing {@code this} as the argument.

* Whether the field is supported is determined by the field.

*

* @param field the field to check, null returns false

* @return true if the field is supported on this date-time, false if not

*/

@Override

public boolean isSupported(TemporalField field) {

return field instanceof ChronoField || (field != null && field.isSupportedBy(this));

}

/**

* Checks if the specified unit is supported.

* <p>

* This checks if the specified unit can be added to, or subtracted from, this date-time.

* If false, then calling the {@link #plus(long, TemporalUnit)} and

* {@link #minus(long, TemporalUnit) minus} methods will throw an exception.

* <p>

* If the unit is a {@link ChronoUnit} then the query is implemented here.

* The supported units are:

* <ul>

* <li>{@code NANOS}

* <li>{@code MICROS}

* <li>{@code MILLIS}

* <li>{@code SECONDS}

* <li>{@code MINUTES}

* <li>{@code HOURS}

* <li>{@code HALF_DAYS}

* <li>{@code DAYS}

* <li>{@code WEEKS}

* <li>{@code MONTHS}

* <li>{@code YEARS}

* <li>{@code DECADES}

* <li>{@code CENTURIES}

* <li>{@code MILLENNIA}

* <li>{@code ERAS}

* </ul>

* All other {@code ChronoUnit} instances will return false.

* <p>

* If the unit is not a {@code ChronoUnit}, then the result of this method

* is obtained by invoking {@code TemporalUnit.isSupportedBy(Temporal)}

* passing {@code this} as the argument.

* Whether the unit is supported is determined by the unit.

*

* @param unit the unit to check, null returns false

* @return true if the unit can be added/subtracted, false if not

*/

@Override // override for Javadoc

public boolean isSupported(TemporalUnit unit) {

if (unit instanceof ChronoUnit) {

return unit != FOREVER;

}

return unit != null && unit.isSupportedBy(this);

}

//-----------------------------------------------------------------------

/**

* Gets the range of valid values for the specified field.

* <p>

* The range object expresses the minimum and maximum valid values for a field.

* This date-time is used to enhance the accuracy of the returned range.

* If it is not possible to return the range, because the field is not supported

* or for some other reason, an exception is thrown.

* <p>

* If the field is a {@link ChronoField} then the query is implemented here.

* The {@link #isSupported(TemporalField) supported fields} will return

* appropriate range instances.

* All other {@code ChronoField} instances will throw an {@code UnsupportedTemporalTypeException}.

* <p>

* If the field is not a {@code ChronoField}, then the result of this method

* is obtained by invoking {@code TemporalField.rangeRefinedBy(TemporalAccessor)}

* passing {@code this} as the argument.

* Whether the range can be obtained is determined by the field.

*

* @param field the field to query the range for, not null

* @return the range of valid values for the field, not null

* @throws DateTimeException if the range for the field cannot be obtained

* @throws UnsupportedTemporalTypeException if the field is not supported

*/

@Override

public ValueRange range(TemporalField field) {

if (field instanceof ChronoField) {

if (field == INSTANT_SECONDS || field == OFFSET_SECONDS) {

return field.range();

}

return dateTime.range(field);

}

return field.rangeRefinedBy(this);

}

/**

* Gets the value of the specified field from this date-time as an {@code int}.

* <p>

* This queries this date-time for the value for the specified field.

* The returned value will always be within the valid range of values for the field.

* If it is not possible to return the value, because the field is not supported

* or for some other reason, an exception is thrown.

* <p>

* If the field is a {@link ChronoField} then the query is implemented here.

* The {@link #isSupported(TemporalField) supported fields} will return valid

* values based on this date-time, except {@code NANO_OF_DAY}, {@code MICRO_OF_DAY},

* {@code EPOCH_DAY}, {@code PROLEPTIC_MONTH} and {@code INSTANT_SECONDS} which are too

* large to fit in an {@code int} and throw a {@code DateTimeException}.

* All other {@code ChronoField} instances will throw an {@code UnsupportedTemporalTypeException}.

* <p>

* If the field is not a {@code ChronoField}, then the result of this method

* is obtained by invoking {@code TemporalField.getFrom(TemporalAccessor)}

* passing {@code this} as the argument. Whether the value can be obtained,

* and what the value represents, is determined by the field.

*

* @param field the field to get, not null

* @return the value for the field

* @throws DateTimeException if a value for the field cannot be obtained or

* the value is outside the range of valid values for the field

* @throws UnsupportedTemporalTypeException if the field is not supported or

* the range of values exceeds an {@code int}

* @throws ArithmeticException if numeric overflow occurs

*/

@Override

public int get(TemporalField field) {

if (field instanceof ChronoField) {

switch ((ChronoField) field) {

case INSTANT_SECONDS:

throw new UnsupportedTemporalTypeException("Invalid field 'InstantSeconds' for get() method, use getLong() instead");

case OFFSET_SECONDS:

return getOffset().getTotalSeconds();

}

return dateTime.get(field);

}

return Temporal.super.get(field);

}

/**

* Gets the value of the specified field from this date-time as a {@code long}.

* <p>

* This queries this date-time for the value for the specified field.

* If it is not possible to return the value, because the field is not supported

* or for some other reason, an exception is thrown.

* <p>

* If the field is a {@link ChronoField} then the query is implemented here.

* The {@link #isSupported(TemporalField) supported fields} will return valid

* values based on this date-time.

* All other {@code ChronoField} instances will throw an {@code UnsupportedTemporalTypeException}.

* <p>

* If the field is not a {@code ChronoField}, then the result of this method

* is obtained by invoking {@code TemporalField.getFrom(TemporalAccessor)}

* passing {@code this} as the argument. Whether the value can be obtained,

* and what the value represents, is determined by the field.

*

* @param field the field to get, not null

* @return the value for the field

* @throws DateTimeException if a value for the field cannot be obtained

* @throws UnsupportedTemporalTypeException if the field is not supported

* @throws ArithmeticException if numeric overflow occurs

*/

@Override

public long getLong(TemporalField field) {

if (field instanceof ChronoField) {

switch ((ChronoField) field) {

case INSTANT_SECONDS: return toEpochSecond();

case OFFSET_SECONDS: return getOffset().getTotalSeconds();

}

return dateTime.getLong(field);

}

return field.getFrom(this);

}

//-----------------------------------------------------------------------

/**

* Gets the zone offset, such as '+01:00'.

* <p>

* This is the offset of the local date-time from UTC/Greenwich.

*

* @return the zone offset, not null

*/

public ZoneOffset getOffset() {

return offset;

}

/**

* Returns a copy of this {@code OffsetDateTime} with the specified offset ensuring

* that the result has the same local date-time.

* <p>

* This method returns an object with the same {@code LocalDateTime} and the specified {@code ZoneOffset}.

* No calculation is needed or performed.

* For example, if this time represents {@code 2007-12-03T10:30+02:00} and the offset specified is

* {@code +03:00}, then this method will return {@code 2007-12-03T10:30+03:00}.

* <p>

* To take into account the difference between the offsets, and adjust the time fields,

* use {@link #withOffsetSameInstant}.

* <p>

* This instance is immutable and unaffected by this method call.

*

* @param offset the zone offset to change to, not null

* @return an {@code OffsetDateTime} based on this date-time with the requested offset, not null

*/

public OffsetDateTime withOffsetSameLocal(ZoneOffset offset) {

return with(dateTime, offset);

}

/**

* Returns a copy of this {@code OffsetDateTime} with the specified offset ensuring

* that the result is at the same instant.

* <p>

* This method returns an object with the specified {@code ZoneOffset} and a {@code LocalDateTime}

* adjusted by the difference between the two offsets.

* This will result in the old and new objects representing the same instant.

* This is useful for finding the local time in a different offset.

* For example, if this time represents {@code 2007-12-03T10:30+02:00} and the offset specified is

* {@code +03:00}, then this method will return {@code 2007-12-03T11:30+03:00}.

* <p>

* To change the offset without adjusting the local time use {@link #withOffsetSameLocal}.

* <p>

* This instance is immutable and unaffected by this method call.

*

* @param offset the zone offset to change to, not null

* @return an {@code OffsetDateTime} based on this date-time with the requested offset, not null

* @throws DateTimeException if the result exceeds the supported date range

*/

public OffsetDateTime withOffsetSameInstant(ZoneOffset offset) {

if (offset.equals(this.offset)) {

return this;

}

int difference = offset.getTotalSeconds() - this.offset.getTotalSeconds();

LocalDateTime adjusted = dateTime.plusSeconds(difference);

return new OffsetDateTime(adjusted, offset);

}

//-----------------------------------------------------------------------

/**

* Gets the {@code LocalDateTime} part of this offset date-time.

* <p>

* This returns a {@code LocalDateTime} with the same year, month, day and time

* as this date-time.

*

* @return the local date-time part of this date-time, not null

*/

public LocalDateTime toLocalDateTime() {

return dateTime;

}

//-----------------------------------------------------------------------

/**

* Gets the {@code LocalDate} part of this date-time.

* <p>

* This returns a {@code LocalDate} with the same year, month and day

* as this date-time.

*

* @return the date part of this date-time, not null

*/

public LocalDate toLocalDate() {

return dateTime.toLocalDate();

}

/**

* Gets the year field.

* <p>

* This method returns the primitive {@code int} value for the year.

* <p>

* The year returned by this method is proleptic as per {@code get(YEAR)}.

* To obtain the year-of-era, use {@code get(YEAR_OF_ERA)}.

*

* @return the year, from MIN_YEAR to MAX_YEAR

*/

public int getYear() {

return dateTime.getYear();

}

/**

* Gets the month-of-year field from 1 to 12.

* <p>

* This method returns the month as an {@code int} from 1 to 12.

* Application code is frequently clearer if the enum {@link Month}

* is used by calling {@link #getMonth()}.

*

* @return the month-of-year, from 1 to 12

* @see #getMonth()

*/

public int getMonthValue() {

return dateTime.getMonthValue();

}

/**

* Gets the month-of-year field using the {@code Month} enum.

* <p>

* This method returns the enum {@link Month} for the month.

* This avoids confusion as to what {@code int} values mean.

* If you need access to the primitive {@code int} value then the enum

* provides the {@link Month#getValue() int value}.

*

* @return the month-of-year, not null

* @see #getMonthValue()

*/

public Month getMonth() {

return dateTime.getMonth();

}

/**

* Gets the day-of-month field.

* <p>

* This method returns the primitive {@code int} value for the day-of-month.

*

* @return the day-of-month, from 1 to 31

*/

public int getDayOfMonth() {

return dateTime.getDayOfMonth();

}

/**

* Gets the day-of-year field.

* <p>

* This method returns the primitive {@code int} value for the day-of-year.

*

* @return the day-of-year, from 1 to 365, or 366 in a leap year

*/

public int getDayOfYear() {

return dateTime.getDayOfYear();

}

/**

* Gets the day-of-week field, which is an enum {@code DayOfWeek}.

* <p>

* This method returns the enum {@link java.time.DayOfWeek} for the day-of-week.

* This avoids confusion as to what {@code int} values mean.

* If you need access to the primitive {@code int} value then the enum

* provides the {@link java.time.DayOfWeek#getValue() int value}.

* <p>

* Additional information can be obtained from the {@code DayOfWeek}.

* This includes textual names of the values.

*

* @return the day-of-week, not null

*/

public DayOfWeek getDayOfWeek() {

return dateTime.getDayOfWeek();

}

//-----------------------------------------------------------------------

/**

* Gets the {@code LocalTime} part of this date-time.

* <p>

* This returns a {@code LocalTime} with the same hour, minute, second and

* nanosecond as this date-time.

*

* @return the time part of this date-time, not null

*/

public LocalTime toLocalTime() {

return dateTime.toLocalTime();

}

/**

* Gets the hour-of-day field.

*

* @return the hour-of-day, from 0 to 23

*/

public int getHour() {

return dateTime.getHour();

}

/**

* Gets the minute-of-hour field.

*

* @return the minute-of-hour, from 0 to 59

*/

public int getMinute() {

return dateTime.getMinute();

}

/**

* Gets the second-of-minute field.

*

* @return the second-of-minute, from 0 to 59

*/

public int getSecond() {

return dateTime.getSecond();

}

/**

* Gets the nano-of-second field.

*

* @return the nano-of-second, from 0 to 999,999,999

*/

public int getNano() {

return dateTime.getNano();

}

//-----------------------------------------------------------------------

/**

* Returns an adjusted copy of this date-time.

* <p>

* This returns an {@code OffsetDateTime}, based on this one, with the date-time adjusted.

* The adjustment takes place using the specified adjuster strategy object.

* Read the documentation of the adjuster to understand what adjustment will be made.

* <p>

* A simple adjuster might simply set the one of the fields, such as the year field.

* A more complex adjuster might set the date to the last day of the month.

* A selection of common adjustments is provided in {@link TemporalAdjuster}.

* These include finding the "last day of the month" and "next Wednesday".

* Key date-time classes also implement the {@code TemporalAdjuster} interface,

* such as {@link Month} and {@link java.time.MonthDay MonthDay}.

* The adjuster is responsible for handling special cases, such as the varying

* lengths of month and leap years.

* <p>

* For example this code returns a date on the last day of July:

* <pre>

* import static java.time.Month.*;

* import static java.time.temporal.Adjusters.*;

*

* result = offsetDateTime.with(JULY).with(lastDayOfMonth());

* </pre>

* <p>

* The classes {@link LocalDate}, {@link LocalTime} and {@link ZoneOffset} implement

* {@code TemporalAdjuster}, thus this method can be used to change the date, time or offset:

* <pre>

* result = offsetDateTime.with(date);

* result = offsetDateTime.with(time);

* result = offsetDateTime.with(offset);

* </pre>

* <p>

* The result of this method is obtained by invoking the

* {@link TemporalAdjuster#adjustInto(Temporal)} method on the

* specified adjuster passing {@code this} as the argument.

* <p>

* This instance is immutable and unaffected by this method call.

*

* @param adjuster the adjuster to use, not null

* @return an {@code OffsetDateTime} based on {@code this} with the adjustment made, not null

* @throws DateTimeException if the adjustment cannot be made

* @throws ArithmeticException if numeric overflow occurs

*/

@Override

public OffsetDateTime with(TemporalAdjuster adjuster) {

// optimizations

if (adjuster instanceof LocalDate || adjuster instanceof LocalTime || adjuster instanceof LocalDateTime) {

return with(dateTime.with(adjuster), offset);

} else if (adjuster instanceof Instant) {

return ofInstant((Instant) adjuster, offset);

} else if (adjuster instanceof ZoneOffset) {

return with(dateTime, (ZoneOffset) adjuster);

} else if (adjuster instanceof OffsetDateTime) {

return (OffsetDateTime) adjuster;

}

return (OffsetDateTime) adjuster.adjustInto(this);

}

/**

* Returns a copy of this date-time with the specified field set to a new value.

* <p>

* TThis returns an {@code OffsetDateTime}, based on this one, with the value

* for the specified field changed.

* This can be used to change any supported field, such as the year, month or day-of-month.

* If it is not possible to set the value, because the field is not supported or for

* some other reason, an exception is thrown.

* <p>

* In some cases, changing the specified field can cause the resulting date-time to become invalid,

* such as changing the month from 31st January to February would make the day-of-month invalid.

* In cases like this, the field is responsible for resolving the date. Typically it will choose

* the previous valid date, which would be the last valid day of February in this example.

* <p>

* If the field is a {@link ChronoField} then the adjustment is implemented here.

* <p>

* The {@code INSTANT_SECONDS} field will return a date-time with the specified instant.

* The offset and nano-of-second are unchanged.

* If the new instant value is outside the valid range then a {@code DateTimeException} will be thrown.

* <p>

* The {@code OFFSET_SECONDS} field will return a date-time with the specified offset.

* The local date-time is unaltered. If the new offset value is outside the valid range

* then a {@code DateTimeException} will be thrown.

* <p>

* The other {@link #isSupported(TemporalField) supported fields} will behave as per

* the matching method on {@link LocalDateTime#with(TemporalField, long) LocalDateTime}.

* In this case, the offset is not part of the calculation and will be unchanged.

* <p>

* All other {@code ChronoField} instances will throw an {@code UnsupportedTemporalTypeException}.

* <p>

* If the field is not a {@code ChronoField}, then the result of this method

* is obtained by invoking {@code TemporalField.adjustInto(Temporal, long)}

* passing {@code this} as the argument. In this case, the field determines

* whether and how to adjust the instant.

* <p>

* This instance is immutable and unaffected by this method call.

*

* @param field the field to set in the result, not null

* @param newValue the new value of the field in the result

* @return an {@code OffsetDateTime} based on {@code this} with the specified field set, not null

* @throws DateTimeException if the field cannot be set

* @throws UnsupportedTemporalTypeException if the field is not supported

* @throws ArithmeticException if numeric overflow occurs

*/

@Override

public OffsetDateTime with(TemporalField field, long newValue) {

if (field instanceof ChronoField) {

ChronoField f = (ChronoField) field;

switch (f) {

case INSTANT_SECONDS: return ofInstant(Instant.ofEpochSecond(newValue, getNano()), offset);

case OFFSET_SECONDS: {

return with(dateTime, ZoneOffset.ofTotalSeconds(f.checkValidIntValue(newValue)));

}

}

return with(dateTime.with(field, newValue), offset);

}

return field.adjustInto(this, newValue);

}

//-----------------------------------------------------------------------

/**

* Returns a copy of this {@code OffsetDateTime} with the year altered.

* The offset does not affect the calculation and will be the same in the result.

* If the day-of-month is invalid for the year, it will be changed to the last valid day of the month.

* <p>

* This instance is immutable and unaffected by this method call.

*

* @param year the year to set in the result, from MIN_YEAR to MAX_YEAR

* @return an {@code OffsetDateTime} based on this date-time with the requested year, not null

* @throws DateTimeException if the year value is invalid

*/

public OffsetDateTime withYear(int year) {

return with(dateTime.withYear(year), offset);

}

/**

* Returns a copy of this {@code OffsetDateTime} with the month-of-year altered.

* The offset does not affect the calculation and will be the same in the result.

* If the day-of-month is invalid for the year, it will be changed to the last valid day of the month.

* <p>

* This instance is immutable and unaffected by this method call.