com.unboundid.asn1

Class ASN1GeneralizedTime

java.lang.Object

com.unboundid.asn1.ASN1Element

com.unboundid.asn1.ASN1GeneralizedTime

All Implemented Interfaces:

java.io.Serializable

@NotMutable
 @ThreadSafety(level=COMPLETELY_THREADSAFE)
public final class ASN1GeneralizedTime
extends ASN1Element

This class provides an ASN.1 generalized time element, which represents a timestamp in the generalized time format. The value is encoded as a string, although the ASN.1 specification imposes a number of restrictions on that string representation, including:

• The generic generalized time specification allows you to specify the time zone either by ending the value with "Z" to indicate that the value is in the UTC time zone, or by ending it with a positive or negative offset (expressed in hours and minutes) from UTC time. The ASN.1 specification only allows the "Z" option.
• The generic generalized time specification only requires generalized time values to include the year, month, day, and hour components of the timestamp, while the minute, second, and sub-second components are optional. The ASN.1 specification requires that generalized time values always include the minute and second components. Sub-second components are permitted, but with the restriction noted below.
• The ASN.1 specification for generalized time values does not allow the sub-second component to include any trailing zeroes. If the sub-second component is all zeroes, then it will be omitted, along with the decimal point that would have separated the second and sub-second components.

Note that this implementation only supports up to millisecond-level precision. It will never generate a value with a sub-second component that contains more than three digits, and any value decoded from a string representation that contains a sub-second component with more than three digits will return a timestamp rounded to the nearest millisecond from the getDate() and getTime() methods, although the original string representation will be retained and will be used in the encoded representation.

See Also:

Serialized Form

Constructor Summary

Constructors

Constructor and Description
ASN1GeneralizedTime() Creates a new generalized time element with the default BER type that represents the current time.
ASN1GeneralizedTime(byte type) Creates a new generalized time element with the specified BER type that represents the current time.
ASN1GeneralizedTime(byte type, java.util.Date date) Creates a new generalized time element with the specified BER type that represents the indicated time.
ASN1GeneralizedTime(byte type, long time) Creates a new generalized time element with the specified BER type that represents the indicated time.
ASN1GeneralizedTime(byte type, java.lang.String timestamp) Creates a new generalized time element with the specified BER type and a time decoded from the provided string representation.
ASN1GeneralizedTime(java.util.Date date) Creates a new generalized time element with the default BER type that represents the indicated time.
ASN1GeneralizedTime(long time) Creates a new generalized time element with the default BER type that represents the indicated time.
ASN1GeneralizedTime(java.lang.String timestamp) Creates a new generalized time element with the default BER type and a time decoded from the provided string representation.

Method Summary

Modifier and Type	Method and Description
static ASN1GeneralizedTime	decodeAsGeneralizedTime(ASN1Element element) Decodes the provided ASN.1 element as a generalized time element.
static ASN1GeneralizedTime	decodeAsGeneralizedTime(byte[] elementBytes) Decodes the contents of the provided byte array as a generalized time element.
static long	decodeTimestamp(java.lang.String timestamp) Decodes the provided string as a timestamp in the generalized time format.
static java.lang.String	encodeTimestamp(java.util.Date date, boolean includeMilliseconds) Encodes the time represented by the provided date into the appropriate ASN.1 generalized time format.
static java.lang.String	encodeTimestamp(long time, boolean includeMilliseconds) Encodes the specified time into the appropriate ASN.1 generalized time format.
java.util.Date	getDate() Retrieves a Date object that is set to the time represented by this generalized time element.
java.lang.String	getStringRepresentation() Retrieves the string representation of the generalized time value contained in this element.
long	getTime() Retrieves the time represented by this generalized time element, expressed as the number of milliseconds since the epoch (the same format used by System.currentTimeMillis() and Date.getTime()).
void	toString(java.lang.StringBuilder buffer) Appends a string representation of the value for this ASN.1 element to the provided buffer.

Methods inherited from class com.unboundid.asn1.ASN1Element

decode, decodeAsBigInteger, decodeAsBitString, decodeAsBoolean, decodeAsEnumerated, decodeAsGeneralizedTime, decodeAsIA5String, decodeAsInteger, decodeAsLong, decodeAsNull, decodeAsNumericString, decodeAsObjectIdentifier, decodeAsOctetString, decodeAsPrintableString, decodeAsSequence, decodeAsSet, decodeAsUTCTime, decodeAsUTF8String, encode, encodeLength, encodeTo, equals, equalsIgnoreType, getType, getTypeClass, getValue, getValueLength, hashCode, isConstructed, readFrom, readFrom, toString, writeTo

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

ASN1GeneralizedTime

public ASN1GeneralizedTime()

Creates a new generalized time element with the default BER type that represents the current time.

ASN1GeneralizedTime

public ASN1GeneralizedTime(byte type)

Creates a new generalized time element with the specified BER type that represents the current time.

Parameters:

type - The BER type to use for this element.

ASN1GeneralizedTime

public ASN1GeneralizedTime(@NotNull
                           java.util.Date date)

Creates a new generalized time element with the default BER type that represents the indicated time.

Parameters:

date - The date value that specifies the time to represent. This must not be null.

ASN1GeneralizedTime

public ASN1GeneralizedTime(byte type,
                           @NotNull
                           java.util.Date date)

Creates a new generalized time element with the specified BER type that represents the indicated time.

