com.unboundid.asn1
Class ASN1StreamReader

java.lang.Object
  extended by com.unboundid.asn1.ASN1StreamReader

@Mutable
@ThreadSafety(level=NOT_THREADSAFE)
public final class ASN1StreamReader
extends java.lang.Object

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

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

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.

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.

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.

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.