DataStream ("Entrust Authority Security Toolkit for the Java Platform")

java.lang.Object
- iaik.pkcs.pkcs7.DataStream

All Implemented Interfaces:

ContentStream
```
public class DataStream
extends java.lang.Object
implements ContentStream
```
This class represents the stream-implementation of the PKCS#7 content type Data.
Each PKCS#7 content type is associated with a specific object identifier, derived from:
```
 pkcs-7 OBJECT IDENTIFIER ::=
   { iso(1) member-body(2) US(840) rsadsi(113549)
       pkcs(1) 7 }
 
```
The object identifier for the Data content type is defined as:
data OBJECT IDENTIFIER ::= { pkcs-7 1 }
which corresponds to the OID string "1.2.840.1.113549.1.7.1".
PKCS #7: Cryptographic Message Syntax Version 1.5 (RFC 2315) specifies the Data content type as base type without any cryptographic enhancements:
Data ::= OCTET STRING
Use the DataStream(InputStream is, int blockSize) constructor to create a new DataStream object for the given raw data supplying input stream:
```
 InputStream input_stream = ...;
 int blockSize = ...;
 DataStream data_stream = new DataStream(InputStream, blockSize);
 
```
If blockSize is set to a positive value, the data is BER encoded as indefinite constructed octet string being composed of a series of definite primitive encoded octet strings of blockSize length:
```
 0x24 0x80
           0x04 <blocksize> <data>
           0x04 <blocksize> <data>
           0x04 <blocksize> <data>
                ...
 0x00 0x00
 
```
However, if blockSize is not positive, whole the data is encoded as one single primitive definite octet string, which may cause a memory overflow when dealing with large data volumes (consult the documentation of the ContentStream class for more information about the difference between the two encoding schemes).
In contrast to the non-stream variant of the PKCS#7 Data type (implemented by the Data class), where the raw data is supplied as byte array and therefore can be accessed arbitrarily often, it is important to keep in mind that now for the DataStream class, the raw data carrying input stream only can be read once, which shall not be done before actually performing the encoding (again, see ContentStream)!
After writing a DataStream object BER encoded to an output stream by calling the writeTo method, it may be read back, decoded and re-parsed again by means of the DataStream(InputStream is) constructor. In this case, the getInputStream method may be used for reading the raw data included in the received DataStream object.
See Also:

ContentStream, ContentInfoStream, OCTET_STRING

Constructor Summary

Constructors
Modifier	Constructor and Description
`protected`	`DataStream()` Default constructor for dynamic object creation in ContentInfo.
	`DataStream(java.io.InputStream is)` Creates a new PKCS#7 data from a BER encoded InputStream.
	`DataStream(java.io.InputStream is, int blockSize)` Creates a new PKCS#7 Data from an InputStream supplying the raw content data.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`decode(java.io.InputStream is)` Reads and decodes the Data from a DerInputStream.
`ObjectID`	`getContentType()` Returns the object identifier of this PKCS#7 `Data`.
`java.io.InputStream`	`getInputStream()` Returns an InputStream where the contents of this object can be read.
`void`	`setBlockSize(int blockSize)` Sets the block size for defining the length of each definite primitive encoded octet string component.
`ASN1Object`	`toASN1Object()` Returns this PKCS#7 `Data` as ASN1Object.
`java.lang.String`	`toString()` Returns a string giving some information about this `DataStream` object.
`java.lang.String`	`toString(boolean detailed)` Returns a string giving some - if requested - detailed information about this `DataStream` object.
`void`	`writeTo(java.io.OutputStream os)` Writes this PKCS#7 `DataStream` object BER encoded to the given output stream.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Constructor Detail
  - DataStream
```
protected DataStream()
```
    Default constructor for dynamic object creation in ContentInfo.
  - DataStream
```
public DataStream(java.io.InputStream is,
                  int blockSize)
```
    Creates a new PKCS#7 Data from an InputStream supplying the raw content data. If the value of blockSize is smaller or equal to zero, the data will be DER encoded as primitive definite OCTET STRING when writing it to a stream by means of the writeTo method. However, if blockSize is set to a positive value, the data will be BER encoded as indefinite constructed octet string being composed of a series of definite primitive encoded octet strings of blockSize length:
```
 0x24 0x80
           0x04 <blocksize> <data>
           0x04 <blocksize> <data>
           0x04 <blocksize> <data>
                ...
 0x00 0x00
 
```
    Parameters:
    
    is - the stream containing the content
    
    blockSize - the block size defining the length of each primitive definite encoded octet string component; or initiating an entire primitive definite encoding, when being not positive
    
    See Also:
    
    OCTET_STRING
  - DataStream
