com.unboundid.asn1

Class ASN1Element

java.lang.Object

com.unboundid.asn1.ASN1Element

All Implemented Interfaces:

java.io.Serializable

Direct Known Subclasses:

ASN1BigInteger, ASN1BitString, ASN1Boolean, ASN1Enumerated, ASN1GeneralizedTime, ASN1IA5String, ASN1Integer, ASN1Long, ASN1Null, ASN1NumericString, ASN1ObjectIdentifier, ASN1OctetString, ASN1PrintableString, ASN1Sequence, ASN1Set, ASN1UTCTime, ASN1UTF8String

@NotExtensible
 @NotMutable
 @ThreadSafety(level=COMPLETELY_THREADSAFE)
public class ASN1Element
extends java.lang.Object
implements java.io.Serializable

This class defines a generic ASN.1 BER element, which has a type and value. It provides a framework for encoding and decoding BER elements, both as generic elements and more specific subtypes.

See Also:

Serialized Form

Constructor Summary

Constructors

Constructor and Description
ASN1Element(byte type) Creates a new ASN.1 BER element with the specified type and no value.
ASN1Element(byte type, byte[] value) Creates a new ASN1 BER element with the specified type and value.
ASN1Element(byte type, byte[] value, int offset, int length) Creates a new ASN1 BER element with the specified type and value.

Method Summary

Modifier and Type	Method and Description
static ASN1Element	decode(byte[] elementBytes) Decodes the content in the provided byte array as an ASN.1 element.
ASN1BigInteger	decodeAsBigInteger() Decodes this ASN.1 element as a big integer element.
ASN1BitString	decodeAsBitString() Decodes this ASN.1 element as a bit string element.
ASN1Boolean	decodeAsBoolean() Decodes this ASN.1 element as a Boolean element.
ASN1Enumerated	decodeAsEnumerated() Decodes this ASN.1 element as an enumerated element.
ASN1GeneralizedTime	decodeAsGeneralizedTime() Decodes this ASN.1 element as a generalized time element.
ASN1IA5String	decodeAsIA5String() Decodes this ASN.1 element as an IA5 string element.
ASN1Integer	decodeAsInteger() Decodes this ASN.1 element as an integer element.
ASN1Long	decodeAsLong() Decodes this ASN.1 element as a long element.
ASN1Null	decodeAsNull() Decodes this ASN.1 element as a null element.
ASN1NumericString	decodeAsNumericString() Decodes this ASN.1 element as a numeric string element.
ASN1ObjectIdentifier	decodeAsObjectIdentifier() Decodes this ASN.1 element as an object identifier element.
ASN1OctetString	decodeAsOctetString() Decodes this ASN.1 element as an octet string element.
ASN1PrintableString	decodeAsPrintableString() Decodes this ASN.1 element as a printable string element.
ASN1Sequence	decodeAsSequence() Decodes this ASN.1 element as a sequence element.
ASN1Set	decodeAsSet() Decodes this ASN.1 element as a set element.
ASN1UTCTime	decodeAsUTCTime() Decodes this ASN.1 element as a UTC time element.
ASN1UTF8String	decodeAsUTF8String() Decodes this ASN.1 element as a UTF-8 string element.
byte[]	encode() Encodes this ASN.1 element to a byte array.
static byte[]	encodeLength(int length) Encodes the provided length to a byte array.
void	encodeTo(ByteStringBuffer buffer) Appends an encoded representation of this ASN.1 element to the provided buffer.
boolean	equals(java.lang.Object o) Indicates whether the provided object is equal to this ASN.1 BER element.
boolean	equalsIgnoreType(ASN1Element element) Indicates whether the provided ASN.1 element is equal to this element, ignoring any potential difference in the BER type.
byte	getType() Retrieves the BER type for this element.
byte	getTypeClass() Retrieves a value that corresponds to the type class for this element.
byte[]	getValue() Retrieves the encoded value for this element.
int	getValueLength() Retrieves the number of bytes contained in the value.
int	hashCode() Retrieves a hash code for this ASN.1 BER element.
boolean	isConstructed() Indicates whether the type indicates that this element is constructed.
static ASN1Element	readFrom(java.io.InputStream inputStream) Reads an ASN.1 element from the provided input stream.
static ASN1Element	readFrom(java.io.InputStream inputStream, int maxSize) Reads an ASN.1 element from the provided input stream.
java.lang.String	toString() Retrieves a string representation of the value for ASN.1 element.
void	toString(java.lang.StringBuilder buffer) Appends a string representation of the value for this ASN.1 element to the provided buffer.
int	writeTo(java.io.OutputStream outputStream) Writes an encoded representation of this ASN.1 element to the provided output stream.

