com.unboundid.asn1

Class ASN1UTCTime

java.lang.Object

com.unboundid.asn1.ASN1Element

com.unboundid.asn1.ASN1UTCTime

All Implemented Interfaces:

java.io.Serializable

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

This class provides an ASN.1 UTC time element, which represents a timestamp with a string representation in the format "YYMMDDhhmmssZ". Although the general UTC time format considers the seconds element to be optional, the ASN.1 specification requires the element to be present.

Note that the UTC time format only allows two digits for the year, which is obviously prone to causing problems when deciding which century is implied by the timestamp. The official specification does not indicate which behavior should be used, so this implementation will use the same logic as Java's SimpleDateFormat class, which infers the century using a sliding window that assumes that the year is somewhere between 80 years before and 20 years after the current time. For example, if the current year is 2017, the following values would be inferred:

• A year of "40" would be interpreted as 1940.
• A year of "50" would be interpreted as 1950.
• A year of "60" would be interpreted as 1960.
• A year of "70" would be interpreted as 1970.
• A year of "80" would be interpreted as 1980.
• A year of "90" would be interpreted as 1990.
• A year of "00" would be interpreted as 2000.
• A year of "10" would be interpreted as 2010.
• A year of "20" would be interpreted as 2020.
• A year of "30" would be interpreted as 2030.

UTC time elements should generally only be used for historical purposes in encodings that require them. For new cases in which a timestamp may be required, you should use some other format to represent the timestamp. The ASN1GeneralizedTime element type does use a four-digit year (and also allows for the possibility of sub-second values), so it may be a good fit. You may also want to use a general-purpose string format like ASN1OctetString that is flexible enough to support whatever encoding you want.

See Also:

Serialized Form

Constructor Summary

Constructors

Constructor and Description
ASN1UTCTime() Creates a new UTC time element with the default BER type that represents the current time.
ASN1UTCTime(byte type) Creates a new UTC time element with the specified BER type that represents the current time.
ASN1UTCTime(byte type, java.util.Date date) Creates a new UTC time element with the specified BER type that represents the indicated time.
ASN1UTCTime(byte type, long time) Creates a new UTC time element with the specified BER type that represents the indicated time.
ASN1UTCTime(byte type, java.lang.String timestamp) Creates a new UTC time element with the specified BER type and a time decoded from the provided string representation.
ASN1UTCTime(java.util.Date date) Creates a new UTC time element with the default BER type that represents the indicated time.
ASN1UTCTime(long time) Creates a new UTC time element with the default BER type that represents the indicated time.
ASN1UTCTime(java.lang.String timestamp) Creates a new UTC 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 ASN1UTCTime	decodeAsUTCTime(ASN1Element element) Decodes the provided ASN.1 element as a UTC time element.
static ASN1UTCTime	decodeAsUTCTime(byte[] elementBytes) Decodes the contents of the provided byte array as a UTC time element.
static long	decodeTimestamp(java.lang.String timestamp) Decodes the provided string as a timestamp in the UTC time format.
static java.lang.String	encodeTimestamp(java.util.Date date) Encodes the time represented by the provided date into the appropriate ASN.1 UTC time format.
static java.lang.String	encodeTimestamp(long time) Encodes the specified time into the appropriate ASN.1 UTC time format.
java.util.Date	getDate() Retrieves a Date object that is set to the time represented by this UTC time element.
java.lang.String	getStringRepresentation() Retrieves the string representation of the UTC time value contained in this element.
long	getTime() Retrieves the time represented by this UTC 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

ASN1UTCTime

public ASN1UTCTime()

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

ASN1UTCTime

public ASN1UTCTime(byte type)

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

Parameters:

type - The BER type to use for this element.

ASN1UTCTime

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

Creates a new UTC 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. Note that the time that is actually represented by the element will have its milliseconds component set to zero.

ASN1UTCTime

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

Creates a new UTC 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. Note that the time that is actually represented by the element will have its milliseconds component set to zero.

ASN1UTCTime

public ASN1UTCTime(long time)

Creates a new UTC 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()). Note that the time that is actually represented by the element will have its milliseconds component set to zero.

ASN1UTCTime

public ASN1UTCTime(byte type,
                   long time)

Creates a new UTC 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()). Note that the time that is actually represented by the element will have its milliseconds component set to zero.

ASN1UTCTime

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

Creates a new UTC 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 UTC time string representation.

ASN1UTCTime

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

Creates a new UTC 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 UTC time string representation.

Method Detail

encodeTimestamp

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

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

Parameters:

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

Returns:

The encoded timestamp.

encodeTimestamp

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

Encodes the specified time into the appropriate ASN.1 UTC 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()).

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 UTC time format.

Parameters:

timestamp - The string representation of a UTC 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 UTC time value.

getTime

public long getTime()

Retrieves the time represented by this UTC 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 UTC time element.

getDate

@NotNull
public java.util.Date getDate()

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

Returns:

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

getStringRepresentation

@NotNull
public java.lang.String getStringRepresentation()

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

Returns:

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

decodeAsUTCTime

@NotNull
public static ASN1UTCTime decodeAsUTCTime(@NotNull
                                                   byte[] elementBytes)
                                            throws ASN1Exception

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

Parameters:

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

Returns:

The decoded ASN.1 UTC time element.

Throws:

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

decodeAsUTCTime

@NotNull
public static ASN1UTCTime decodeAsUTCTime(@NotNull
                                                   ASN1Element element)
                                            throws ASN1Exception

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

Parameters:

element - The ASN.1 element to be decoded.

Returns:

The decoded ASN.1 UTC time element.

Throws:

ASN1Exception - If the provided element cannot be decoded as a UTC 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.