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

java.lang.Object
- iaik.cms.DataStream

All Implemented Interfaces:

ContentStream

Direct Known Subclasses:

Data
```
public class DataStream
extends java.lang.Object
implements ContentStream
```
This class represents the stream-implementation of the CMS content type Data.
Each CMS 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".

The Cryptographic Message Syntax (CMS, RFC 2630) specifies the Data content type as base type without any cryptographic enhancements. Please note that in difference to PKCS#7, CMS specifies the Data as arbitrary octet strings, such as ASCII text files; the interpretation is left to the application. From this point of view the CMS type Data itself does not have an ASN.1 respresentation in contrast to its PKCS#7 equivalent where Data is defined as ASN.1 OCTET STRING:
Data ::= OCTET STRING
This class only may be used for compatibility to PKCS#7 for allowing to include Data(Stream) objects into ContentInfo(Stream)s. Within SignedData or EnvelopedData objects the internal content always is wrapped by an EncapsulatedContentInfo object. Since an EncapsulatedContentInfo anytime is encoded as OCTET STRING backwards compatibility to PKCS#7 is preserved even when the inner content type is Data
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 CMS 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

Constructor Summary

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

Method Summary

Methods
Modifier and Type	Method and Description
`void`	`decode(java.io.InputStream is)` Reads and decodes the BER encoded Data from an input stream.
`int`	`getBlockSize()` Gets the block size defining the length of each definite primitive encoded octet string component.
`ObjectID`	`getContentType()` Returns the object identifier of this CMS `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 CMS `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 CMS `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 ContentInfoStream. Shall be not used by an application.
  - DataStream
```
public DataStream(java.io.InputStream is,
          int blockSize)
```
    Creates a new CMS Data from an InputStream supplying the raw content data. 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 not splitting the encoding, when being not positive
  - DataStream
```
public DataStream(java.io.InputStream is)
           throws java.io.IOException,
                  CMSParsingException
```
    Creates a new CMS 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
    
    CMSParsingException - if an error occurs while parsing the object
- Method Detail
  - decode
```
public void decode(java.io.InputStream is)
            throws java.io.IOException,
                   CMSParsingException
```
    Reads and decodes the BER encoded Data from an input stream.
    
    Specified by:
    
    decode in interface ContentStream
    
    Parameters:
    is - the InputStream holding a BER encoded CMS Data object
    
    Throws:
    
    java.io.IOException - if an I/O error occurs during reading from the InputStream
    
    CMSParsingException - if an error occurs while parsing the object
  - 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
  - getBlockSize
```
public int getBlockSize()
```
    Gets the block size 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. This method may be used for enforcing block encoding when wrapping the Data into a ContentInfo.
    
    Specified by:
    
    getBlockSize in interface ContentStream
    
    Returns:
    blockSize defining the encoding scheme and setting the octet string component length, if positive
  - getContentType
```
public ObjectID getContentType()
```
    Returns the object identifier of this CMS Data.
    
    Specified by:
    
    getContentType in interface ContentStream
    
    Returns:
    ObjectID.cms_data
  - 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 CMSException
```
    Returns this CMS 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:
    
    CMSException - if the ASN1Object could not be created
  - writeTo
```
public void writeTo(java.io.OutputStream os)
             throws CMSException,
                    java.io.IOException
```
    Writes this CMS 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:
    the - output stream to which to encode the data
    IOException - if an error occurs during writing to the stream
    
    Throws:
    
    CMSException - if an encoding error occurs
    
    java.io.IOException
  - 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

getBlockSize

getContentType

getInputStream

toASN1Object

writeTo

toString

toString