http://www.joda.org/joda-time/: Date and time library to replace JDK date handling (Joda.org) 
/*
 *  Copyright 2001-2010 Stephen Colebourne
 *
 *  Licensed under the Apache License, Version 2.0 (the "License");
 *  you may not use this file except in compliance with the License.
 *  You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 *  Unless required by applicable law or agreed to in writing, software
 *  distributed under the License is distributed on an "AS IS" BASIS,
 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 *  See the License for the specific language governing permissions and
 *  limitations under the License.
 */
package org.joda.time;

import java.io.Serializable;

import org.joda.convert.FromString;
import org.joda.time.base.AbstractInstant;
import org.joda.time.chrono.ISOChronology;
import org.joda.time.convert.ConverterManager;
import org.joda.time.convert.InstantConverter;
import org.joda.time.field.FieldUtils;
import org.joda.time.format.DateTimeFormatter;
import org.joda.time.format.ISODateTimeFormat;


Instant is the standard implementation of a fully immutable instant in time.


Instant is an implementation of ReadableInstant. As with all instants, it represents an exact point on the time-line, but limited to the precision of milliseconds. An Instant
should be used to represent a point in time irrespective of any other
factor, such as chronology or time zone.


Internally, the class holds one piece of data, the instant as milliseconds
from the Java epoch of 1970-01-01T00:00:00Z.


For example, an Instant can be used to compare two DateTime
objects irrespective of chronology or time zone.

boolean sameInstant = dt1.toInstant().equals(dt2.toInstant());


Note that the following code will also perform the same check:

boolean sameInstant = dt1.isEqual(dt2);




Instant is thread-safe and immutable.

Author:Stephen Colebourne
Since:1.0
/**
 * Instant is the standard implementation of a fully immutable instant in time.
 * <p>
 * <code>Instant</code> is an implementation of {@link ReadableInstant}.
 * As with all instants, it represents an exact point on the time-line,
 * but limited to the precision of milliseconds. An <code>Instant</code>
 * should be used to represent a point in time irrespective of any other
 * factor, such as chronology or time zone.
 * <p>
 * Internally, the class holds one piece of data, the instant as milliseconds
 * from the Java epoch of 1970-01-01T00:00:00Z.
 * <p>
 * For example, an Instant can be used to compare two <code>DateTime</code>
 * objects irrespective of chronology or time zone.
 * <pre>
 * boolean sameInstant = dt1.toInstant().equals(dt2.toInstant());
 * </pre>
 * Note that the following code will also perform the same check:
 * <pre>
 * boolean sameInstant = dt1.isEqual(dt2);
 * </pre>
 * <p>
 * Instant is thread-safe and immutable.
 *
 * @author Stephen Colebourne
 * @since 1.0
 */
