Start line:  
End line:  

Snippet Preview

Snippet HTML Code

Stack Overflow Questions
  /*
   *  Copyright 2001-2006 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;
 
 
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;
 
     //-----------------------------------------------------------------------
     
Constructs an instance set to the current system millisecond time.
 
     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 org.joda.time.convert.ConverterManager and include String, Calendar and Date.

Parameters:
instant the datetime object, null means now
Throws:
java.lang.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:
java.lang.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:
java.lang.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:
java.lang.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:
java.lang.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:
java.lang.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:
java.lang.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 org.joda.time.chrono.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 compatability 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 definition preserves compatability with earlier versions of Joda-Time.

Deprecated:
Use toDateTime() as it is identical
Returns:
a DateTime using the same millis with ISOChronology
    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 compatability 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 definition preserves compatability with earlier versions of Joda-Time.

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