Methods inherited from class java.lang.Object

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

Constructor Detail

ASN1Element

public ASN1Element(byte type)

Creates a new ASN.1 BER element with the specified type and no value.

Parameters:

type - The BER type for this element.

ASN1Element

public ASN1Element(byte type,
                   @Nullable
                   byte[] value)

Creates a new ASN1 BER element with the specified type and value.

Parameters:

type - The BER type for this element.

value - The encoded value for this element.

ASN1Element

public ASN1Element(byte type,
                   @NotNull
                   byte[] value,
                   int offset,
                   int length)

Creates a new ASN1 BER element with the specified type and value.

Parameters:

type - The BER type for this element.

value - The array containing the encoded value for this element. It must not be null.

offset - The offset within the array at which the value begins.

length - The number of bytes contained in the value.

Method Detail

getType

public final byte getType()

Retrieves the BER type for this element.

Returns:

The BER type for this element.

getTypeClass

public byte getTypeClass()

Retrieves a value that corresponds to the type class for this element. The value returned will be one of ASN1Constants.TYPE_MASK_UNIVERSAL_CLASS, ASN1Constants.TYPE_MASK_APPLICATION_CLASS, ASN1Constants.TYPE_MASK_CONTEXT_SPECIFIC_CLASS, or ASN1Constants.TYPE_MASK_PRIVATE_CLASS.

Returns:

A value that corresponds to the type class for this element.

isConstructed

public boolean isConstructed()

Indicates whether the type indicates that this element is constructed. A constructed element is one whose value is comprised of the encoded representation of zero or more ASN.1 elements. If the type does not indicate that the element is constructed, then the element is considered primitive.

Returns:

true if the type indicates that the element is constructed, or false if the type indicates that the element is primitive.

getValueLength

public int getValueLength()

Retrieves the number of bytes contained in the value.

Returns:

The number of bytes contained in the value.

getValue

@NotNull
public byte[] getValue()

Retrieves the encoded value for this element.

Returns:

The encoded value for this element.

encode

@NotNull
public final byte[] encode()

Encodes this ASN.1 element to a byte array.

Returns:

A byte array containing the encoded representation of this ASN.1 element.

encodeTo

public void encodeTo(@NotNull
                     ByteStringBuffer buffer)

Appends an encoded representation of this ASN.1 element to the provided buffer.

Parameters:

buffer - The buffer to which the encoded representation should be appended.

encodeLength

@NotNull
public static byte[] encodeLength(int length)

Encodes the provided length to a byte array.

Parameters:

length - The length to be encoded.

Returns:

A byte array containing the encoded length.

decode

@NotNull
public static ASN1Element decode(@NotNull
                                          byte[] elementBytes)
                                   throws ASN1Exception

Decodes the content in the provided byte array as an ASN.1 element.

Parameters:

elementBytes - The byte array containing the data to decode.

Returns:

The decoded ASN.1 BER element.

Throws:

ASN1Exception - If the provided byte array does not represent a valid ASN.1 element.

decodeAsBitString

@NotNull
public final ASN1BitString decodeAsBitString()
                                               throws ASN1Exception