public final class Instant
        extends AbstractInstant
        implements ReadableInstant, Serializable {

    
The Java epoch of 1970-01-01T00:00:00Z.

Since:2.10
/**
     * The Java epoch of 1970-01-01T00:00:00Z.
     * @since 2.10
     */
    public static final Instant EPOCH = new Instant(0L);

    
Serialization lock 
/** Serialization lock */
    private static final long serialVersionUID = 3299096530934209741L;

    
The millis from 1970-01-01T00:00:00Z 
/** The millis from 1970-01-01T00:00:00Z */
    private final long iMillis;

    //-----------------------------------------------------------------------
    
Obtains an Instant set to the current system millisecond time. 
Returns:the current instant, not null
Since:2.0
/**
     * Obtains an {@code Instant} set to the current system millisecond time.
     * 
     * @return the current instant, not null
     * @since 2.0
     */
    public static Instant now() {
        return new Instant();
    }
    
    
Obtains an Instant set to the milliseconds from 1970-01-01T00:00:00Z. 
Params:
  • epochMilli –  the milliseconds from 1970-01-01T00:00:00Z
Since:2.10
/**
     * Obtains an {@code Instant} set to the milliseconds from 1970-01-01T00:00:00Z.
     * 
     * @param epochMilli  the milliseconds from 1970-01-01T00:00:00Z
     * @since 2.10
     */
    public static Instant ofEpochMilli(long epochMilli) {
        return new Instant(epochMilli);
    }
    
    
Obtains an Instant set to the seconds from 1970-01-01T00:00:00Z. 
Params:
  • epochSecond –  the seconds from 1970-01-01T00:00:00Z
Throws:
Since:2.10
/**
     * Obtains an {@code Instant} set to the seconds from 1970-01-01T00:00:00Z.
     * 
     * @param epochSecond  the seconds from 1970-01-01T00:00:00Z
     * @throws ArithmeticException if the new instant exceeds the capacity of a long
     * @since 2.10
     */
    public static Instant ofEpochSecond(long epochSecond) {
        return new Instant(FieldUtils.safeMultiply(epochSecond, 1000));
    }

    //-----------------------------------------------------------------------
    
Parses an Instant from the specified string. 
 This uses ISODateTimeFormat.dateTimeParser(). 
Params:
  • str –  the string to parse, not null
Since:2.0
/**
     * Parses an {@code Instant} from the specified string.
     * <p>
     * This uses {@link ISODateTimeFormat#dateTimeParser()}.
     * 
     * @param str  the string to parse, not null
     * @since 2.0
     */
    @FromString
    public static Instant parse(String str) {
        return parse(str, ISODateTimeFormat.dateTimeParser());
    }

    
Parses an Instant from the specified string using a formatter. 
Params:
  • str –  the string to parse, not null
  • formatter –  the formatter to use, not null
Since:2.0
/**
     * Parses an {@code Instant} from the specified string using a formatter.
     * 
     * @param str  the string to parse, not null
     * @param formatter  the formatter to use, not null
     * @since 2.0
     */
    public static Instant parse(String str, DateTimeFormatter formatter) {
        return formatter.parseDateTime(str).toInstant();
    }

    //-----------------------------------------------------------------------
    
Constructs an instance set to the current system millisecond time.

See Also:
  • now()
/**
     * Constructs an instance set to the current system millisecond time.
     * 
     * @see #now()
     */
    public Instant() {
        super();
        iMillis = DateTimeUtils.currentTimeMillis();
    }

    
Constructs an instance set to the milliseconds from 1970-01-01T00:00:00Z.

Params:
  • instant –  the milliseconds from 1970-01-01T00:00:00Z
/**
     * Constructs an instance set to the milliseconds from 1970-01-01T00:00:00Z.
     * 
     * @param instant  the milliseconds from 1970-01-01T00:00:00Z
     */
    public Instant(long instant) {
        super();
        iMillis = instant;
    }

    
Constructs an instance from an Object that represents a datetime.

 The recognised object types are defined in ConverterManager and include String, Calendar and Date. 
Params:
  • instant –  the datetime object, null means now
Throws:
/**
     * Constructs an instance from an Object that represents a datetime.
     * <p>
     * The recognised object types are defined in {@link ConverterManager} and
     * include String, Calendar and Date.
     *
     * @param instant  the datetime object, null means now
     * @throws IllegalArgumentException if the instant is invalid
     */
    public Instant(Object instant) {
        super();
        InstantConverter converter = ConverterManager.getInstance().getInstantConverter(instant);
        iMillis = converter.getInstantMillis(instant, ISOChronology.getInstanceUTC());
    }

    //-----------------------------------------------------------------------
    
Get this object as an Instant by returning this.

Returns:this
/**
     * Get this object as an Instant by returning <code>this</code>.
     * 
     * @return <code>this</code>
     */
    public Instant toInstant() {
        return this;
    }

    //-----------------------------------------------------------------------
    
Gets a copy of this instant with different millis.


The returned object will be either be a new Instant or this.


Note that this replaces the entire state of the Instant. To manage the sub-second part of the instant, use toDateTime() and DateTime.withMillisOfSecond(int). 
Params:
  • newMillis –  the new millis, from 1970-01-01T00:00:00Z
Returns:a copy of this instant with different millis
/**
     * Gets a copy of this instant with different millis.
     * <p>
     * The returned object will be either be a new Instant or <code>this</code>.
     * <p>
     * Note that this replaces the entire state of the <code>Instant</code>.
     * To manage the sub-second part of the instant, use {@link #toDateTime()}
     * and {@link DateTime#withMillisOfSecond(int)}.
     *
     * @param newMillis  the new millis, from 1970-01-01T00:00:00Z
     * @return a copy of this instant with different millis
     */
    public Instant withMillis(long newMillis) {
        return (newMillis == iMillis ? this : new Instant(newMillis));
    }

    
Gets a copy of this instant with the specified duration added.


If the addition is zero, then this is returned.

Params:
  • durationToAdd –  the duration to add to this one
  • scalar –  the amount of times to add, such as -1 to subtract once
Throws:
Returns:a copy of this instant with the duration added
/**
     * Gets a copy of this instant with the specified duration added.
     * <p>
     * If the addition is zero, then <code>this</code> is returned.
     * 
     * @param durationToAdd  the duration to add to this one
     * @param scalar  the amount of times to add, such as -1 to subtract once
     * @return a copy of this instant with the duration added
     * @throws ArithmeticException if the new instant exceeds the capacity of a long
     */
    public Instant withDurationAdded(long durationToAdd, int scalar) {
        if (durationToAdd == 0 || scalar == 0) {
            return this;
        }
        long instant = getChronology().add(getMillis(), durationToAdd, scalar);
        return withMillis(instant);
    }

    
Gets a copy of this instant with the specified duration added.


If the addition is zero, then this is returned.

Params:
  • durationToAdd –  the duration to add to this one, null means zero
  • scalar –  the amount of times to add, such as -1 to subtract once
Throws:
Returns:a copy of this instant with the duration added
/**
     * Gets a copy of this instant with the specified duration added.
     * <p>
     * If the addition is zero, then <code>this</code> is returned.
     * 
     * @param durationToAdd  the duration to add to this one, null means zero
     * @param scalar  the amount of times to add, such as -1 to subtract once
     * @return a copy of this instant with the duration added
     * @throws ArithmeticException if the new instant exceeds the capacity of a long
     */
    public Instant withDurationAdded(ReadableDuration durationToAdd, int scalar) {
        if (durationToAdd == null || scalar == 0) {
            return this;
        }
        return withDurationAdded(durationToAdd.getMillis(), scalar);
    }

    //-----------------------------------------------------------------------
    
Gets a copy of this instant with the specified duration added.


If the amount is zero or null, then this is returned.

Params:
  • duration –  the duration to add to this one
Throws:
Returns:a copy of this instant with the duration added
/**
     * Gets a copy of this instant with the specified duration added.
     * <p>
     * If the amount is zero or null, then <code>this</code> is returned.
     * 
     * @param duration  the duration to add to this one
     * @return a copy of this instant with the duration added
     * @throws ArithmeticException if the new instant exceeds the capacity of a long
     */
    public Instant plus(long duration) {
        return withDurationAdded(duration, 1);
    }

    
Gets a copy of this instant with the specified duration added.


If the amount is zero or null, then this is returned.

Params:
  • duration –  the duration to add to this one, null means zero
Throws:
Returns:a copy of this instant with the duration added
/**
     * Gets a copy of this instant with the specified duration added.
     * <p>
     * If the amount is zero or null, then <code>this</code> is returned.
     * 
     * @param duration  the duration to add to this one, null means zero
     * @return a copy of this instant with the duration added
     * @throws ArithmeticException if the new instant exceeds the capacity of a long
     */
    public Instant plus(ReadableDuration duration) {
        return withDurationAdded(duration, 1);
    }

    //-----------------------------------------------------------------------
    
Gets a copy of this instant with the specified duration taken away.


If the amount is zero or null, then this is returned.

Params:
  • duration –  the duration to reduce this instant by
Throws:
Returns:a copy of this instant with the duration taken away
/**
     * Gets a copy of this instant with the specified duration taken away.
     * <p>
     * If the amount is zero or null, then <code>this</code> is returned.
     * 
     * @param duration  the duration to reduce this instant by
     * @return a copy of this instant with the duration taken away
     * @throws ArithmeticException if the new instant exceeds the capacity of a long
     */
    public Instant minus(long duration) {
        return withDurationAdded(duration, -1);
    }

    
Gets a copy of this instant with the specified duration taken away.


If the amount is zero or null, then this is returned.

Params:
  • duration –  the duration to reduce this instant by
Throws:
Returns:a copy of this instant with the duration taken away
/**
     * Gets a copy of this instant with the specified duration taken away.
     * <p>
     * If the amount is zero or null, then <code>this</code> is returned.
     * 
     * @param duration  the duration to reduce this instant by
     * @return a copy of this instant with the duration taken away
     * @throws ArithmeticException if the new instant exceeds the capacity of a long
     */
    public Instant minus(ReadableDuration duration) {
        return withDurationAdded(duration, -1);
    }

    //-----------------------------------------------------------------------
    
Gets the milliseconds of the instant.

Returns:the number of milliseconds since 1970-01-01T00:00:00Z
/**
     * Gets the milliseconds of the instant.
     * 
     * @return the number of milliseconds since 1970-01-01T00:00:00Z
     */
    public long getMillis() {
        return iMillis;
    }

    
Gets the chronology of the instant, which is ISO in the UTC zone.

 This method returns ISOChronology.getInstanceUTC() which corresponds to the definition of the Java epoch 1970-01-01T00:00:00Z. 
Returns:ISO in the UTC zone
/**
     * Gets the chronology of the instant, which is ISO in the UTC zone.
     * <p>
     * This method returns {@link ISOChronology#getInstanceUTC()} which
     * corresponds to the definition of the Java epoch 1970-01-01T00:00:00Z.
     * 
     * @return ISO in the UTC zone
     */
    public Chronology getChronology() {
        return ISOChronology.getInstanceUTC();
    }

    //-----------------------------------------------------------------------
    
Get this object as a DateTime using ISOChronology in the default zone.


This method returns a DateTime object in the default zone.
This differs from the similarly named method on DateTime, DateMidnight
or MutableDateTime which retains the time zone. The difference is
because Instant really represents a time without a zone,
thus calling this method we really have no zone to 'retain' and
hence expect to switch to the default zone.


This method definition preserves compatibility with earlier versions
of Joda-Time.

Returns:a DateTime using the same millis
/**
     * Get this object as a DateTime using ISOChronology in the default zone.
     * <p>
     * This method returns a DateTime object in the default zone.
     * This differs from the similarly named method on DateTime, DateMidnight
     * or MutableDateTime which retains the time zone. The difference is
     * because Instant really represents a time <i>without</i> a zone,
     * thus calling this method we really have no zone to 'retain' and
     * hence expect to switch to the default zone.
     * <p>
     * This method definition preserves compatibility with earlier versions
     * of Joda-Time.
     *
     * @return a DateTime using the same millis
     */
    public DateTime toDateTime() {
        return new DateTime(getMillis(), ISOChronology.getInstance());
    }

    
Get this object as a DateTime using ISOChronology in the default zone.
This method is identical to toDateTime().


This method returns a DateTime object in the default zone.
This differs from the similarly named method on DateTime, DateMidnight
or MutableDateTime which retains the time zone. The difference is
because Instant really represents a time without a zone,
thus calling this method we really have no zone to 'retain' and
hence expect to switch to the default zone.

 This method is deprecated because it is a duplicate of toDateTime(). However, removing it would cause the superclass implementation to be used, which would create silent bugs in any caller depending on this implementation. As such, the method itself is not currently planned to be removed. 

This method definition preserves compatibility with earlier versions
of Joda-Time.

Returns:a DateTime using the same millis with ISOChronology
Deprecated:Use toDateTime() as it is identical
/**
     * Get this object as a DateTime using ISOChronology in the default zone.
     * This method is identical to <code>toDateTime()</code>.
     * <p>
     * This method returns a DateTime object in the default zone.
     * This differs from the similarly named method on DateTime, DateMidnight
     * or MutableDateTime which retains the time zone. The difference is
     * because Instant really represents a time <i>without</i> a zone,
     * thus calling this method we really have no zone to 'retain' and
     * hence expect to switch to the default zone.
     * <p>
     * This method is deprecated because it is a duplicate of {@link #toDateTime()}.
     * However, removing it would cause the superclass implementation to be used,
     * which would create silent bugs in any caller depending on this implementation.
     * As such, the method itself is not currently planned to be removed.
     * <p>
     * This method definition preserves compatibility with earlier versions
     * of Joda-Time.
     *
     * @return a DateTime using the same millis with ISOChronology
     * @deprecated Use toDateTime() as it is identical
     */
    @Deprecated
    public DateTime toDateTimeISO() {
        return toDateTime();
    }

    
Get this object as a MutableDateTime using ISOChronology in the default zone.


This method returns a MutableDateTime object in the default zone.
This differs from the similarly named method on DateTime, DateMidnight
or MutableDateTime which retains the time zone. The difference is
because Instant really represents a time without a zone,
thus calling this method we really have no zone to 'retain' and
hence expect to switch to the default zone.


This method definition preserves compatibility with earlier versions
of Joda-Time.

Returns:a MutableDateTime using the same millis
/**
     * Get this object as a MutableDateTime using ISOChronology in the default zone.
     * <p>
     * This method returns a MutableDateTime object in the default zone.
     * This differs from the similarly named method on DateTime, DateMidnight
     * or MutableDateTime which retains the time zone. The difference is
     * because Instant really represents a time <i>without</i> a zone,
     * thus calling this method we really have no zone to 'retain' and
     * hence expect to switch to the default zone.
     * <p>
     * This method definition preserves compatibility with earlier versions
     * of Joda-Time.
     *
     * @return a MutableDateTime using the same millis
     */
    public MutableDateTime toMutableDateTime() {
        return new MutableDateTime(getMillis(), ISOChronology.getInstance());
    }

    
Get this object as a MutableDateTime using ISOChronology in the default zone.
This method is identical to toMutableDateTime().


This method returns a MutableDateTime object in the default zone.
This differs from the similarly named method on DateTime, DateMidnight
or MutableDateTime which retains the time zone. The difference is
because Instant really represents a time without a zone,
thus calling this method we really have no zone to 'retain' and
hence expect to switch to the default zone.

 This method is deprecated because it is a duplicate of toMutableDateTime(). However, removing it would cause the superclass implementation to be used, which would create silent bugs in any caller depending on this implementation. As such, the method itself is not currently planned to be removed. 

This method definition preserves compatibility with earlier versions
of Joda-Time.

Returns:a MutableDateTime using the same millis with ISOChronology
Deprecated:Use toMutableDateTime() as it is identical
/**
     * Get this object as a MutableDateTime using ISOChronology in the default zone.
     * This method is identical to <code>toMutableDateTime()</code>.
     * <p>
     * This method returns a MutableDateTime object in the default zone.
     * This differs from the similarly named method on DateTime, DateMidnight
     * or MutableDateTime which retains the time zone. The difference is
     * because Instant really represents a time <i>without</i> a zone,
     * thus calling this method we really have no zone to 'retain' and
     * hence expect to switch to the default zone.
     * <p>
     * This method is deprecated because it is a duplicate of {@link #toMutableDateTime()}.
     * However, removing it would cause the superclass implementation to be used,
     * which would create silent bugs in any caller depending on this implementation.
     * As such, the method itself is not currently planned to be removed.
     * <p>
     * This method definition preserves compatibility with earlier versions
     * of Joda-Time.
     *
     * @return a MutableDateTime using the same millis with ISOChronology
     * @deprecated Use toMutableDateTime() as it is identical
     */
    @Deprecated
    public MutableDateTime toMutableDateTimeISO() {
        return toMutableDateTime();
    }

}