Parameters:

type - The BER type to use for this element.

date - The date value that specifies the time to represent. This must not be null.

ASN1GeneralizedTime

public ASN1GeneralizedTime(long time)

Creates a new generalized time element with the default BER type that represents the indicated time.

Parameters:

time - The time to represent. This must be expressed in milliseconds since the epoch (the same format used by System.currentTimeMillis() and Date.getTime()).

ASN1GeneralizedTime

public ASN1GeneralizedTime(byte type,
                           long time)

Creates a new generalized time element with the specified BER type that represents the indicated time.

Parameters:

type - The BER type to use for this element.

time - The time to represent. This must be expressed in milliseconds since the epoch (the same format used by System.currentTimeMillis() and Date.getTime()).

ASN1GeneralizedTime

public ASN1GeneralizedTime(@NotNull
                           java.lang.String timestamp)
                    throws ASN1Exception

Creates a new generalized time element with the default BER type and a time decoded from the provided string representation.

Parameters:

timestamp - The string representation of the timestamp to represent. This must not be null.

Throws:

ASN1Exception - If the provided timestamp does not represent a valid ASN.1 generalized time string representation.

ASN1GeneralizedTime

public ASN1GeneralizedTime(byte type,
                           @NotNull
                           java.lang.String timestamp)
                    throws ASN1Exception

Creates a new generalized time element with the specified BER type and a time decoded from the provided string representation.

Parameters:

type - The BER type to use for this element.

timestamp - The string representation of the timestamp to represent. This must not be null.

Throws:

ASN1Exception - If the provided timestamp does not represent a valid ASN.1 generalized time string representation.

Method Detail

encodeTimestamp

@NotNull
public static java.lang.String encodeTimestamp(@NotNull
                                                        java.util.Date date,
                                                        boolean includeMilliseconds)

Encodes the time represented by the provided date into the appropriate ASN.1 generalized time format.

Parameters:

date - The date value that specifies the time to represent. This must not be null.

includeMilliseconds - Indicate whether the timestamp should include a sub-second component representing a precision of up to milliseconds. Note that even if this is true, the sub-second component will only be included if it is not all zeroes. If this is false, then the resulting timestamp will only use a precision indicated in seconds, and the sub-second portion will be truncated rather than rounded to the nearest second (which is the behavior that SimpleDateFormat exhibits for formatting timestamps without a sub-second component).

Returns:

The encoded timestamp.

encodeTimestamp

@NotNull
public static java.lang.String encodeTimestamp(long time,
                                                        boolean includeMilliseconds)

Encodes the specified time into the appropriate ASN.1 generalized time format.

Parameters:

time - The time to represent. This must be expressed in milliseconds since the epoch (the same format used by System.currentTimeMillis() and Date.getTime()).

includeMilliseconds - Indicate whether the timestamp should include a sub-second component representing a precision of up to milliseconds. Note that even if this is true, the sub-second component will only be included if it is not all zeroes.

Returns:

The encoded timestamp.

decodeTimestamp

public static long decodeTimestamp(@NotNull
                                   java.lang.String timestamp)
                            throws ASN1Exception

Decodes the provided string as a timestamp in the generalized time format.

Parameters:

timestamp - The string representation of a generalized time to be parsed as a timestamp. It must not be null.

Returns:

The decoded time, expressed in milliseconds since the epoch (the same format used by System.currentTimeMillis() and Date.getTime()).

Throws:

ASN1Exception - If the provided timestamp cannot be parsed as a valid string representation of an ASN.1 generalized time value.

getTime

public long getTime()

Retrieves the time represented by this generalized time element, expressed as the number of milliseconds since the epoch (the same format used by System.currentTimeMillis() and Date.getTime()).

Returns:

The time represented by this generalized time element.

getDate

@NotNull
public java.util.Date getDate()

Retrieves a Date object that is set to the time represented by this generalized time element.

Returns:

A Date object that is set ot the time represented by this generalized time element.

getStringRepresentation

@NotNull
public java.lang.String getStringRepresentation()

Retrieves the string representation of the generalized time value contained in this element.

Returns:

The string representation of the generalized time value contained in this element.

decodeAsGeneralizedTime

@NotNull
public static ASN1GeneralizedTime decodeAsGeneralizedTime(@NotNull
                                                                   byte[] elementBytes)
                                                            throws ASN1Exception

Decodes the contents of the provided byte array as a generalized time element.

Parameters:

elementBytes - The byte array to decode as an ASN.1 generalized time element.

Returns:

The decoded ASN.1 generalized time element.

Throws:

ASN1Exception - If the provided array cannot be decoded as a generalized time element.

decodeAsGeneralizedTime

@NotNull
public static ASN1GeneralizedTime decodeAsGeneralizedTime(@NotNull
                                                                   ASN1Element element)
                                                            throws ASN1Exception

Decodes the provided ASN.1 element as a generalized time element.

Parameters:

element - The ASN.1 element to be decoded.

Returns:

The decoded ASN.1 generalized time element.

Throws:

ASN1Exception - If the provided element cannot be decoded as a generalized time element.

toString

public void toString(@NotNull
                     java.lang.StringBuilder buffer)

Appends a string representation of the value for this ASN.1 element to the provided buffer.

Overrides:

toString in class ASN1Element

Parameters:

buffer - The buffer to which to append the information.