Decodes this ASN.1 element as a bit string element.

Returns:

The decoded bit string element.

Throws:

ASN1Exception - If this element cannot be decoded as a bit string element.

decodeAsBoolean

@NotNull
public final ASN1Boolean decodeAsBoolean()
                                           throws ASN1Exception

Decodes this ASN.1 element as a Boolean element.

Returns:

The decoded Boolean element.

Throws:

ASN1Exception - If this element cannot be decoded as a Boolean element.

decodeAsEnumerated

@NotNull
public final ASN1Enumerated decodeAsEnumerated()
                                                 throws ASN1Exception

Decodes this ASN.1 element as an enumerated element.

Returns:

The decoded enumerated element.

Throws:

ASN1Exception - If this element cannot be decoded as an enumerated element.

decodeAsGeneralizedTime

@NotNull
public final ASN1GeneralizedTime decodeAsGeneralizedTime()
                                                           throws ASN1Exception

Decodes this ASN.1 element as a generalized time element.

Returns:

The decoded generalized time element.

Throws:

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

decodeAsIA5String

@NotNull
public final ASN1IA5String decodeAsIA5String()
                                               throws ASN1Exception

Decodes this ASN.1 element as an IA5 string element.

Returns:

The decoded IA5 string element.

Throws:

ASN1Exception - If this element cannot be decoded as a IA5 string element.

decodeAsInteger

@NotNull
public final ASN1Integer decodeAsInteger()
                                           throws ASN1Exception

Decodes this ASN.1 element as an integer element.

Returns:

The decoded integer element.

Throws:

ASN1Exception - If this element cannot be decoded as an integer element.

decodeAsLong

@NotNull
public final ASN1Long decodeAsLong()
                                     throws ASN1Exception

Decodes this ASN.1 element as a long element.

Returns:

The decoded long element.

Throws:

ASN1Exception - If this element cannot be decoded as a long element.

decodeAsBigInteger

@NotNull
public final ASN1BigInteger decodeAsBigInteger()
                                                 throws ASN1Exception

Decodes this ASN.1 element as a big integer element.

Returns:

The decoded big integer element.

Throws:

ASN1Exception - If this element cannot be decoded as a big integer element.

decodeAsNull

@NotNull
public final ASN1Null decodeAsNull()
                                     throws ASN1Exception

Decodes this ASN.1 element as a null element.

Returns:

The decoded null element.

Throws:

ASN1Exception - If this element cannot be decoded as a null element.

decodeAsNumericString

@NotNull
public final ASN1NumericString decodeAsNumericString()
                                                       throws ASN1Exception

Decodes this ASN.1 element as a numeric string element.

Returns:

The decoded numeric string element.

Throws:

ASN1Exception - If this element cannot be decoded as a numeric string element.

decodeAsObjectIdentifier

@NotNull
public final ASN1ObjectIdentifier decodeAsObjectIdentifier()
                                                             throws ASN1Exception

Decodes this ASN.1 element as an object identifier element.

Returns:

The decoded object identifier element.

Throws:

ASN1Exception - If this element cannot be decoded as an object identifier element.

decodeAsOctetString

@NotNull
public final ASN1OctetString decodeAsOctetString()

Decodes this ASN.1 element as an octet string element.

Returns:

The decoded octet string element.

decodeAsPrintableString

@NotNull
public final ASN1PrintableString decodeAsPrintableString()
                                                           throws ASN1Exception

Decodes this ASN.1 element as a printable string element.

Returns:

The decoded printable string element.

Throws:

ASN1Exception - If this element cannot be decoded as a printable string element.

decodeAsSequence

@NotNull
public final ASN1Sequence decodeAsSequence()
                                             throws ASN1Exception

Decodes this ASN.1 element as a sequence element.

Returns:

The decoded sequence element.

Throws:

ASN1Exception - If this element cannot be decoded as a sequence element.