```
public DataStream(java.io.InputStream is)
           throws java.io.IOException,
                  PKCSParsingException
```
    Creates a new PKCS#7 data from a BER encoded InputStream. Do not use this constructor for supplying the content value. This constructor may be used for decoding and parsing an already exisiting DataStream object, supplied as BER encoded input stream that may have been created by calling writeTo.
    Use the DataStream(InputStream is, int blockSize) constructor for supplying the content data when creating a DataStream object.
    
    Throws:
    
    java.io.IOException - if an I/O error occurs during reading from the InputStream
    
    PKCSParsingException - if an error occurs while parsing the object
- Method Detail
  - decode
```
public void decode(java.io.InputStream is)
            throws java.io.IOException,
                   PKCSParsingException
```
    Reads and decodes the Data from a DerInputStream. If the supplied InputStream actually is not an instance of DerInputStream, internally a DerInputStream is created before parsing the data.
    
    Specified by:
    
    decode in interface ContentStream
    
    Parameters:
    
    is - the InputStream holding a DER encoded PKCS#7 Data object
    
    Throws:
    
    java.io.IOException - if an I/O error occurs during reading from the InputStream
    
    PKCSParsingException - if an error occurs while parsing the object
    
    See Also:
    
    DerInputStream
  - setBlockSize
```
public void setBlockSize(int blockSize)
```
    Sets the block size for defining the length of each definite primitive encoded octet string component. If the value of blockSize is smaller or equal to zero the whole data is encoded as definite primitive octet string.
    
    Specified by:
    
    setBlockSize in interface ContentStream
    
    Parameters:
    
    blockSize - for defining the encoding scheme and setting the octet string component length, if positive
    
    See Also:
    
    OCTET_STRING
  - getContentType
```
public ObjectID getContentType()
```
    Returns the object identifier of this PKCS#7 Data.
    
    Specified by:
    
    getContentType in interface ContentStream
    
    Returns:
    
    ObjectID.pkcs7_data
    
    See Also:
    
    ObjectID
  - getInputStream
```
public java.io.InputStream getInputStream()
```
    Returns an InputStream where the contents of this object can be read. Attention! The stream only may be read once.
    When having created a new DataStream object to be encoded to a stream, this method should not be utilized at all, since the stream automatically will be read during performing the encoding (which is done when calling the writeTo method).
    When having decoded and parsed a DataStream object coming from some stream, this method may be used for reading the raw data.
    
    Returns:
    
    an InputStream with the contents of this object
  - toASN1Object
```
public ASN1Object toASN1Object()
                        throws PKCSException
```
    Returns this PKCS#7 Data as ASN1Object. From the internal value an ASN.1 OCTET STRING object is created. If block size has a value > 0 a constructed OCTET STRING is created.
    
    Specified by:
    
    toASN1Object in interface ContentStream
    
    Returns:
    
    this Data as ASN1Object
    
    Throws:
    
    PKCSException - if the ASN1Object could not be created
    
    See Also:
    
    OCTET_STRING
  - writeTo
```
public void writeTo(java.io.OutputStream os)
             throws PKCSException,
                    java.io.IOException
```
    Writes this PKCS#7 DataStream object BER encoded to the given output stream. From the internal value an ASN.1 OCTET STRING object is created, BER encoded and written to the stream. If block size has a value > 0 a constructed OCTET STRING is created. In this case the encoding is splitted according to the defined block size:
```
 0x24 0x80
           0x04 <blocksize> <data>
           0x04 <blocksize> <data>
           0x04 <blocksize> <data>
                ...
 0x00 0x00
 
```
    If the block size is not positive, whole the data is encoded as one single primitive definite octet string:
```
 0x04 <length> <data>
 
```
    Parameters:
    
    os - the output stream to which to encode the data
    
    Throws:
    
    PKCSException - if an encoding error occurs
    
    java.io.IOException - if an error occurs during writing to the stream
    
    See Also:
    
    OCTET_STRING
  - toString
```
public java.lang.String toString()
```
    Returns a string giving some information about this DataStream object.
    
    Overrides:
    
    toString in class java.lang.Object
    
    Returns:
    
    the string representation
  - toString
```
public java.lang.String toString(boolean detailed)
```
    Returns a string giving some - if requested - detailed information about this DataStream object.
    
    Specified by:
    
    toString in interface ContentStream
    
    Parameters:
    
    detailed - - whether or not to give detailed information
    
    Returns:
    
    the string representation

Class DataStream

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

DataStream

DataStream

DataStream

Method Detail

decode

setBlockSize

getContentType

getInputStream

toASN1Object

writeTo

toString

toString