Package com.unboundid.asn1

Class ASN1StreamReader

  • All Implemented Interfaces:
    java.io.Closeable, java.lang.AutoCloseable
    @Mutable
@ThreadSafety(level=NOT_THREADSAFE)
public final class ASN1StreamReader
extends java.lang.Object
implements java.io.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​(java.io.InputStream inputStream)
      Creates a new ASN.1 stream reader that will read data from the provided input stream.
      ASN1StreamReader​(java.io.InputStream inputStream, int maxElementSize)
      Creates a new ASN.1 stream reader that will read data from the provided input stream.

    • Method Summary

      All Methods Instance Methods Concrete Methods Deprecated Methods 
      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.
      java.math.BigInteger readBigInteger()
      Reads an ASN.1 integer element from the input stream and returns the value as a BigInteger.
      java.lang.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.
      java.lang.Integer readEnumerated()
      Reads an ASN.1 enumerated element from the input stream and returns the value as an Integer.
      java.util.Date readGeneralizedTime()
      Reads an ASN.1 generalized time element from the input stream and returns the value as a Date.
      java.lang.Integer readInteger()
      Reads an ASN.1 integer element from the input stream and returns the value as an Integer.
      java.lang.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.
      java.lang.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.
      java.util.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 Detail

      • ASN1StreamReader

        public ASN1StreamReader​(java.io.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 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.

      • ASN1StreamReader

        public ASN1StreamReader​(java.io.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 Detail

      • close

        public void close()
           throws java.io.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 java.lang.AutoCloseable
        Specified by:
        close in interface java.io.Closeable
        Throws:
        java.io.IOException - If a problem occurs while closing the underlying input stream.

      • 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 java.io.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:
        java.io.IOException - If a problem occurs while reading from the input stream.

      • readElement

        public ASN1Element readElement()
                        throws java.io.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:
        java.io.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

        public java.lang.Boolean readBoolean()
                              throws java.io.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:
        java.io.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

        public java.lang.Integer readEnumerated()
                                 throws java.io.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:
        java.io.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

        public java.util.Date readGeneralizedTime()
                                   throws java.io.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:
        java.io.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

        public java.lang.Integer readInteger()
                              throws java.io.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:
        java.io.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

        public java.lang.Long readLong()
                        throws java.io.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:
        java.io.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

        public java.math.BigInteger readBigInteger()
                                    throws java.io.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:
        java.io.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 java.io.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:
        java.io.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

        public byte[] readBytes()
                 throws java.io.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:
        java.io.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

        public java.lang.String readString()
                            throws java.io.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:
        java.io.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

        public java.util.Date readUTCTime()
                           throws java.io.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:
        java.io.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

        public ASN1StreamReaderSequence beginSequence()
                                       throws java.io.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:
        java.io.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

        public ASN1StreamReaderSet beginSet()
                             throws java.io.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:
        java.io.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.