Package com.amazon.ion

Interface IonTimestamp

  • All Superinterfaces:
    java.lang.Cloneable, IonValue
    public interface IonTimestamp
extends IonValue
    An Ion timestamp value.

    WARNING: This interface should not be implemented or extended by code outside of this library.

    • Method Detail

      • timestampValue

        Timestamp timestampValue()
        Gets the value of this timestamp in a form suitable for use independent of Ion data.
        Returns:
        the value of this timestamp, or null if this.isNullValue().

      • dateValue

        java.util.Date dateValue()
        Gets the value of this Ion timestamp as a Java Date, representing the time in UTC. As a result, this method will return the same result for all Ion representations of the same instant, regardless of the local offset.

        Because Date instances are mutable, this method returns a new instance from each call.

        Returns:
        a new Date value, in UTC, or null if this.isNullValue().

      • getMillis

        long getMillis()
        throws NullValueException
        Gets the value of this Ion timestamp as the number of milliseconds since 1970-01-01T00:00:00.000Z, truncating any fractional milliseconds. This method will return the same result for all Ion representations of the same instant, regardless of the local offset.
        Returns:
        the number of milliseconds since 1970-01-01T00:00:00.000Z represented by this timestamp.
        Throws:
        NullValueException - if this.isNullValue().

      • getDecimalMillis

        java.math.BigDecimal getDecimalMillis()
        Gets the value of this Ion timestamp as the number of milliseconds since 1970-01-01T00:00:00Z, including fractional milliseconds. This method will return the same result for all Ion representations of the same instant, regardless of the local offset.
        Returns:
        the number of milliseconds since 1970-01-01T00:00:00Z represented by this timestamp, or null if this.isNullValue().

      • setValue

        void setValue​(Timestamp timestamp)
        Sets the value of this timestamp.
        Parameters:
        timestamp - may be null to cause this to be null.timestamp.

      • setValue

        void setValue​(java.math.BigDecimal millis,
              java.lang.Integer localOffset)
        Sets this timestamp to represent the point in time that is millis milliseconds after 1970-01-01T00:00:00Z, with the specified local offset of localOffset.
        Parameters:
        millis - the number of milliseconds since 1970-01-01T00:00:00Z to be represented by this timestamp.
        localOffset - the local offset of this timestamp, in minutes. Zero indicates UTC. null indicates the unknown offset (-00:00).
        Throws:
        java.lang.IllegalArgumentException - if the resulting timestamp would precede 0001-01-01T00:00:00Z.
        java.lang.NullPointerException - if millis is null

      • setValue

        void setValue​(long millis,
              java.lang.Integer localOffset)
        Sets this timestamp to represent the point in time that is millis milliseconds after 1970-01-01T00:00:00Z, with the specified local offset of localOffset.
        Parameters:
        millis - the number of milliseconds since 1970-01-01T00:00:00Z to be represented by this timestamp.
        localOffset - the local offset of this timestamp, in minutes. Zero indicates UTC. null indicates the unknown offset (-00:00).
        Throws:
        java.lang.IllegalArgumentException - if the resulting timestamp would precede 0001-01-01T00:00:00Z.

      • setMillis

        void setMillis​(long millis)
        Sets this timestamp to represent the point in time that is millis milliseconds after 1970-01-01T00:00:00Z, with the same local offset part.

        If this is null.timestamp, then the local offset will be unknown.

        Parameters:
        millis - the number of milliseconds since 1970-01-01T00:00:00Z to be represented by this timestamp.
        Throws:
        java.lang.IllegalArgumentException - if the resulting timestamp would precede 0001-01-01T00:00:00Z.

      • setDecimalMillis

        void setDecimalMillis​(java.math.BigDecimal millis)
        Sets this timestamp to represent the point in time that is millis milliseconds after 1970-01-01T00:00:00Z, with the same local offset part.

        If this is null.timestamp, then the local offset will be unknown.

        Parameters:
        millis - the number of milliseconds since 1970-01-01T00:00:00Z to be represented by this timestamp.
        Throws:
        java.lang.IllegalArgumentException - if the resulting timestamp would precede 0001-01-01T00:00:00Z.
        java.lang.NullPointerException - if millis is null

      • setMillisUtc

        void setMillisUtc​(long millis)
        Sets this timestamp to represent the point in time that is millis milliseconds after 1970-01-01T00:00:00Z, and sets the local offset to UTC.
        Parameters:
        millis - the number of milliseconds since 1970-01-01T00:00:00Z to be represented by this timestamp.

      • getLocalOffset

        java.lang.Integer getLocalOffset()
                          throws NullValueException
        Gets the local offset (in minutes) of this timestamp, or null if it's unknown (i.e., -00:00).

        For example, the result for 1969-02-23T07:00+07:00 is 420, the result for 1969-02-22T22:45:00.00-01:15 is -75, and the result for 1969-02-23 (by Ion's definition, equivalent to 1969-02-23T00:00-00:00) is null.

        Returns:
        the positive or negative local-time offset, represented as minutes from UTC. If the offset is unknown, returns null.
        Throws:
        NullValueException - if this.isNullValue().

      • setTime

        void setTime​(java.util.Date value)
        Sets the time portion of this timestamp. If value is null, then this will become null.timestamp. If this is null.timestamp, then the local offset will be unknown.
        Parameters:
        value - will be copied into this element. If null then this becomes null.timestamp.

      • setCurrentTime

        void setCurrentTime()
        Sets the time portion of this timestamp to the current time, leaving the local offset portion unchanged.

        If this.isNullValue(), then the local offset will be unknown.

      • setCurrentTimeUtc

        void setCurrentTimeUtc()
        Sets the time portion of this timestamp to the current time, and the local offset portion to UTC.

      • setLocalOffset

        void setLocalOffset​(int minutes)
             throws NullValueException
        Sets the local-offset portion of this timestamp. The time portion is not changed. Note that this method cannot set the unknown offset (-00:00); to do that use setLocalOffset(Integer).
        Parameters:
        minutes - is the new local offset, in minutes. Zero indicates UTC.
        Throws:
        NullValueException - if this.isNullValue().

      • setLocalOffset

        void setLocalOffset​(java.lang.Integer minutes)
             throws NullValueException
        Sets the local-offset portion of this timestamp. The time portion is not changed.
        Parameters:
        minutes - is the new local offset, in minutes. Zero indicates UTC. null indicates the unknown offset (-00:00).
        Throws:
        NullValueException - if this.isNullValue().

      • makeNull

        void makeNull()
        Sets this timestamp to Ion null.timestamp.

      • clone

        IonTimestamp clone()
            throws UnknownSymbolException
        Description copied from interface: IonValue
        Creates a copy of this value and all of its children. The cloned value may use the same shared symbol tables, but it will have an independent local symbol table if necessary. The cloned value will be modifiable regardless of whether this instance IonValue.isReadOnly().

        The cloned value will be created in the context of the same ValueFactory as this instance; if you want a copy using a different factory, then use ValueFactory.clone(IonValue) instead.

        Specified by:
        clone in interface IonValue
        Throws:
        UnknownSymbolException - if any part of this value has unknown text but known Sid for its field name, annotation or symbol.