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.

Field Summary

Fields inherited from interface com.amazon.ion.IonValue

EMPTY_ARRAY

Method Summary

Modifier and Type	Method and Description
IonTimestamp	clone() Creates a copy of this value and all of its children.
java.util.Date	dateValue() Gets the value of this Ion timestamp as a Java Date, representing the time in UTC.
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.
java.lang.Integer	getLocalOffset() Gets the local offset (in minutes) of this timestamp, or null if it's unknown (i.e., -00:00).
long	getMillis() Gets the value of this Ion timestamp as the number of milliseconds since 1970-01-01T00:00:00.000Z, truncating any fractional milliseconds.
void	makeNull() Sets this timestamp to Ion null.timestamp.
void	setCurrentTime() Sets the time portion of this timestamp to the current time, leaving the local offset portion unchanged.
void	setCurrentTimeUtc() Sets the time portion of this timestamp to the current time, and the local offset portion to UTC.
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.
void	setLocalOffset(int minutes) Sets the local-offset portion of this timestamp.
void	setLocalOffset(java.lang.Integer minutes) Sets the local-offset portion of this timestamp.
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.
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.
void	setTime(java.util.Date value) Sets the time portion of this timestamp.
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.
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.
void	setValue(Timestamp timestamp) Sets the value of this timestamp.
Timestamp	timestampValue() Gets the value of this timestamp in a form suitable for use independent of Ion data.

Methods inherited from interface com.amazon.ion.IonValue

accept, addTypeAnnotation, clearTypeAnnotations, equals, getContainer, getFieldId, getFieldName, getFieldNameSymbol, getSymbolTable, getSystem, getType, getTypeAnnotations, getTypeAnnotationSymbols, hashCode, hasTypeAnnotation, isNullValue, isReadOnly, makeReadOnly, removeFromContainer, removeTypeAnnotation, setTypeAnnotations, setTypeAnnotationSymbols, topLevelValue, toPrettyString, toString, toString, writeTo

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.