Package com.unboundid.asn1

Class ASN1StreamReader

java.lang.Object
com.unboundid.asn1.ASN1StreamReader
All Implemented Interfaces:
Closeable, AutoCloseable
@Mutable @ThreadSafety(level=NOT_THREADSAFE) public final class ASN1StreamReader extends Object implements Closeable
This class provides a mechanism for ASN.1 elements (including sequences and sets) from an input stream in a manner that allows the data to be decoded on the fly without constructing ASN1Element objects if they are not needed. If any method in this class throws an IOException, then the caller must close this reader and must not attempt to use it any more. ASN1StreamReader instances are not threadsafe and must not be accessed concurrently by multiple threads.

  • Constructor Summary

    Constructors
    Constructor
    Description
    ASN1StreamReader(InputStream inputStream)
    Creates a new ASN.1 stream reader that will read data from the provided input stream.
    ASN1StreamReader(InputStream inputStream, int maxElementSize)
    Creates a new ASN.1 stream reader that will read data from the provided input stream.

  • Method Summary

    Modifier and Type
    Method
    Description
    ASN1StreamReaderSequence
    beginSequence()
    Reads the beginning of an ASN.1 sequence from the input stream and returns a value that can be used to determine when the end of the sequence has been reached.
    ASN1StreamReaderSet
    beginSet()
    Reads the beginning of an ASN.1 set from the input stream and returns a value that can be used to determine when the end of the set has been reached.
    void
    close()
    Closes this ASN.1 stream reader and the underlying input stream.
    boolean
    ignoreInitialSocketTimeoutException()
    Indicates whether to ignore java.net.SocketTimeoutException exceptions that may be caught while trying to read the first byte of an element.
    boolean
    ignoreSocketTimeoutException()
    Deprecated.
    Use the ignoreInitialSocketTimeoutException() and ignoreSubsequentSocketTimeoutException() methods instead.
    boolean
    ignoreSubsequentSocketTimeoutException()
    Indicates whether to ignore java.net.SocketTimeoutException exceptions that may be caught while trying to read subsequent bytes of an element (after one or more bytes have already been read for that element).
    int
    peek()
    Peeks at the next byte to be read from the input stream without actually consuming it.
    BigInteger
    readBigInteger()
    Reads an ASN.1 integer element from the input stream and returns the value as a BigInteger.
    Boolean
    readBoolean()
    Reads an ASN.1 Boolean element from the input stream and returns the value as a Boolean.
    byte[]
    readBytes()
    Reads an ASN.1 octet string element from the input stream and returns the value as a byte array.
    ASN1Element
    readElement()
    Reads a complete ASN.1 element from the input stream.
    Integer
    readEnumerated()
    Reads an ASN.1 enumerated element from the input stream and returns the value as an Integer.
    Date
    readGeneralizedTime()
    Reads an ASN.1 generalized time element from the input stream and returns the value as a Date.
    Integer
    readInteger()
    Reads an ASN.1 integer element from the input stream and returns the value as an Integer.
    Long
    readLong()
    Reads an ASN.1 integer element from the input stream and returns the value as a Long.
    void
    readNull()
    Reads an ASN.1 null element from the input stream.
    String
    readString()
    Reads an ASN.1 octet string element from the input stream and returns the value as a String using the UTF-8 encoding.
    Date
    readUTCTime()
    Reads an ASN.1 UTC time element from the input stream and returns the value as a Date.
    void
    setIgnoreSocketTimeout(boolean ignoreSocketTimeout)
    Deprecated.
    Use the setIgnoreSocketTimeout(boolean,boolean) method instead.
    void
    setIgnoreSocketTimeout(boolean ignoreInitialSocketTimeout, boolean ignoreSubsequentSocketTimeout)
    Indicates whether to ignore java.net.SocketTimeoutException exceptions that may be caught during processing.

    Methods inherited from class java.lang.Object

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

  • Constructor Details

    • ASN1StreamReader

      public ASN1StreamReader(@NotNull InputStream inputStream)
      Creates a new ASN.1 stream reader that will read data from the provided input stream. It will use a maximum element size equal to the default value returned by the LDAPConnectionOptions.getMaxMessageSize() method.
      Parameters:
      inputStream - The input stream from which data should be read. If the provided input stream does not support the use of the mark and reset methods, then it will be wrapped with a BufferedInputStream.

    • ASN1StreamReader

      public ASN1StreamReader(@NotNull InputStream inputStream, int maxElementSize)
      Creates a new ASN.1 stream reader that will read data from the provided input stream. It will use a maximum element size of Integer.MAX_VALUE.
      Parameters:
      inputStream - The input stream from which data should be read. If the provided input stream does not support the use of the mark and reset methods, then it will be wrapped with a BufferedInputStream.
      maxElementSize - The maximum size in bytes of an ASN.1 element that may be read. A value less than or equal to zero will be interpreted as Integer.MAX_VALUE.

  • Method Details

    • close

      public void close() throws IOException
      Closes this ASN.1 stream reader and the underlying input stream. This reader must not be used after it has been closed.
      Specified by:
      close in interface AutoCloseable
      Specified by:
      close in interface Closeable
      Throws:
      IOException - If a problem occurs while closing the underlying input stream.

    • ignoreSocketTimeoutException

      @Deprecated public boolean ignoreSocketTimeoutException()
      Deprecated.
      Use the ignoreInitialSocketTimeoutException() and ignoreSubsequentSocketTimeoutException() methods instead.
      Indicates whether to ignore java.net.SocketTimeoutException exceptions that may be caught during processing.
      Returns:
      true if SocketTimeoutException exceptions should be ignored, or false if they should not be ignored and should be propagated to the caller.

    • ignoreInitialSocketTimeoutException

      public boolean ignoreInitialSocketTimeoutException()
      Indicates whether to ignore java.net.SocketTimeoutException exceptions that may be caught while trying to read the first byte of an element.
      Returns:
      true if SocketTimeoutException exceptions should be ignored while trying to read the first byte of an element, or false if they should not be ignored and should be propagated to the caller.

    • ignoreSubsequentSocketTimeoutException

      public boolean ignoreSubsequentSocketTimeoutException()
      Indicates whether to ignore java.net.SocketTimeoutException exceptions that may be caught while trying to read subsequent bytes of an element (after one or more bytes have already been read for that element).
      Returns:
      true if SocketTimeoutException exceptions should be ignored while trying to read subsequent bytes of an element, or false if they should not be ignored and should be propagated to the caller.

    • setIgnoreSocketTimeout

      @Deprecated public void setIgnoreSocketTimeout(boolean ignoreSocketTimeout)
      Deprecated.
      Use the setIgnoreSocketTimeout(boolean,boolean) method instead.
      Indicates whether to ignore java.net.SocketTimeoutException exceptions that may be caught during processing.
      Parameters:
      ignoreSocketTimeout - Indicates whether to ignore SocketTimeoutException exceptions that may be caught during processing.

    • setIgnoreSocketTimeout

      public void setIgnoreSocketTimeout(boolean ignoreInitialSocketTimeout, boolean ignoreSubsequentSocketTimeout)
      Indicates whether to ignore java.net.SocketTimeoutException exceptions that may be caught during processing.
      Parameters:
      ignoreInitialSocketTimeout - Indicates whether to ignore SocketTimeoutException exceptions that may be caught while trying to read the first byte of an element.
      ignoreSubsequentSocketTimeout - Indicates whether to ignore SocketTimeoutException exceptions that may be caught while reading beyond the first byte of an element.

    • peek

      public int peek() throws IOException
      Peeks at the next byte to be read from the input stream without actually consuming it.
      Returns:
      An integer value encapsulating the BER type of the next element in the input stream, or -1 if the end of the input stream has been reached and there is no data to be read. If a value of -1 is returned, then the input stream will not have been closed since this method is not intended to have any impact on the underlying input stream.
      Throws:
      IOException - If a problem occurs while reading from the input stream.

    • readElement

      @Nullable public ASN1Element readElement() throws IOException
      Reads a complete ASN.1 element from the input stream.
      Returns:
      The ASN.1 element read from the input stream, or null if the end of the input stream was reached before any data could be read. If null is returned, then the input stream will have been closed.
      Throws:
      IOException - If a problem occurs while reading from the input stream, if the end of the input stream is reached in the middle of the element, or or if an attempt is made to read an element larger than the maximum allowed size.

    • readBoolean

      @Nullable public Boolean readBoolean() throws IOException, ASN1Exception
      Reads an ASN.1 Boolean element from the input stream and returns the value as a Boolean.
      Returns:
      The Boolean value of the ASN.1 Boolean element read, or null if the end of the input stream was reached before any data could be read. If null is returned, then the input stream will have been closed.
      Throws:
      IOException - If a problem occurs while reading from the input stream, if the end of the input stream is reached in the middle of the element, or or if an attempt is made to read an element larger than the maximum allowed size.
      ASN1Exception - If the data read cannot be parsed as an ASN.1 Boolean element.

    • readEnumerated

      @Nullable public Integer readEnumerated() throws IOException, ASN1Exception
      Reads an ASN.1 enumerated element from the input stream and returns the value as an Integer.
      Returns:
      The Integer value of the ASN.1 enumerated element read, or null if the end of the input stream was reached before any data could be read. If null is returned, then the input stream will have been closed.
      Throws:
      IOException - If a problem occurs while reading from the input stream, if the end of the input stream is reached in the middle of the element, or or if an attempt is made to read an element larger than the maximum allowed size.
      ASN1Exception - If the data read cannot be parsed as an ASN.1 enumerated element.

    • readGeneralizedTime

      @Nullable public Date readGeneralizedTime() throws IOException, ASN1Exception
      Reads an ASN.1 generalized time element from the input stream and returns the value as a Date.
      Returns:
      The Date value of the ASN.1 generalized time element read, or null if the end of the input stream was reached before any data could be read. If null is returned, then the input stream will have been closed.
      Throws:
      IOException - If a problem occurs while reading from the input stream, if the end of the input stream is reached in the middle of the element, or or if an attempt is made to read an element larger than the maximum allowed size.
      ASN1Exception - If the data read cannot be parsed as an ASN.1 generalized time element.

    • readInteger

      @Nullable public Integer readInteger() throws IOException, ASN1Exception
      Reads an ASN.1 integer element from the input stream and returns the value as an Integer.
      Returns:
      The Integer value of the ASN.1 integer element read, or null if the end of the input stream was reached before any data could be read. If null is returned, then the input stream will have been closed.
      Throws:
      IOException - If a problem occurs while reading from the input stream, if the end of the input stream is reached in the middle of the element, or or if an attempt is made to read an element larger than the maximum allowed size.
      ASN1Exception - If the data read cannot be parsed as an ASN.1 integer element.

    • readLong

      @Nullable public Long readLong() throws IOException, ASN1Exception
      Reads an ASN.1 integer element from the input stream and returns the value as a Long.
      Returns:
      The Long value of the ASN.1 integer element read, or null if the end of the input stream was reached before any data could be read. If null is returned, then the input stream will have been closed.
      Throws:
      IOException - If a problem occurs while reading from the input stream, if the end of the input stream is reached in the middle of the element, or or if an attempt is made to read an element larger than the maximum allowed size.
      ASN1Exception - If the data read cannot be parsed as an ASN.1 integer element.

    • readBigInteger

      @Nullable public BigInteger readBigInteger() throws IOException, ASN1Exception
      Reads an ASN.1 integer element from the input stream and returns the value as a BigInteger.
      Returns:
      The BigInteger value of the ASN.1 integer element read, or null if the end of the input stream was reached before any data could be read. If null is returned, then the input stream will have been closed.
      Throws:
      IOException - If a problem occurs while reading from the input stream, if the end of the input stream is reached in the middle of the element, or or if an attempt is made to read an element larger than the maximum allowed size.
      ASN1Exception - If the data read cannot be parsed as an ASN.1 integer element.

    • readNull

      public void readNull() throws IOException, ASN1Exception
      Reads an ASN.1 null element from the input stream. No value will be returned but the null element will be consumed.
      Throws:
      IOException - If a problem occurs while reading from the input stream, if the end of the input stream is reached in the middle of the element, or or if an attempt is made to read an element larger than the maximum allowed size.
      ASN1Exception - If the data read cannot be parsed as an ASN.1 null element.

    • readBytes

      @Nullable public byte[] readBytes() throws IOException
      Reads an ASN.1 octet string element from the input stream and returns the value as a byte array.
      Returns:
      The byte array value of the ASN.1 octet string element read, or null if the end of the input stream was reached before any data could be read. If null is returned, then the input stream will have been closed.
      Throws:
      IOException - If a problem occurs while reading from the input stream, if the end of the input stream is reached in the middle of the element, or or if an attempt is made to read an element larger than the maximum allowed size.

    • readString

      @Nullable public String readString() throws IOException
      Reads an ASN.1 octet string element from the input stream and returns the value as a String using the UTF-8 encoding.
      Returns:
      The String value of the ASN.1 octet string element read, or null if the end of the input stream was reached before any data could be read. If null is returned, then the input stream will have been closed.
      Throws:
      IOException - If a problem occurs while reading from the input stream, if the end of the input stream is reached in the middle of the element, or or if an attempt is made to read an element larger than the maximum allowed size.

    • readUTCTime

      @Nullable public Date readUTCTime() throws IOException, ASN1Exception
      Reads an ASN.1 UTC time element from the input stream and returns the value as a Date.
      Returns:
      The Date value of the ASN.1 UTC time element read, or null if the end of the input stream was reached before any data could be read. If null is returned, then the input stream will have been closed.
      Throws:
      IOException - If a problem occurs while reading from the input stream, if the end of the input stream is reached in the middle of the element, or or if an attempt is made to read an element larger than the maximum allowed size.
      ASN1Exception - If the data read cannot be parsed as an ASN.1 UTC time element.

    • beginSequence

      @Nullable public ASN1StreamReaderSequence beginSequence() throws IOException
      Reads the beginning of an ASN.1 sequence from the input stream and returns a value that can be used to determine when the end of the sequence has been reached. Elements which are part of the sequence may be read from this ASN.1 stream reader until the ASN1StreamReaderSequence.hasMoreElements() method returns false.
      Returns:
      An object which may be used to determine when the end of the sequence has been reached, or null if the end of the input stream was reached before any data could be read. If null is returned, then the input stream will have been closed.
      Throws:
      IOException - If a problem occurs while reading from the input stream, if the end of the input stream is reached in the middle of the element, or or if an attempt is made to read an element larger than the maximum allowed size.

    • beginSet

      @Nullable public ASN1StreamReaderSet beginSet() throws IOException
      Reads the beginning of an ASN.1 set from the input stream and returns a value that can be used to determine when the end of the set has been reached. Elements which are part of the set may be read from this ASN.1 stream reader until the ASN1StreamReaderSet.hasMoreElements() method returns false.
      Returns:
      An object which may be used to determine when the end of the set has been reached, or null if the end of the input stream was reached before any data could be read. If null is returned, then the input stream will have been closed.
      Throws:
      IOException - If a problem occurs while reading from the input stream, if the end of the input stream is reached in the middle of the element, or or if an attempt is made to read an element larger than the maximum allowed size.