decodeAsSet

@NotNull
public final ASN1Set decodeAsSet()
                                   throws ASN1Exception

Decodes this ASN.1 element as a set element.

Returns:

The decoded set element.

Throws:

ASN1Exception - If this element cannot be decoded as a set element.

decodeAsUTCTime

@NotNull
public final ASN1UTCTime decodeAsUTCTime()
                                           throws ASN1Exception

Decodes this ASN.1 element as a UTC time element.

Returns:

The decoded UTC time element.

Throws:

ASN1Exception - If this element cannot be decoded as a UTC time element.

decodeAsUTF8String

@NotNull
public final ASN1UTF8String decodeAsUTF8String()
                                                 throws ASN1Exception

Decodes this ASN.1 element as a UTF-8 string element.

Returns:

The decoded UTF_8 string element.

Throws:

ASN1Exception - If this element cannot be decoded as a UTF-8 string element.

readFrom

@Nullable
public static ASN1Element readFrom(@NotNull
                                             java.io.InputStream inputStream)
                                      throws java.io.IOException,
                                             ASN1Exception

Reads an ASN.1 element from the provided input stream.

Parameters:

inputStream - The input stream from which to read the element.

Returns:

The element read from the input stream, or null if the end of the input stream is reached without reading any data.

Throws:

java.io.IOException - If a problem occurs while attempting to read from the input stream.

ASN1Exception - If a problem occurs while attempting to decode the element.

readFrom

@Nullable
public static ASN1Element readFrom(@NotNull
                                             java.io.InputStream inputStream,
                                             int maxSize)
                                      throws java.io.IOException,
                                             ASN1Exception

Reads an ASN.1 element from the provided input stream.

Parameters:

inputStream - The input stream from which to read the element.

maxSize - The maximum value size in bytes that will be allowed. A value less than or equal to zero indicates that no maximum size should be enforced. An attempt to read an element with a value larger than this will cause an ASN1Exception to be thrown.

Returns:

The element read from the input stream, or null if the end of the input stream is reached without reading any data.

Throws:

java.io.IOException - If a problem occurs while attempting to read from the input stream.

ASN1Exception - If a problem occurs while attempting to decode the element.

writeTo

public final int writeTo(@NotNull
                         java.io.OutputStream outputStream)
                  throws java.io.IOException

Writes an encoded representation of this ASN.1 element to the provided output stream.

Parameters:

outputStream - The output stream to which the element should be written.

Returns:

The total number of bytes written to the output stream.

Throws:

java.io.IOException - If a problem occurs while attempting to write to the provided output stream.

See Also:

ASN1Writer.writeElement(ASN1Element,OutputStream)

hashCode

public final int hashCode()

Retrieves a hash code for this ASN.1 BER element.

Overrides:

hashCode in class java.lang.Object

Returns:

A hash code for this ASN.1 BER element.

equals

public final boolean equals(@Nullable
                            java.lang.Object o)

Indicates whether the provided object is equal to this ASN.1 BER element. The object will only be considered equal to this ASN.1 element if it is a non-null ASN.1 element with the same type and value as this element.

Overrides:

equals in class java.lang.Object

Parameters:

o - The object for which to make the determination.

Returns:

true if the provided object is considered equal to this ASN.1 element, or false if not.

equalsIgnoreType

public final boolean equalsIgnoreType(@Nullable
                                      ASN1Element element)

Indicates whether the provided ASN.1 element is equal to this element, ignoring any potential difference in the BER type.

Parameters:

element - The ASN.1 BER element for which to make the determination.

Returns:

true if the provided ASN.1 element is considered equal to this element (ignoring type differences), or false if not.

toString

@NotNull
public final java.lang.String toString()

Retrieves a string representation of the value for ASN.1 element.

Overrides:

toString in class java.lang.Object

Returns:

A string representation of the value for this ASN.1 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.

Parameters:

buffer - The buffer to which to append the information.