com.unboundid.asn1

Class ASN1StreamReader

java.lang.Object

com.unboundid.asn1.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 and 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

Modifier and Type	Method and 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(@NotNull
                        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 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
                        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.io.Closeable

Specified by:

close in interface java.lang.AutoCloseable

Throws:

java.io.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 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

@Nullable
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

@Nullable
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

@Nullable
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

@Nullable
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

@Nullable
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

@Nullable
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

@Nullable
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

@Nullable
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

@Nullable
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

@Nullable
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

@Nullable
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

@Nullable
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.