Package org.forgerock.opendj.io

Class Asn1Reader

java.lang.Object

org.forgerock.opendj.io.Asn1Reader

All Implemented Interfaces:

Closeable, AutoCloseable

public final class Asn1Reader
extends Object
implements Closeable

An interface for decoding ASN.1 elements from a data source.

Methods for creating Asn1Readers are provided in the Asn1 class.

Method Summary

Modifier and Type	Method	Description
void	close()	Reads the end of the current ASN.1 sequence, set or explicit tag, or closes the underlying input if the reader is not reading a sequence.
boolean	elementAvailable()	Indicates whether the next element can be read without blocking.
boolean	hasNextElement()	Indicates whether the current stream, sequence, or set contains another element.
int	peekLength()	Returns the length of the next element without actually reading it.
byte	peekType()	Returns the single byte type of the next element without actually reading it.
long	peekTypeMultiByte()	Returns the possibly multi-byte type of the next element without actually reading it.
ByteString	readAsn1Element()	Reads the next element and returns its full encoding, which includes tag and length bytes.
ByteStringBuilder	readAsn1Element(ByteStringBuilder builder)	Reads the next element and appends its full encoding, which includes tag and length bytes, to the provided ByteStringBuilder.
ByteString	readBitString()	Reads the next element as a bit string having the Universal Bit String ASN.1 type tag.
ByteString	readBitString(byte type)	Reads the next element as a bit string having the provided type tag.
boolean	readBoolean()	Reads the next element as a boolean having the Universal Boolean ASN.1 type tag.
boolean	readBoolean(byte type)	Reads the next element as a boolean having the provided type tag.
int	readEnumerated()	Reads the next element as an enumerated having the Universal Enumerated ASN.1 type tag.
int	readEnumerated(byte type)	Reads the next element as an enumerated having the provided type tag.
Asn1Reader	readExplicitTag()	Reads the next element as an explicit tag ignoring the ASN.1 type tag.
Asn1Reader	readExplicitTag(byte type)	Reads the next element as an explicit tag having the provided tag type.
Asn1Reader	readExplicitTag(long type)	Reads the next element as an explicit tag having the provided multi-byte tag type encoded as described in Asn1Tag.numberMultiByte(long).
long	readInteger()	Reads the next element as an integer having the Universal Integer ASN.1 type tag.
long	readInteger(byte type)	Reads the next element as an integer having the provided type tag.
BigInteger	readIntegerAsBigInteger()	Reads the next element as a BigInteger having the Universal Integer ASN.1 type tag.
BigInteger	readIntegerAsBigInteger(byte type)	Reads the next element as a BigInteger having the provided type tag.
Dn	readName(byte type, Schema schema)	Reads the next element as a distinguished name having the provided type tag.
Dn	readName(Schema schema)	Reads the next element as a distinguished name having the Universal Sequence ASN.1 type tag.
void	readNull()	Reads the next element as a null element having the Universal Null ASN.1 type tag.
void	readNull(byte type)	Reads the next element as a null element having the provided type tag.
String	readObjectIdentifier()	Reads the next element as an object identifier (OID) having the Universal Object Identifier ASN.1 type tag.
String	readObjectIdentifier(byte type)	Reads the next element as an object identifier (OID) having the provided type tag.
ByteString	readOctetString()	Reads the next element as an octet string having any tag.
ByteString	readOctetString(byte type)	Reads the next element as an octet string having the provided type tag.
ByteStringBuilder	readOctetString(byte type, ByteStringBuilder builder)	Reads the next element as an octet string having the provided type tag and appends it to the provided ByteStringBuilder.
ByteStringBuilder	readOctetString(ByteStringBuilder builder)	Reads the next element as an octet string having the Universal Octet String ASN.1 type tag and appends it to the provided ByteStringBuilder.
String	readOctetStringAsString()	Reads the next element as an octet string having the Universal Octet String ASN.1 type tag and decodes the value as a UTF-8 encoded string.
String	readOctetStringAsString(byte type)	Reads the next element as an octet string having the provided type tag and decodes the value as a UTF-8 encoded string.
Asn1Reader	readSequence()	Reads the next element as a sequence having the Universal Sequence ASN.1 type tag.
Asn1Reader	readSequence(byte type)	Reads the next element as a sequence having the provided type tag.
Asn1Reader	readSet()	Reads the next element as a set having the Universal Set ASN.1 type tag.
Asn1Reader	readSet(byte type)	Reads the next element as a set having the provided type tag.
Asn1Reader	skipElement()	Skips the next element without decoding it.
Asn1Reader	skipElement(byte type)	Skips the next element having the provided type tag without decoding it.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

close

public void close()
           throws IOException

Reads the end of the current ASN.1 sequence, set or explicit tag, or closes the underlying input if the reader is not reading a sequence. Any remaining data in the current sequence will be skipped.

