Start line:  
End line:  

Snippet Preview

Snippet HTML Code

Stack Overflow Questions
  /*
   *  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  org.joda.convert.FromString;
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(s):
Stephen Colebourne
Since:
1.0
 
 public final class Instant
         extends AbstractInstant
         implements ReadableInstantSerializable {

    
Serialization lock
 
     private static final long serialVersionUID = 3299096530934209741L;

    
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
 
     public static Instant now() {
         return new Instant();
     }
 
     //-----------------------------------------------------------------------
     
Parses a Instant from the specified string.

This uses ISODateTimeFormat.dateTimeParser().

Parameters:
str the string to parse, not null
Since:
2.0
 
     @FromString
     public static Instant parse(String str) {
         return parse(str, ISODateTimeFormat.dateTimeParser());
     }

    
Parses a Instant from the specified string using a formatter.

Parameters:
str the string to parse, not null
formatter the formatter to use, not null
Since:
2.0
 
     public static Instant parse(String strDateTimeFormatter formatter) {
         return formatter.parseDateTime(str).toInstant();
     }
    //-----------------------------------------------------------------------
    
Constructs an instance set to the current system millisecond time.

See also:
now()
    public Instant() {
        super();
         = DateTimeUtils.currentTimeMillis();
    }

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

Parameters:
instant the milliseconds from 1970-01-01T00:00:00Z
    public Instant(long instant) {
        super();
         = 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.

Parameters:
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);
         = converter.getInstantMillis(instant, ISOChronology.getInstanceUTC());
    }
    //-----------------------------------------------------------------------
    
Get this object as an Instant by returning this.

Returns:
this
    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.

Parameters:
newMillis the new millis, from 1970-01-01T00:00:00Z
Returns:
a copy of this instant with different millis
    public Instant withMillis(long newMillis) {
        return (newMillis ==  ? this : new Instant(newMillis));
    }

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

If the addition is zero, then this is returned.

Parameters:
durationToAdd the duration to add to this one
scalar the amount of times to add, such as -1 to subtract once
Returns:
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 durationToAddint scalar) {
        if (durationToAdd == 0 || scalar == 0) {
            return this;
        }
        long instant = getChronology().add(getMillis(), durationToAddscalar);
        return withMillis(instant);
    }

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

If the addition is zero, then this is returned.

Parameters:
durationToAdd the duration to add to this one, null means zero
scalar the amount of times to add, such as -1 to subtract once
Returns:
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 durationToAddint 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.

Parameters:
duration the duration to add to this one
Returns:
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.

Parameters:
duration the duration to add to this one, null means zero
Returns:
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.

Parameters:
duration the duration to reduce this instant by
Returns:
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.

Parameters:
duration the duration to reduce this instant by
Returns:
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
    public long getMillis() {
        return ;
    }

    
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
    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
    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.

Deprecated:
Use toDateTime() as it is identical
Returns:
a DateTime using the same millis with ISOChronology
    @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
        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.

Deprecated:
Use toMutableDateTime() as it is identical
Returns:
a MutableDateTime using the same millis with ISOChronology
    @Deprecated
        return toMutableDateTime();
    }
New to GrepCode? Check out our FAQ X