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 Details

    • 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.