Specified by:

close in interface AutoCloseable

Specified by:

close in interface Closeable

Throws:

IOException - If an error occurs while closing.

elementAvailable

public boolean elementAvailable()
                         throws IOException

Indicates whether the next element can be read without blocking.

Returns:

true if a complete element is available or false otherwise.

Throws:

DecodeException - If the available data was not valid ASN.1.

IOException - If an unexpected IO error occurred.

hasNextElement

public boolean hasNextElement()
                       throws IOException

Indicates whether the current stream, sequence, or set contains another element. Note that this method may return true even if a previous call to elementAvailable() returned false, indicating that the current set or sequence contains another element but an attempt to read that element may block. This method will block if there is not enough data available to make the determination (typically only the next element's type is required).

Returns:

true if the current stream, sequence, or set contains another element, or false if the end of the stream, sequence, or set has been reached.

Throws:

DecodeException - If the available data was not valid ASN.1.

IOException - If an unexpected IO error occurred.

peekLength

public int peekLength()
               throws IOException

Returns the length of the next element without actually reading it.

Returns:

The length of the next element, zero or positive.

Throws:

DecodeException - If EOF was reached when reading the length or if the length bytes are invalid ASN.1.

IOException - If an unexpected IO error occurred.

peekType

public byte peekType()
              throws IOException

Returns the single byte type of the next element without actually reading it. If the next element has a multi-byte type (number greater than 30) then this method will only return the first byte of the encoded type which contains the class and form bits. In other words, use this method when the ASN.1 schema indicates that the expected type is between 0 and 30 inclusive, otherwise use peekTypeMultiByte() for the very rare cases involving types greater than 30.

Returns:

The single byte type of the next element.

Throws:

DecodeException - If EOF was reached when reading the type, or the multi-byte type contained more than 8 bytes, or if the type was invalid ASN.1.

IOException - If an unexpected IO error occurred.

peekTypeMultiByte

public long peekTypeMultiByte()
                       throws IOException

Returns the possibly multi-byte type of the next element without actually reading it. The returned type is encoded as a long as described in Asn1Tag.numberMultiByte(long). This implementation only supports multi-byte types containing up to 8 bytes. Bigger types will result in a DecodeException.

Returns:

The possibly multi-byte type of the next element.

Throws:

DecodeException - If EOF was reached when reading the type, or the multi-byte type contained more than 8 bytes, or if the type was invalid ASN.1.

IOException - If an unexpected IO error occurred.

readAsn1Element

public ByteString readAsn1Element()
                           throws IOException

Reads the next element and returns its full encoding, which includes tag and length bytes.

Returns:

The full encoding of the next element.

Throws:

IOException - If an unexpected IO error occurred.

readAsn1Element

public ByteStringBuilder readAsn1Element(ByteStringBuilder builder)
                                  throws IOException

Reads the next element and appends its full encoding, which includes tag and length bytes, to the provided ByteStringBuilder.

Parameters:

builder - The ByteStringBuilder to append the ASN.1 element to.

Returns:

A reference to builder.

Throws:

IOException - If an unexpected IO error occurred.

readIntegerAsBigInteger

public BigInteger readIntegerAsBigInteger()
                                   throws IOException

Reads the next element as a BigInteger having the Universal Integer ASN.1 type tag.

Returns:

The decoded BigInteger value.

Throws:

DecodeException - If the element cannot be decoded as a BigInteger.

IOException - If an unexpected IO error occurred.

readIntegerAsBigInteger

public BigInteger readIntegerAsBigInteger(byte type)
                                   throws IOException

Reads the next element as a BigInteger having the provided type tag.

Parameters:

type - The expected type tag of the element.

Returns:

The decoded BigInteger value.

Throws:

DecodeException - If the element cannot be decoded as a BigInteger.

IOException - If an unexpected IO error occurred.

readBitString

public ByteString readBitString()
                         throws IOException

Reads the next element as a bit string having the Universal Bit String ASN.1 type tag. The returned value will be padded with zeros.

Returns:

The decoded bit string value padded with zeros.

Throws:

DecodeException - If the element cannot be decoded as a bit string.

IOException - If an unexpected IO error occurred.

readBitString

public ByteString readBitString(byte type)
                         throws IOException

Reads the next element as a bit string having the provided type tag. The returned value will be padded with zeros.

Parameters:

type - The expected type tag of the element.

Returns:

The decoded bit string value padded with zeros.

Throws:

DecodeException - If the element cannot be decoded as a bit string.

IOException - If an unexpected IO error occurred.

readBoolean

public boolean readBoolean()
                    throws IOException

Reads the next element as a boolean having the Universal Boolean ASN.1 type tag.

Returns:

The decoded boolean value.

Throws:

DecodeException - If the element cannot be decoded as a boolean.

IOException - If an unexpected IO error occurred.

readBoolean

public boolean readBoolean(byte type)
                    throws IOException

Reads the next element as a boolean having the provided type tag.

Parameters:

type - The expected type tag of the element.

Returns:

The decoded boolean value.

Throws:

DecodeException - If the element cannot be decoded as a boolean.

IOException - If an unexpected IO error occurred.

readEnumerated

public int readEnumerated()
                   throws IOException

Reads the next element as an enumerated having the Universal Enumerated ASN.1 type tag.

Returns:

The decoded enumerated value.

Throws:

DecodeException - If the element cannot be decoded as an enumerated value.

IOException - If an unexpected IO error occurred.

readEnumerated

public int readEnumerated(byte type)
                   throws IOException

Reads the next element as an enumerated having the provided type tag.

Parameters:

type - The expected type tag of the element.

Returns:

The decoded enumerated value.

Throws:

DecodeException - If the element cannot be decoded as an enumerated value.

IOException - If an unexpected IO error occurred.

readInteger

public long readInteger()
                 throws IOException

Reads the next element as an integer having the Universal Integer ASN.1 type tag.

Returns:

The decoded integer value.

Throws:

DecodeException - If the element cannot be decoded as an integer.

IOException - If an unexpected IO error occurred.

readInteger

public long readInteger(byte type)
                 throws IOException

Reads the next element as an integer having the provided type tag.

Parameters:

type - The expected type tag of the element.

Returns:

The decoded integer value.

Throws:

DecodeException - If the element cannot be decoded as an integer.

IOException - If an unexpected IO error occurred.

readName

public Dn readName(Schema schema)
            throws IOException

Reads the next element as a distinguished name having the Universal Sequence ASN.1 type tag.

Parameters:

schema - The schema which should be used when decoding the distinguished name.

Returns:

The decoded distinguished name value.

Throws:

DecodeException - If the element cannot be decoded as a distinguished name.

IOException - If an unexpected IO error occurred.

readName

public Dn readName(byte type,
                   Schema schema)
            throws IOException

Reads the next element as a distinguished name having the provided type tag.

Parameters:

type - The expected type tag of the element.

schema - The schema which should be used when decoding the distinguished name.

Returns:

The decoded distinguished name value.

Throws:

DecodeException - If the element cannot be decoded as a distinguished name.

IOException - If an unexpected IO error occurred.

readObjectIdentifier

public String readObjectIdentifier()
                            throws IOException

Reads the next element as an object identifier (OID) having the Universal Object Identifier ASN.1 type tag.

Returns:

The decoded object identifier value.

Throws:

DecodeException - If the element cannot be decoded as an object identifier.

IOException - If an unexpected IO error occurred.

readObjectIdentifier

public String readObjectIdentifier(byte type)
                            throws IOException

Reads the next element as an object identifier (OID) having the provided type tag.

Parameters:

type - The expected type tag of the element.

Returns:

The decoded object identifier value.

Throws:

DecodeException - If the element cannot be decoded as an object identifier.

IOException - If an unexpected IO error occurred.

readNull

public void readNull()
              throws IOException

Reads the next element as a null element having the Universal Null ASN.1 type tag.

Throws:

DecodeException - If the element cannot be decoded as a null element.

IOException - If an unexpected IO error occurred.

readNull

public void readNull(byte type)
              throws IOException

Reads the next element as a null element having the provided type tag.

Parameters:

type - The expected type tag of the element.

Throws:

DecodeException - If the element cannot be decoded as a null element.

IOException - If an unexpected IO error occurred.

readOctetString

public ByteString readOctetString()
                           throws IOException

Reads the next element as an octet string having any tag.

Returns:

The decoded octet string represented using a ByteString.

Throws:

DecodeException - If the element cannot be decoded as an octet string.

IOException - If an unexpected IO error occurred.

readOctetString

public ByteStringBuilder readOctetString(ByteStringBuilder builder)
                                  throws IOException

Reads the next element as an octet string having the Universal Octet String ASN.1 type tag and appends it to the provided ByteStringBuilder.

Parameters:

builder - The ByteStringBuilder to append the octet string to.

Returns:

A reference to builder.

Throws:

DecodeException - If the element cannot be decoded as an octet string.

IOException - If an unexpected IO error occurred.

readOctetString

public ByteString readOctetString(byte type)
                           throws IOException

Reads the next element as an octet string having the provided type tag.

Parameters:

type - The expected type tag of the element.

Returns:

The decoded octet string represented using a ByteString.

Throws:

DecodeException - If the element cannot be decoded as an octet string.

IOException - If an unexpected IO error occurred.

readOctetString

public ByteStringBuilder readOctetString(byte type,
                                         ByteStringBuilder builder)
                                  throws IOException

Reads the next element as an octet string having the provided type tag and appends it to the provided ByteStringBuilder.

Parameters:

type - The expected type tag of the element.

builder - The ByteStringBuilder to append the octet string to.

Returns:

A reference to builder.

Throws:

DecodeException - If the element cannot be decoded as an octet string.

IOException - If an unexpected IO error occurred.

readOctetStringAsString

public String readOctetStringAsString()
                               throws IOException

Reads the next element as an octet string having the Universal Octet String ASN.1 type tag and decodes the value as a UTF-8 encoded string.

Returns:

The decoded octet string as a UTF-8 encoded string.

Throws:

DecodeException - If the element cannot be decoded as an octet string.

IOException - If an unexpected IO error occurred.

readOctetStringAsString

public String readOctetStringAsString(byte type)
                               throws IOException

Reads the next element as an octet string having the provided type tag and decodes the value as a UTF-8 encoded string.

Parameters:

type - The expected type tag of the element.

Returns:

The decoded octet string as a UTF-8 encoded string.

Throws:

DecodeException - If the element cannot be decoded as an octet string.

IOException - If an unexpected IO error occurred.

readExplicitTag

public Asn1Reader readExplicitTag()
                           throws IOException

Reads the next element as an explicit tag ignoring the ASN.1 type tag. The returned ASN.1 reader must be closed once the value for the tag has been read.

Returns:

An ASN.1 reader representing the tag which must be closed once the value for the tag has been read.

Throws:

DecodeException - If the element cannot be decoded as an explicit tag.

IOException - If an unexpected IO error occurred.

readExplicitTag

public Asn1Reader readExplicitTag(byte type)
                           throws IOException

Reads the next element as an explicit tag having the provided tag type. The returned ASN.1 reader must be closed once the value for the tag has been read.

Parameters:

type - The expected type tag of the element.

Returns:

An ASN.1 reader representing the tag which must be closed once the value for the tag has been read.

Throws:

DecodeException - If the element cannot be decoded as an explicit tag having the expected type.

IOException - If an unexpected IO error occurred.

readExplicitTag

public Asn1Reader readExplicitTag(long type)
                           throws IOException

Reads the next element as an explicit tag having the provided multi-byte tag type encoded as described in Asn1Tag.numberMultiByte(long). The returned ASN.1 reader must be closed once the value for the tag has been read.

Parameters:

type - The expected type tag of the element, encoded as described in Asn1Tag.numberMultiByte(long).

Returns:

An ASN.1 reader representing the tag which must be closed once the value for the tag has been read.

Throws:

DecodeException - If the element cannot be decoded as an explicit tag having the expected type.

IOException - If an unexpected IO error occurred.

readSequence

public Asn1Reader readSequence()
                        throws IOException

Reads the next element as a sequence having the Universal Sequence ASN.1 type tag. The returned ASN.1 reader must be closed once the sequence elements have been read.

Returns:

An ASN.1 reader representing the sequence which must be closed once the sequence elements have been read.

Throws:

DecodeException - If the element cannot be decoded as a sequence.

IOException - If an unexpected IO error occurred.

readSequence

public Asn1Reader readSequence(byte type)
                        throws IOException

Reads the next element as a sequence having the provided type tag. The returned ASN.1 reader must be closed once the sequence elements have been read.

Parameters:

type - The expected type tag of the element.

Returns:

An ASN.1 reader representing the sequence which must be closed once the sequence elements have been read.

Throws:

DecodeException - If the element cannot be decoded as a sequence.

IOException - If an unexpected IO error occurred.

readSet

public Asn1Reader readSet()
                   throws IOException

Reads the next element as a set having the Universal Set ASN.1 type tag. The returned ASN.1 reader must be closed once the set elements have been read.

Returns:

An ASN.1 reader representing the set which must be closed once the set elements have been read.

Throws:

DecodeException - If the element cannot be decoded as a set.

IOException - If an unexpected IO error occurred.

readSet

public Asn1Reader readSet(byte type)
                   throws IOException

Reads the next element as a set having the provided type tag. The returned ASN.1 reader must be closed once the set elements have been read.

Parameters:

type - The expected type tag of the element.

Returns:

An ASN.1 reader representing the set which must be closed once the set elements have been read.

Throws:

DecodeException - If the element cannot be decoded as a set.

IOException - If an unexpected IO error occurred.

skipElement

public Asn1Reader skipElement()
                       throws IOException

Skips the next element without decoding it.

Returns:

A reference to this ASN.1 reader.

Throws:

DecodeException - If the next element could not be skipped.

IOException - If an unexpected IO error occurred.

skipElement

public Asn1Reader skipElement(byte type)
                       throws IOException

Skips the next element having the provided type tag without decoding it.

Parameters:

type - The expected type tag of the element.

Returns:

A reference to this ASN.1 reader.

Throws:

DecodeException - If the next element does not have the provided type tag.

IOException - If an unexpected IO error occurred.